Merge pull request #38 from oracle/release_2017-12-11

Releasing version 1.3.11

Author: benthamc

CHANGELOG.rst

@@ -4,6 +4,25 @@ 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.11 - 2017-12-11
+====================
+
+Added
+-----
+* Support for public peering for FastConnect
+* Support for specifying an authorized entity name in a Letter of Authority
+* Support for showing a list of bandwidth shapes for a specific provider (the ``list_fast_connect_provider_virtual_circuit_bandwidth_shapes`` in ``VirtualNetworkClient``)
+
+Changed
+-------
+* Audit events now have a ``response_payload`` attribute which contains metadata of interest. For example, the OCID of a resource
+
+Deprecated
+-----------
+* The ``list_virtual_circuit_bandwidth_shapes`` operation in ``VirtualNetworkClient`` has been deprecated. Use the ``list_fast_connect_provider_virtual_circuit_bandwidth_shapes`` operation instead
+* When using ``CreateVirtualCircuitDetails``, supplying a ``provider_name`` is deprecated and ``provider_service_id`` should be used instead
+
 ====================
 1.3.10 - 2017-11-27
 ====================

docs/api/index.rst

@@ -226,6 +226,14 @@ Load Balancer
 
 .. autoclass:: Sentinel
 
+===========
+ Waiters
+===========
+
+.. module:: oci
+
+.. autofunction:: wait_until
+
 =========
 Request
 =========

docs/index.rst

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

docs/waiters.rst

@@ -0,0 +1,40 @@
+.. 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>
+
+Waiters
+~~~~~~~
+Sometimes you may need to wait until an attribute of a resource, such as an instance or a VCN, reaches a certain state. An example of this would be launching an instance and then waiting for the instance to become available, or waiting until a subnet in a VCN has been terminated. This waiting can be accomplished by using the :py:func:`~oci.wait_until` function. As an example:
+
+.. code-block:: python
+
+    import oci
+    
+    config = oci.config.from_file()
+    client = oci.core.ComputeClient(config)
+
+    response = client.launch_instance(...)
+    instance_ocid = response.data.id
+
+    # We will get returned the result of the last get_instance call (in this case the one where the lifecycle state has moved to available).
+    # We can inspect the .data attribute of this (i.e. get_instance_response.data) to get information about the instance
+    #
+    # Some items to note about the parameters provided:
+    #
+    #   - The first parameter is the client we'll use to call the service to retrieve data
+    #   - The second parameter is the result of a service call. The wait_until function uses this to determine what service operation needs to be called. In the case below
+    #     it will keep calling client.get_instance(instance_ocid) until the instance reaches the desired state
+    #   - The third parameter is the name of the attribute we will check. The object we will check against is the result of calling .data on the result of the service call.
+    #     Please consult the API reference for available attribute names you can use
+    #   - 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')
+
+
+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. 
+
+For a more comprehensive sample, please see our `examples <https://github.com/oracle/oci-python-sdk/blob/master/examples/wait_for_resource_in_state.py>`_ on GitHub.

