Merge pull request #41 from oracle/release_2018-01-11

Releasing version 1.3.12

Author: benthamc

CHANGELOG.rst

@@ -4,6 +4,30 @@ 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.12 - 2018-01-11
+====================
+
+Added
+-----
+* Support for tagging:
+
+  * Support for creating, updating, retrieving and listing tags and tag namespaces (these operations can be found in Identity Service)
+  * Support for adding freeform and defined tags to resources in Core Services (Networking, Compute, and Block Volume) and Identity Service
+  * An example on using tagging can be found on `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/tagging.py>`_.
+
+* Support for bringing your own custom image for emulation mode virtual machines in Compute Service
+* Added the ``oci.pagination`` module, which contains convenience functions so that you don't have to manually deal with page tokens when using list operations. See the `documentation <https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/pagination.html>`_ for more information
+
+Changed
+-------
+* Upgraded cryptography dependency to 2.1.3
+
+  * Added dependency on pyOpenSSL <= 17.4.0 as the minimum cryptography version for pyOpenSSL 17.5.0 is 2.1.4
+
+* Upgraded six dependency to 1.11.0
+* Ugraded requests dependency to 2.18.4
+
 ====================
 1.3.11 - 2017-12-11
 ====================

CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 Contributing to the Oracle Cloud Infrastructure Python SDK
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.*
+*Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.*
 
 Pull requests can be made under
 `The Oracle Contributor Agreement <https://www.oracle.com/technetwork/community/oca-486395.html>`_ (OCA).

LICENSE.txt

@@ -1,9 +1,9 @@
-Copyright (c) 2016, 2017, Oracle and/or its affiliates.  All rights reserved.
+Copyright (c) 2016, 2018, Oracle and/or its affiliates.  All rights reserved.
 
 This software is dual-licensed to you under the Universal Permissive License (UPL) and Apache License 2.0.  See below for license terms.  You may choose either license, or both.
  ____________________________
 The Universal Permissive License (UPL), Version 1.0
-Copyright (c) 2016, 2017, Oracle and/or its affiliates.  All rights reserved.
+Copyright (c) 2016, 2018, Oracle and/or its affiliates.  All rights reserved.
 
 Subject to the condition set forth below, permission is hereby granted to any person obtaining a copy of this software, associated documentation and/or data (collectively the "Software"), free of charge and under any and all copyright rights in the Software, and any and all patent rights owned or freely licensable by each licensor hereunder covering either (i) the unmodified Software as contributed to or provided by such licensor, or (ii) the Larger Works (as defined below), to deal in both
 
@@ -19,7 +19,7 @@ The above copyright notice and either this complete permission notice or at a mi
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 The Apache Software License, Version 2.0
-Copyright (c) 2016, 2017, Oracle and/or its affiliates.  All rights reserved.
+Copyright (c) 2016, 2018, Oracle and/or its affiliates.  All rights reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License"); You may not use this product except in compliance with the License.  You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.  A copy of the license is also reproduced below.  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and  limitations under the License.
 

README.rst

@@ -113,7 +113,7 @@ __ https://github.com/oracle/oci-python-sdk
 License
 =======
 
-Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 
 This SDK and sample is dual licensed under the Universal Permissive License 1.0 and the Apache License 2.0.
 

docs/api/index.rst

@@ -234,6 +234,17 @@ Load Balancer
 
 .. autofunction:: wait_until
 
+===========
+ Pagination
+===========
+
+.. module:: oci.pagination
+
+.. autofunction:: list_call_get_all_results
+.. autofunction:: list_call_get_up_to_limit
+.. autofunction:: list_call_get_all_results_generator
+.. autofunction:: list_call_get_up_to_limit_generator
+
 =========
 Request
 =========

docs/conf.py

@@ -4,6 +4,8 @@
 import pkg_resources
 import sphinx_rtd_theme
 
