Merge pull request #45 from oracle/release_2018-01-25

Releasing version 1.3.13

Author: benthamc

CHANGELOG.rst

@@ -4,6 +4,18 @@ 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.13 - 2018-01-25
+====================
+
+Added
+-----
+* Support for using the ``ObjectReadWithoutList`` public access type when creating and updating buckets
+* Support for dynamic groups in Identity Service
+* Support for instance principals authentication when calling OCI services. An example of how to use instance principals authentication can be found on `GitHub <https://github.com/oracle/oci-python-sdk/blob/master/examples/instance_principals_examples.py>`_.
+* Support for configuring idle timeout for listeners in Load Balancer Service 
+* Support for VNC console connections in Compute Service
+
 ====================
 1.3.12 - 2018-01-11
 ====================

docs/api/index.rst

@@ -216,6 +216,58 @@ Load Balancer
 
 .. autoclass:: Signer
 
+=====================
+ Additional Signers
+=====================
+
+.. module:: oci.auth.signers
+
+.. autoclass:: SecurityTokenSigner
+      :special-members: __init__
+      :members:
+
+.. autoclass:: X509FederationClientBasedSecurityTokenSigner
+      :special-members: __init__
+      :members:
+
+.. autoclass:: InstancePrincipalsSecurityTokenSigner
+      :special-members: __init__
+      :members:
+
+============================
+X509 Certificate Retrievers
+============================
+
+.. module:: oci.auth.certificate_retriever
+
+.. autoclass:: UrlBasedCertificateRetriever
+      :special-members: __init__
+      :members:
+
+.. autoclass:: PEMStringCertificateRetriever
+      :special-members: __init__
+      :members:
+
+.. autoclass:: FileBasedCertificateRetriever
+      :special-members: __init__
+      :members:
+
+====================================
+X509 Certificate Federation Client
+====================================
+
+.. module:: oci.auth.federation_client
+
+.. autoclass:: X509FederationClient
+      :special-members: __init__
+      :members:
+
+.. module:: oci.auth.session_key_supplier
+
+.. autoclass:: SessionKeySupplier
+      :special-members: __init__
+      :members:
+
 ===========
  Utilities
 ===========

docs/conf.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+import datetime
 import sys
 import pkg_resources
 import sphinx_rtd_theme
@@ -22,7 +23,7 @@
 
 # General information about the project.
 project = "oci"
-copyright = "2016, 2017, Oracle"
+copyright = "2016, {}, Oracle".format(datetime.datetime.now().year)
 author = "Oracle"
 
 try:

docs/index.rst

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

docs/sdk-with-proxy.rst

@@ -0,0 +1,32 @@
+.. _sdk-with-proxy:
+
+.. 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>
+
+Using the SDK with a proxy server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Python SDK uses the `Requests <http://docs.python-requests.org/en/master/>`_ library to make calls to OCI services. If your environment requires you to use a proxy server for outgoing HTTP requests 
+then you can set this up in the following ways:
+
+* Configuring environment variable as described `here <http://docs.python-requests.org/en/master/user/advanced/#proxies>`_
+* Modifying the underlying Requests `Session <http://docs.python-requests.org/en/master/api/#request-sessions>`_ object for a service client
+
+In order to modify the underlying Session object, you can do something similar to:
+
+.. code-block:: python
+
+    import oci
+
+    config = oci.config.from_file()
+    compute = oci.core.ComputeClient(config)
+
+    compute.base_client.session.proxies = { 'https': 'proxy.example.org:80' }
+
+The key parts are that the underlying Session object can be accessed via ``base_client.session`` and we can then modify the `proxies <http://docs.python-requests.org/en/master/api/#requests.Session.proxies>`_
+dictionary to add any required proxies.

examples/instance_principals_examples.py