examples/wait_for_resource_in_state.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+#
+# This script provides an example on how to use waiters in the Python SDK to block/wait until a resource (e.g. an instance, a VCN)
+# reaches a certain state.
+
+import oci
+
+# Default config file and profile
+config = oci.config.from_file()
+compartment_id = '<Your compartment OCID here>'
+availability_domain = '<An availability domain, e.g. crmS:IAD-AD-1, here>'
+second_availability_domain = '<An availability domain, e.g. crmS:IAD-AD-2, here. This should be different to availability_domain>'
+
+virtual_network_client = oci.core.VirtualNetworkClient(config)
+load_balancer_client = oci.load_balancer.LoadBalancerClient(config)
+
+# This creates a VCN and then waits until the VCN's lifecycle state is AVAILABLE
+print('Creating VCN')
+result = virtual_network_client.create_vcn(oci.core.models.CreateVcnDetails(cidr_block='10.0.0.0/16', display_name='WaitForResourceExampleVcn', compartment_id=compartment_id))
+vcn_ocid = result.data.id
+get_vcn_response = oci.wait_until(virtual_network_client, virtual_network_client.get_vcn(vcn_ocid), 'lifecycle_state', 'AVAILABLE')
+print(get_vcn_response.data)
+
+# This creates a subnet in the VCN and waits until the subnet's lifecycle state is AVAILABLE
+print('Creating Subnet 1')
+result = virtual_network_client.create_subnet(
+    oci.core.models.CreateSubnetDetails(
+        compartment_id=compartment_id,
+        availability_domain=availability_domain,
+        display_name='WaitForResourceExampleSubnet',
+        vcn_id=vcn_ocid,
+        cidr_block='10.0.0.0/24'
+    )
+)
+subnet_ocid = result.data.id
+get_subnet_response = oci.wait_until(virtual_network_client, virtual_network_client.get_subnet(subnet_ocid), 'lifecycle_state', 'AVAILABLE')
+print(get_subnet_response.data)
+
+print('Creating Subnet 2')
+result = virtual_network_client.create_subnet(
+    oci.core.models.CreateSubnetDetails(
+        compartment_id=compartment_id,
+        availability_domain=second_availability_domain,
+        display_name='WaitForResourceExampleSubnet2',
+        vcn_id=vcn_ocid,
+        cidr_block='10.0.1.0/24'
+    )
+)
+subnet_two_ocid = result.data.id
+get_subnet_response = oci.wait_until(virtual_network_client, virtual_network_client.get_subnet(subnet_two_ocid), 'lifecycle_state', 'AVAILABLE')
+print(get_subnet_response.data)
+
+# Now we create a load balancer and wait until it has been created. Load balancers work slightly differently in that the create_load_balancer call
+# returns a work request and it is the work request whose state we should wait on (we wait until it has succeeded)
+print('Creating Load Balancer')
+create_load_balancer_details = oci.load_balancer.models.CreateLoadBalancerDetails(
+    compartment_id=compartment_id,
+    display_name='WaitForResourceExampleLB',
+    shape_name='100Mbps',
+    subnet_ids=[subnet_ocid, subnet_two_ocid],
+    backend_sets={
+        'WaitExampleBackSet': oci.load_balancer.models.BackendSetDetails(
+            policy='ROUND_ROBIN',
+            health_checker=oci.load_balancer.models.HealthCheckerDetails(
+                protocol='HTTP',
+                url_path='/',
+                port=80,
+                retries=1,
+                timeout_in_millis=100,
+                interval_in_millis=1000,
+            ),
+            session_persistence_configuration=oci.load_balancer.models.SessionPersistenceConfigurationDetails(cookie_name='*', disable_fallback=False)
+        )
+    }
+)
+result = load_balancer_client.create_load_balancer(create_load_balancer_details)
+work_request_id = result.headers['opc-work-request-id']
+get_work_request_response = oci.wait_until(load_balancer_client, load_balancer_client.get_work_request(work_request_id), 'lifecycle_state', 'SUCCEEDED')
+print(get_work_request_response.data)
+load_balancer_ocid = get_work_request_response.data.load_balancer_id
+
+# Here we delete the load balancer. Note that on the waiter we use the optional succeed_on_not_found and set it to True. This meants that if we get a
+# 404 back from the service when checking the load balancer's state, instead of throwing an exception we will return successfully. This flag will typically
+# only be useful for delete/terminate scenarios and its normal default is False.
+print('Deleting Load Balancer')
+load_balancer_client.delete_backend_set(load_balancer_ocid, 'WaitExampleBackSet')
+load_balancer_client.delete_load_balancer(load_balancer_ocid)
+oci.wait_until(load_balancer_client, load_balancer_client.get_load_balancer(load_balancer_ocid), 'lifecycle_state', 'TERMINATED', succeed_on_not_found=True)
+
+print('Deleting Subnet 1')
+virtual_network_client.delete_subnet(subnet_ocid)
+oci.wait_until(virtual_network_client, virtual_network_client.get_subnet(subnet_ocid), 'lifecycle_state', 'TERMINATED', succeed_on_not_found=True)
+
+print('Deleting Subnet 2')
+virtual_network_client.delete_subnet(subnet_two_ocid)
+oci.wait_until(virtual_network_client, virtual_network_client.get_subnet(subnet_two_ocid), 'lifecycle_state', 'TERMINATED', succeed_on_not_found=True)
+
+print('Deleting VCN')
+virtual_network_client.delete_vcn(vcn_ocid)
+oci.wait_until(virtual_network_client, virtual_network_client.get_vcn(vcn_ocid), 'lifecycle_state', 'TERMINATED', succeed_on_not_found=True)