+from sphinx.domains.python import PythonDomain
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -236,3 +238,20 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+
+class PatchedPythonDomain(PythonDomain):
+    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+        if 'refspecific' in node and fromdocname == 'api/index':
+            # This for api/index.rst and defined tags. These have a data type of dict(str, dict(str, object)) but if
+            # Sphinx auto-linking tries to link "object" to the "object" property in CreateMultipartUploadDetails (which is
+            # incorrect).
+            #
+            # This prevents any non-explicit link (e.g. just plain "object") from being linked across, but if I was
+            # explicit like "oci.object_storage.models.CreateMultipartUploadDetails.object" that **should** still produce
+            # a link
+            if node['reftarget'] == 'object' and not node['refexplicit']:
+                del node['refspecific']
+        return super(PatchedPythonDomain, self).resolve_xref(env, fromdocname, builder, typ, target, node, contnode)
+    
+def setup(sphinx):
+    sphinx.override_domain(PatchedPythonDomain)

docs/index.rst

@@ -53,6 +53,7 @@ To get started, head over to the :ref:`installation instructions <install>` or s
     upload-manager
     raw-requests
     waiters
+    pagination
     api/index
     contributions
     notifications

docs/installation.rst

@@ -105,7 +105,7 @@ The supported version of OpenSSL for the Python SDK is version 1.0.1 or newer.
 
 If the version is lower than ``1.0.1``, run the following command to bypass the version issue::
 
-    pip install requests[security]==2.11.1
+    pip install requests[security]==2.18.4
 
 This command instructs the `requests <https://pypi.python.org/pypi/requests>`_
 library used by the Python SDK to use the version of OpenSSL that is bundled with the `cryptography <https://pypi.python.org/pypi/cryptography>`_

docs/pagination.rst

@@ -0,0 +1,22 @@
+.. 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>
+
+Pagination
+~~~~~~~~~~~~
+When you call a list operation (for example :py:func:`~oci.core.compute_client.ComputeClient.list_instances`) will retrieve a page of results. In order
+to retrieve more data, you have to continue to make calls to the list operation, passing in the value of the most recent response's ``next_page`` attribute 
+as a parameter to the next list operation call.
+
+As a convenience over manually writing pagination code, you can make use of the functions in the :py:mod:`~oci.pagination` module to:
+
+* 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
+
+For an example on how to use these functions, please check `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/pagination.py>`_.

docs/waiters.rst

@@ -34,6 +34,24 @@ Sometimes you may need to wait until an attribute of a resource, such as an inst
     #   - The fourth parameter is the desired value. An equality (==) comparison is done
     get_instance_response = oci.wait_until(client, client.get_instance(instance_ocid), 'lifecycle_state', 'RUNNING')
 
+Instead of waiting for a single attribute to equal a given value, you can also provide a function reference (either a lambda or a reference to an already defined function) that
+can be used to evaluate the response received from the service call. This function should return a truthy value if the waiter should stop waiting, and a falsey value if the waiter
+should continue waiting. 
+
+For example, to wait until a volume backup reaches either the "AVAILABLE" or "FAULTY" state :
+
+.. code-block:: python
+
+    oci.wait_until(client, client.get_volume_backup(vol_backup_id), evaluate_response=lambda r: r.data.lifecycle_state in ['AVAILABLE', 'FAULTY'])
+
+Instead of using a lambda, an already defined function can be used:
+
+.. code-block:: python
+
+    def should_stop_waiting_volume_backup(response):
+        return response.data.lifecycle_state in ['AVAILABLE', 'FAULTY']
+
+    oci.wait_until(client, client.get_volume_backup(vol_backup_id), evaluate_response=should_stop_waiting_volume_backup)
 
 In addition to the base parameters shown above, the function can accept optional attributes to control the maximum amount of time it will wait for and the time between calls to the service. For more information on the optional parameters, see the documentation on the :py:func:`~oci.wait_until` function.