{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Started\n",
    "\n",
    "The Oracle Cloud Infrastructure (OCI) Object Storage filesystem (ocifs) is an fsspec implementation for use with Object Storage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quickstart with Pandas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Begin by importing `ocifs` and `pandas`. When importing `ocifs`, you are registering the `oci` protocol with `pandas`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ocifs\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that the `oci` protocol is registered with `pandas`, you can read and write from and to Object Storage as easily as you can locally. For example, you could read an Excel file, `path/file.xls`, from your bucket in a namespace easily using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_excel(\"oci://bucket@namespace/path/file.xls\",\n",
    "                   storage_options={\"config\": \"~/.oci/config\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.to_parquet(\"oci://bucket@namespace/path/file.parquet\",\n",
    "              storage_options={\"config\": \"~/.oci/config\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You could also use [Dask](https://docs.dask.org/en/latest/index.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from dask import dataframe as dd\n",
    "\n",
    "ddf = dd.read_csv(\"oci://bucket@namespace/path/file*.csv\",\n",
    "                  storage_options={\"config\": \"~/.oci/config\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `storage_options` parameter contains a dictionary of arguments that are passed to the underlying `OCIFileSystem` method. The following `docstring` lists the valid arguments to storage options:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quickstart to UNIX Operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can interact with the filesytem directly using most UNIX commands like `ls`, `cp`, `exists`, `mkdir`, `rm`, `walk`, `find`, and so on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate a filesystem from your configuration, see Getting Connected. Every filesystem instance operates within the home region of the configuration. The `cp` command is the only command that has cross-region support. You must create a unique filesystem instance for each region."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs = ocifs.OCIFileSystem(config=\"~/.oci/config\", profile=\"DEFAULT\", default_block_size=5*2**20)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.ls(\"oci://bucket@namespace/path\")\n",
    "# []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.touch(\"oci://bucket@namespace/path/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.exists(\"oci://bucket@namespace/path/file.txt\")\n",
    "# True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.cat(\"oci://bucket@namespace/path/file.txt\")\n",
    "# \"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.rm(\"oci://bucket@namespace\", recursive=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fs.exists(\"oci://bucket@namespace/path/file.txt\")\n",
    "# False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Following are examples of how you can use the `OCIFileSystem` and `OCIFile` objects."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ds",
   "language": "python",
   "name": "ds"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}