Merge pull request #48 from oracle/release_2018-02-22

Releasing version 1.3.15

Author: nathan-vu

.gitignore

@@ -19,5 +19,9 @@ env/
 docs/warnings.txt
 docs/_build/
 docs/apidocs/
-oraclebmc/models/init_*
 tests/resources/test_debug.log
+tests/resources/*.bin
+tests/temp
+.vscode/
+.wercker/
+temp

CHANGELOG.rst

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 The format is based on `Keep a Changelog <http://keepachangelog.com/>`_.
 
+====================
+1.3.15 - 2018-02-22
+====================
+
+Added
+-----
+* Support for File Storage Service
+  
+  * An example on using the File Storage Service can be found on `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/file_storage_example.py>`__.
+
+* Added support for tagging Bucket resources in the Object Storage Service
+
+  * An example on tagging buckets can be found on `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/object_storage_bucket_tagging_example.py>`__.
+
+* Added support  for specifying a restore period for archived objects in the ``RestoreObjects`` operation of the Object Storage service.
+
+  * An example on using archive storage can be found on `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/object_storage_archive_example.py>`__.
+
 ====================
 1.3.14 - 2018-02-08
 ====================

docs/api/index.rst

@@ -117,6 +117,28 @@ Virtual Network
     :imported-members:
     :inherited-members:
 
+==============
+ File Storage
+==============
+
+--------
+ Client
+--------
+
+.. autoclass:: oci.file_storage.file_storage_client.FileStorageClient
+    :members:
+
+--------
+ Models
+--------
+
+.. automodule:: oci.file_storage.models
+    :special-members: __init__
+    :members:
+    :undoc-members:
+    :imported-members:
+    :inherited-members:
+
 ==========
  Identity
 ==========

docs/customize_service_client/connection_read_timeout.rst

@@ -0,0 +1,35 @@
+.. _read-connection-timeout:
+
+.. raw:: html
+
+    <script type='text/javascript'>
+        var oldDocsHost = 'oracle-bare-metal-cloud-services-python-sdk';
+        if (window.location.href.indexOf(oldDocsHost) != -1) {
+            window.location.href = 'https://oracle-bare-metal-cloud-services-python-sdk.readthedocs.io/en/latest/deprecation-notice.html';
+        }
+    </script>
+
+Setting connection and read timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Python SDK uses the `Requests <http://docs.python-requests.org/en/master/>`_ library to make calls to OCI services. The SDK uses the Requests `definition <http://docs.python-requests.org/en/master/user/advanced/#timeouts>`_ for connection and read timeouts.
+
+By default, calls made to OCI services have no connection or read timeout associated with them (i.e. it is possible to wait forever for a response). If you wish to override this default behaviour and set a timeout, you can do something similar to:
+
+.. code-block:: python
+
+    import oci
+
+    config = oci.config.from_file()
+    compute = oci.core.ComputeClient(config)
+    
+    # This will set a value of 5 seconds to the connection and read timeout
+    compute.base_client.timeout = 5
+
+    # This will set the connection timeout to 2 seconds and the read timeout to 25 seconds
+    compute.base_client.timeout = (2, 25)
+
+
+You can modify the ``timeout`` attribute of the ``base_client`` to customize our connection and read timeouts. This attribute takes input in the same format as `Requests <http://docs.python-requests.org/en/master/>`_ does, namely:
+
+* A single value will be applied to both the connection and read timeouts
+* If a tuple is provided then the first value is used as the connection timeout and the second as the read timeout

docs/customize_service_client/index.rst

@@ -0,0 +1,18 @@
+.. _customize-service-client:
+
+
+Customizing Service Clients
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SDK service clients can be customized in the following ways:
+
+* :doc:`Setting connection and read timeouts for requests </customize_service_client/connection_read_timeout>`
+* :doc:`Using the SDK with a proxy server </sdk-with-proxy>`
+* :doc:`Injecting custom headers into requests </customize_service_client/setting_custom_headers>`
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    connection_read_timeout
+    /sdk-with-proxy
+    setting_custom_headers

docs/customize_service_client/setting_custom_headers.rst

@@ -0,0 +1,29 @@
+.. _setting-custom-headers:
+
+.. raw:: html
+
+    <script type='text/javascript'>
+        var oldDocsHost = 'oracle-bare-metal-cloud-services-python-sdk';
+        if (window.location.href.indexOf(oldDocsHost) != -1) {
+            window.location.href = 'https://oracle-bare-metal-cloud-services-python-sdk.readthedocs.io/en/latest/deprecation-notice.html';
+        }
+    </script>
+
+Setting custom headers
+~~~~~~~~~~~~~~~~~~~~~~~
+The Python SDK uses the `Requests <http://docs.python-requests.org/en/master/>`_ library to make calls to OCI services. If you need to add custom headers to your calls, you can do so via modifying the underlying Requests `Session <http://docs.python-requests.org/en/master/api/#request-sessions>`_ object
+
+.. code-block:: python
+
+    import oci
+
+    config = oci.config.from_file()
+    compute = oci.core.ComputeClient(config)
+
+    # Adds my-custom-header as a header in the request. This header will be included in ALL
+    # subsequent calls made
+    compute.base_client.session.headers['my-custom-header'] = 'my custom header value'
+
+    # If you no longer want to send the header then remove it from the dictionary
+    compute.base_client.session.headers.pop('my-custom-header')
+

docs/index.rst

@@ -54,8 +54,8 @@ To get started, head over to the :ref:`installation instructions <install>` or s
     raw-requests
     waiters
     pagination
-    sdk-with-proxy
     api/index
+    customize_service_client/index
     contributions
     notifications
     license

docs/quickstart.rst

@@ -104,30 +104,24 @@ compartment:
 Even though a response includes a next page, there may not be more results.  The last page will return an empty list,
 and will not have a ``next_page`` token.
 
-Here's a very simple way to paginate a call:
+You can manually iterate through responses, providing the page from the previous response to the next request. For example:
 
 .. code-block:: python
 
-    def paginate(operation, *args, **kwargs):
-        while True:
-            response = operation(*args, **kwargs)
-            for value in response.data:
-                yield value
-            kwargs["page"] = response.next_page
-            if not response.has_next_page:
-                break
+    response = identity.list_users(compartment_id)
+    users = response.data
+    while response.has_next_page:
+        response = identity.list_users(compartment_id, page=response.next_page)
+        users.extend(response.data)
 
-To iterate over all users, the call is now:
 
-.. code-block:: pycon
+As a convenience over manually writing pagination code, you can make use of the functions in the :py:mod:`~oci.pagination` module to:
 
-    >>> for user in paginate(
-    ...         identity.list_users,
-    ...         compartment_id=compartment_id):
-    ...     print(user)
+* Eagerly load all possible results from a list call
+* Eagerly load all results from a list call up to a given limit
+* Lazily load results (either all results, or up to a given limit) from a list call via a generator. These generators can yield either values/models or the raw response from calling the list operation
 
-This ``paginate`` function will work for any list call, but will not include the response metadata, such as headers,
-HTTP status code, or request id.
+For examples on pagination, please check `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/pagination.py>`__.
 
 
 -------------------
@@ -216,7 +210,7 @@ And to get it back:
 ============
 
 Next, head to the `User Guides`_ or jump right into the :ref:`API Reference <api-reference>`
-to explore the available operations for each service, and their parameters. Additional Python examples can be found on `GitHub <https://github.com/oracle/oci-python-sdk/tree/master/examples>`_.
+to explore the available operations for each service, and their parameters. Additional Python examples can be found on `GitHub <https://github.com/oracle/oci-python-sdk/tree/master/examples>`__.
 
 
 .. note::