@@ -0,0 +1,26 @@
+# coding: utf-8
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+import oci
+
+compartment_id = '<your compartment id here>'
+
+# By default this will hit the auth service in the region returned by http://169.254.169.254/opc/v1/instance/region on the instance.
+signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
+
+# In the base case, configuration does not need to be provided as the region and tenancy are obtained from the InstancePrincipalsSecurityTokenSigner
+identity_client = oci.identity.IdentityClient(config={}, signer=signer)
+
+print(identity_client.list_regions().data)
+print(identity_client.list_availability_domains(compartment_id=compartment_id).data)
+
+# If you explicitly specify a region in configuration, it will be honoured. In the below example, you can also change the region later by doing:
+#
+#   object_storage_client.base_client.set_region('us-ashburn-1')
+#
+# You can also explicitly set an endpoint via:
+#
+#   object_storage_client.base_client.set_endpoint('https://<some endpoint>')
+object_storage_client = oci.object_storage.ObjectStorageClient(config={'region': 'us-ashburn-1'}, signer=signer)
+print(object_storage_client.get_namespace().data)
+print(object_storage_client.list_buckets(namespace_name=object_storage_client.get_namespace().data, compartment_id=compartment_id).data)

requirements.txt

@@ -5,6 +5,7 @@ cryptography==2.1.3
 flake8==3.5.0
 httpsig_cffi==15.0.0
 mock==2.0.0
+PyJWT==1.5.3
 pyOpenSSL==17.4.0
 pytest==3.2.3
 pytest-catchlog==1.2.2
@@ -15,4 +16,5 @@ sphinx-rtd-theme==0.1.9
 six==1.11.0
 sphinx==1.6.4
 tox==2.9.1
-wheel==0.29.0
+vcrpy==1.11.1
+wheel==0.29.0

setup.py

@@ -33,6 +33,7 @@ def open_relative(*path):
     "configparser==3.5.0",
     "cryptography==2.1.3",
     "httpsig_cffi==15.0.0",
+    "PyJWT==1.5.3",
     "pyOpenSSL<=17.4.0",
     "python-dateutil==2.5.3",
     "pytz==2016.10",

src/oci/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 
 from . import audit, core, database, identity, load_balancer, object_storage
-from . import config, constants, decorators, exceptions, regions, pagination
+from . import auth, config, constants, decorators, exceptions, regions, pagination, retry
 from .base_client import BaseClient
 from .request import Request
 from .response import Response
@@ -12,6 +12,6 @@
 
 
 __all__ = [
-    "BaseClient", "Error", "Request", "Response", "Signer", "config", "constants", "decorators", "exceptions", "regions", "wait_until", "pagination",
+    "BaseClient", "Error", "Request", "Response", "Signer", "config", "constants", "decorators", "exceptions", "regions", "wait_until", "pagination", "auth", "retry",
     "audit", "core", "database", "identity", "load_balancer", "object_storage"
 ]

src/oci/audit/audit_client.py

@@ -3,8 +3,10 @@
 
 from __future__ import absolute_import
 
+import requests  # noqa: F401
 import six
 
+from .. import retry  # noqa: F401
 from ..base_client import BaseClient
 from ..config import get_config_value_or_default, validate_config
 from ..signer import Signer
@@ -15,16 +17,19 @@
 
 class AuditClient(object):
 
-    def __init__(self, config):
-        validate_config(config)
-        signer = Signer(
-            tenancy=config["tenancy"],
-            user=config["user"],
-            fingerprint=config["fingerprint"],
-            private_key_file_location=config.get("key_file"),
-            pass_phrase=get_config_value_or_default(config, "pass_phrase"),
-            private_key_content=config.get("key_content")
-        )
+    def __init__(self, config, **kwargs):
+        validate_config(config, signer=kwargs.get('signer'))
+        if 'signer' in kwargs:
+            signer = kwargs['signer']
+        else:
+            signer = Signer(
+                tenancy=config["tenancy"],
+                user=config["user"],
+                fingerprint=config["fingerprint"],
+                private_key_file_location=config.get("key_file"),
+                pass_phrase=get_config_value_or_default(config, "pass_phrase"),
+                private_key_content=config.get("key_content")
+            )
         self.base_client = BaseClient("audit", config, signer, audit_type_mapping)
 
     def get_configuration(self, compartment_id, **kwargs):
