release 1.1.1

Author: ahosler

README-development.rst

@@ -8,16 +8,17 @@ If you want to use the SDK with your own programs, see README.rst.
 
 Getting Started
 ===============
-Assuming that you have Python and `virtualenv` installed, set up your environment and install the required dependencies like this:
+Assuming that you have Python and `conda` installed, set up your environment and install the required dependencies like this:
 
 .. code-block:: sh
 
     git clone https://github.com/oracle/ocifs.git
     cd ocifs
-    virtualenv ocifs-env
-    . ocifs-env/bin/activate
+    conda create python=3.8 --name ocifs -y
+    conda activate ocifs
     python3 -m pip install -r requirements.txt
-    python3 -m pip install -e .
+    python3 -m pip install -r requirements-dev.txt
+    python3 -m pip install -r docs/requirements.txt
 
 You should also set up your configuration files, see the `SDK and CLI Configuration File`__.
 

README.md

@@ -32,6 +32,18 @@ python3 -m pip install ocifs
 ## Software Prerequisites:
 Python >= 3.6
 
+## Environment Variables for Authentication:
+```bash
+export OCIFS_IAM_TYPE=api_key
+export OCIFS_CONFIG_LOCATION=~/.oci/config
+export OCIFS_CONFIG_PROFILE=DEFAULT
+```
+
+Note, if you are operating on OCI with an alternative valid signer, such as resource principal, instead set the following:
+```bash
+export OCIFS_IAM_TYPE=resource_principal
+```
+
 ## Documentation:
 [ocifs Documentation](https://ocifs.readthedocs.io/en/latest/index.html)
 [![PyPI](https://img.shields.io/pypi/v/ocifs.svg)](https://pypi.org/project/ocifs/)

docs/requirements.txt

@@ -3,4 +3,5 @@ nbsphinx
 pandoc
 ipython
 sphinx_rtd_theme
--e .
+autodoc
+sphinxcontrib-napoleon

docs/source/conf.py

@@ -27,6 +27,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinxcontrib.napoleon",
     "nbsphinx",
     "sphinx_rtd_theme",
 ]

docs/source/faqs.rst

@@ -0,0 +1,32 @@
+Frequently Asked Questions
+---------------------------
+
+
+**Is ocifs asynchronous?**
+
+No. Ocifs currently inherits the AbstractFile and AbstractFileSystem classes, rather than the Async versions of these. This development may happen in the future if there's enough interest.
+
+
+**Does ocifs use multipart uploads?**
+
+Yes. Ocifs uses multipart uploads to upload files to Object Storage when the file is larger than 5 GB.
+
+
+**Can I bring my own signer?**
+
+Yes. Whether you want to use Resource Principal, Instance Principal, or some other type of OCI signer, simply pass that signer to the OCIFileSystem init method.
+
+
+**Can I use ocifs with a different region?**
+
+Yes, pass this region into the OCIFileSystem init method, and ensure your auth credentials work cross-region.
+
+
+**Can I use ocifs with a different tenancy?**
+
+Yes, pass this tenancy into the OCIFileSystem init method, and ensure your auth credentials work cross-region.
+
+
+**Can I set auth once and forget?**
+
+Yes, you can use environment variables: `OCIFS_IAM_TYPE`, `OCIFS_CONFIG_LOCATION`, `OCIFS_CONFIG_PROFILE`. Read more in the Getting Connected section.

docs/source/faqs_title.rst

@@ -0,0 +1,7 @@
+FAQS
+=====
+
+.. toctree::
+   :maxdepth: 4
+
+   faqs

docs/source/getting-connected.ipynb

@@ -1,14 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "5f14c5a8",
-   "metadata": {},
-   "source": [
-    "Copyright (c) 2021, 2022 Oracle and/or its affiliates.\n",
-    "Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "serial-equivalent",
@@ -85,7 +76,7 @@
    "metadata": {},
    "source": [
     "### Using Environment Variables\n",
-    "From version 1.1.0, users can provide default authentication configuration details as enviornment variables.\n",
+    "Users can provide default authentication configuration details as enviornment variables.\n",
     "The following environment variables are inspected:\n",
     "\n",
     "* `OCIFS_IAM_TYPE`: which can be any of: [\"api_key\", \"resource_principal\", \"instance_principal\", \"unknown_signer\"]\n",

docs/source/getting-started.ipynb

@@ -2,18 +2,9 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "909f1aef",
    "metadata": {},
    "source": [
-    "Copyright (c) 2021, 2022 Oracle and/or its affiliates.\n",
-    "Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Getting Started with ocifs\n",
+    "## Getting Started\n",
     "\n",
     "The Oracle Cloud Infrastructure (OCI) Object Storage filesystem (ocifs) is an fsspec implementation for use with Object Storage."
    ]
@@ -95,85 +86,6 @@
     "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": "code",
-   "execution_count": 5,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\u001b[0;31mInit signature:\u001b[0m \u001b[0mocifs\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mOCIFileSystem\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m*\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-       "\u001b[0;31mDocstring:\u001b[0m     \n",
-       "Access oci as if it were a file system.\n",
-       "This exposes a filesystem-like API (ls, cp, open, etc.) on top of oci\n",
-       "storage.\n",
-       "Parameters\n",
-       "----------\n",
-       "config : Union[dict, str, None]\n",
-       "    Config for the connection to OCI. \n",
-       "    If a dict, it should be returned from oci.config.from_file\n",
-       "    If a str, it should be the location of the config file\n",
-       "    If None, user should have a Resource Principal configured environment\n",
-       "profile : str\n",
-       "    The profile to use from the config (If the config is passed in)\n",
-       "default_block_size: int (None)\n",
-       "    If given, the default block size value used for ``open()``, if no\n",
-       "    specific value is given at all time. The built-in default is 5MB.\n",
-       "config_kwargs : dict of parameters passed to the OCI Client upon connection\n",
-       "    This will first scan for `profile` (in the case of a passed in config)\n",
-       "    Or `resource_principal_token_path_provider` (in the case of no config)\n",
-       "    The rest will be passed to the ObjectStorageClient\n",
-       "    more info here: oci.object_storage.ObjectStorageClient.__init__\n",
-       "oci_additional_kwargs : dict of parameters that are used when calling oci api\n",
-       "    methods. Typically used for things like \"retry_strategy\" or .\n",
-       "kwargs : other parameters for oci session\n",
-       "    This includes default parameters for tenancy, namespace, and region\n",
-       "    Any other parameters are passed along to AbstractFileSystem's init method.\n",
-       "Examples\n",
-       "--------\n",
-       ">>> fs = OCIFileSystem(config=config)  # doctest: +SKIP\n",
-       ">>> fs.ls('my-bucket@my-namespace/')  # doctest: +SKIP\n",
-       "['my-file.txt']\n",
-       ">>> with fs.open('my-bucket@my-namespace/my-file.txt', mode='rb') as f:  # doctest: +SKIP\n",
-       "...     print(f.read())  # doctest: +SKIP\n",
-       "b'Hello, world!'\n",
-       "\u001b[0;31mInit docstring:\u001b[0m\n",
-       "Create and configure file-system instance\n",
-       "\n",
-       "Instances may be cachable, so if similar enough arguments are seen\n",
-       "a new instance is not required. The token attribute exists to allow\n",
-       "implementations to cache instances if they wish.\n",
-       "\n",
-       "A reasonable default should be provided if there are no arguments.\n",
-       "\n",
-       "Subclasses should call this method.\n",
-       "\n",
-       "Parameters\n",
-       "----------\n",
-       "use_listings_cache, listings_expiry_time, max_paths:\n",
-       "    passed to ``DirCache``, if the implementation supports\n",
-       "    directory listing caching. Pass use_listings_cache=False\n",
-       "    to disable such caching.\n",
-       "skip_instance_cache: bool\n",
-       "    If this is a cachable implementation, pass True here to force\n",
-       "    creating a new instance even if a matching instance exists, and prevent\n",
-       "    storing this instance.\n",
-       "asynchronous: bool\n",
-       "loop: asyncio-compatible IOLoop or None\n",
-       "\u001b[0;31mFile:\u001b[0m           ~/ocifs/ocifs/core.py\n",
-       "\u001b[0;31mType:\u001b[0m           _Cached\n",
-       "\u001b[0;31mSubclasses:\u001b[0m     \n"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
-   "source": [
-    "ocifs.OCIFileSystem?"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/source/index.rst

@@ -177,7 +177,9 @@ Contents
    getting-started.ipynb
    getting-connected.ipynb
    unix-operations.ipynb
-   :maxdepth: 2
+   modules.rst
+   faqs_title.rst
+   :maxdepth: 4
 
 
 Indices and tables

docs/source/modules.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 4
+
+   ocifs