src/oci/audit/models/audit_event.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
 
 
-from ...util import formatted_flat_dict
+from ...util import formatted_flat_dict, NONE_SENTINEL, value_allowed_none_or_none_sentinel  # noqa: F401
 from ...decorators import init_model_state_from_kwargs
 
 
@@ -86,6 +86,10 @@ def __init__(self, **kwargs):
             The value to assign to the response_time property of this AuditEvent.
         :type response_time: datetime
 
+        :param response_payload:
+            The value to assign to the response_payload property of this AuditEvent.
+        :type response_payload: dict(str, object)
+
         """
         self.swagger_types = {
             'tenant_id': 'str',
@@ -105,7 +109,8 @@ def __init__(self, **kwargs):
             'request_resource': 'str',
             'response_headers': 'dict(str, list[str])',
             'response_status': 'str',
-            'response_time': 'datetime'
+            'response_time': 'datetime',
+            'response_payload': 'dict(str, object)'
         }
 
         self.attribute_map = {
@@ -126,7 +131,8 @@ def __init__(self, **kwargs):
             'request_resource': 'requestResource',
             'response_headers': 'responseHeaders',
             'response_status': 'responseStatus',
-            'response_time': 'responseTime'
+            'response_time': 'responseTime',
+            'response_payload': 'responsePayload'
         }
 
         self._tenant_id = None
@@ -147,6 +153,7 @@ def __init__(self, **kwargs):
         self._response_headers = None
         self._response_status = None
         self._response_time = None
+        self._response_payload = None
 
     @property
     def tenant_id(self):
@@ -588,6 +595,30 @@ def response_time(self, response_time):
         """
         self._response_time = response_time
 
+    @property
+    def response_payload(self):
+        """
+        Gets the response_payload of this AuditEvent.
+        Metadata of interest from the response payload. For example, the OCID of a resource.
+
+
+        :return: The response_payload of this AuditEvent.
+        :rtype: dict(str, object)
+        """
+        return self._response_payload
+
+    @response_payload.setter
+    def response_payload(self, response_payload):
+        """
+        Sets the response_payload of this AuditEvent.
+        Metadata of interest from the response payload. For example, the OCID of a resource.
+
+
+        :param response_payload: The response_payload of this AuditEvent.
+        :type: dict(str, object)
+        """
+        self._response_payload = response_payload
+
     def __repr__(self):
         return formatted_flat_dict(self)
 

src/oci/audit/models/configuration.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
 
 
-from ...util import formatted_flat_dict
+from ...util import formatted_flat_dict, NONE_SENTINEL, value_allowed_none_or_none_sentinel  # noqa: F401
 from ...decorators import init_model_state_from_kwargs
 
 

src/oci/audit/models/update_configuration_details.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
 
 
-from ...util import formatted_flat_dict
+from ...util import formatted_flat_dict, NONE_SENTINEL, value_allowed_none_or_none_sentinel  # noqa: F401
 from ...decorators import init_model_state_from_kwargs
 
 

src/oci/core/compute_client.py

@@ -2036,6 +2036,7 @@ def terminate_instance(self, instance_id, **kwargs):
 
         :param bool preserve_boot_volume: (optional)
             Specifies whether to delete or preserve the boot volume when terminating an instance.
+            The default value is false.
 
         :return: A :class:`~oci.response.Response` object with data of type None
         :rtype: :class:`~oci.response.Response`

src/oci/core/models/__init__.py

@@ -9,6 +9,8 @@
 from .attach_volume_details import AttachVolumeDetails
 from .boot_volume import BootVolume
 from .boot_volume_attachment import BootVolumeAttachment