@@ -42,9 +47,11 @@ def get_configuration(self, compartment_id, **kwargs):
         resource_path = "/configuration"
         method = "GET"
 
-        if kwargs:
+        expected_kwargs = ["retry_strategy"]
+        extra_kwargs = [key for key in six.iterkeys(kwargs) if key not in expected_kwargs]
+        if extra_kwargs:
             raise ValueError(
-                "get_configuration got unknown kwargs: {!r}".format(kwargs))
+                "get_configuration got unknown kwargs: {!r}".format(extra_kwargs))
 
         query_params = {
             "compartmentId": compartment_id
@@ -56,12 +63,21 @@ def get_configuration(self, compartment_id, **kwargs):
             "content-type": "application/json"
         }
 
-        return self.base_client.call_api(
-            resource_path=resource_path,
-            method=method,
-            query_params=query_params,
-            header_params=header_params,
-            response_type="Configuration")
+        if 'retry_strategy' in kwargs:
+            return kwargs['retry_strategy'].make_retrying_call(
+                self.base_client.call_api,
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                response_type="Configuration")
+        else:
+            return self.base_client.call_api(
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                response_type="Configuration")
 
     def list_events(self, compartment_id, start_time, end_time, **kwargs):
         """
@@ -101,6 +117,7 @@ def list_events(self, compartment_id, start_time, end_time, **kwargs):
 
         # Don't accept unknown kwargs
         expected_kwargs = [
+            "retry_strategy",
             "page",
             "opc_request_id"
         ]
@@ -124,12 +141,21 @@ def list_events(self, compartment_id, start_time, end_time, **kwargs):
         }
         header_params = {k: v for (k, v) in six.iteritems(header_params) if v is not missing}
 
-        return self.base_client.call_api(
-            resource_path=resource_path,
-            method=method,
-            query_params=query_params,
-            header_params=header_params,
-            response_type="list[AuditEvent]")
+        if 'retry_strategy' in kwargs:
+            return kwargs['retry_strategy'].make_retrying_call(
+                self.base_client.call_api,
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                response_type="list[AuditEvent]")
+        else:
+            return self.base_client.call_api(
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                response_type="list[AuditEvent]")
 
     def update_configuration(self, compartment_id, update_configuration_details, **kwargs):
         """
@@ -149,9 +175,11 @@ def update_configuration(self, compartment_id, update_configuration_details, **k
         resource_path = "/configuration"
         method = "PUT"
 
-        if kwargs:
+        expected_kwargs = ["retry_strategy"]
+        extra_kwargs = [key for key in six.iterkeys(kwargs) if key not in expected_kwargs]
+        if extra_kwargs:
             raise ValueError(
-                "update_configuration got unknown kwargs: {!r}".format(kwargs))
+                "update_configuration got unknown kwargs: {!r}".format(extra_kwargs))
 
         query_params = {
             "compartmentId": compartment_id
@@ -163,9 +191,18 @@ def update_configuration(self, compartment_id, update_configuration_details, **k
             "content-type": "application/json"
         }
 
-        return self.base_client.call_api(
-            resource_path=resource_path,
-            method=method,
-            query_params=query_params,
-            header_params=header_params,
-            body=update_configuration_details)
+        if 'retry_strategy' in kwargs:
+            return kwargs['retry_strategy'].make_retrying_call(
+                self.base_client.call_api,
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                body=update_configuration_details)
+        else:
+            return self.base_client.call_api(
+                resource_path=resource_path,
+                method=method,
+                query_params=query_params,
+                header_params=header_params,
+                body=update_configuration_details)