+from .bulk_add_virtual_circuit_public_prefixes_details import BulkAddVirtualCircuitPublicPrefixesDetails
+from .bulk_delete_virtual_circuit_public_prefixes_details import BulkDeleteVirtualCircuitPublicPrefixesDetails
 from .capture_console_history_details import CaptureConsoleHistoryDetails
 from .connect_local_peering_gateways_details import ConnectLocalPeeringGatewaysDetails
 from .console_history import ConsoleHistory
@@ -30,6 +32,7 @@
 from .create_subnet_details import CreateSubnetDetails
 from .create_vcn_details import CreateVcnDetails
 from .create_virtual_circuit_details import CreateVirtualCircuitDetails
+from .create_virtual_circuit_public_prefix_details import CreateVirtualCircuitPublicPrefixDetails
 from .create_vnic_details import CreateVnicDetails
 from .create_volume_backup_details import CreateVolumeBackupDetails
 from .create_volume_details import CreateVolumeDetails
@@ -39,6 +42,7 @@
 from .cross_connect_mapping import CrossConnectMapping
 from .cross_connect_port_speed_shape import CrossConnectPortSpeedShape
 from .cross_connect_status import CrossConnectStatus
+from .delete_virtual_circuit_public_prefix_details import DeleteVirtualCircuitPublicPrefixDetails
 from .dhcp_dns_option import DhcpDnsOption
 from .dhcp_option import DhcpOption
 from .dhcp_options import DhcpOptions
@@ -106,6 +110,7 @@
 from .vcn import Vcn
 from .virtual_circuit import VirtualCircuit
 from .virtual_circuit_bandwidth_shape import VirtualCircuitBandwidthShape
+from .virtual_circuit_public_prefix import VirtualCircuitPublicPrefix
 from .vnic import Vnic
 from .vnic_attachment import VnicAttachment
 from .volume import Volume
@@ -123,6 +128,8 @@
     "AttachVolumeDetails": AttachVolumeDetails,
     "BootVolume": BootVolume,
     "BootVolumeAttachment": BootVolumeAttachment,
+    "BulkAddVirtualCircuitPublicPrefixesDetails": BulkAddVirtualCircuitPublicPrefixesDetails,
+    "BulkDeleteVirtualCircuitPublicPrefixesDetails": BulkDeleteVirtualCircuitPublicPrefixesDetails,
     "CaptureConsoleHistoryDetails": CaptureConsoleHistoryDetails,
     "ConnectLocalPeeringGatewaysDetails": ConnectLocalPeeringGatewaysDetails,
     "ConsoleHistory": ConsoleHistory,
@@ -144,6 +151,7 @@
     "CreateSubnetDetails": CreateSubnetDetails,
     "CreateVcnDetails": CreateVcnDetails,
     "CreateVirtualCircuitDetails": CreateVirtualCircuitDetails,
+    "CreateVirtualCircuitPublicPrefixDetails": CreateVirtualCircuitPublicPrefixDetails,
     "CreateVnicDetails": CreateVnicDetails,
     "CreateVolumeBackupDetails": CreateVolumeBackupDetails,
     "CreateVolumeDetails": CreateVolumeDetails,
@@ -153,6 +161,7 @@
     "CrossConnectMapping": CrossConnectMapping,
     "CrossConnectPortSpeedShape": CrossConnectPortSpeedShape,
     "CrossConnectStatus": CrossConnectStatus,
+    "DeleteVirtualCircuitPublicPrefixDetails": DeleteVirtualCircuitPublicPrefixDetails,
     "DhcpDnsOption": DhcpDnsOption,
     "DhcpOption": DhcpOption,
     "DhcpOptions": DhcpOptions,
@@ -220,6 +229,7 @@
     "Vcn": Vcn,
     "VirtualCircuit": VirtualCircuit,
     "VirtualCircuitBandwidthShape": VirtualCircuitBandwidthShape,
+    "VirtualCircuitPublicPrefix": VirtualCircuitPublicPrefix,
     "Vnic": Vnic,
     "VnicAttachment": VnicAttachment,
     "Volume": Volume,