Metadata-Version: 2.1
Name: azure-core
Version: 1.0.0b4
Summary: Microsoft Azure Core Library for Python
Home-page: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/core/azure-core
Author: Microsoft Corporation
Author-email: azpysdkhelp@microsoft.com
License: MIT License
Description: 
        
        # Azure Core Library
        
        ## Pipeline
        
        The Azure Core pipeline is a re-structuring of the msrest pipeline introduced in msrest 0.6.0.
        Further discussions on the msrest implementation can be found in the [msrest wiki](https://github.com/Azure/msrest-for-python/wiki/msrest-0.6.0---Pipeline).
        
        The Azure Core Pipeline is an implementation of chained policies as described in the [Azure SDK guidelines](https://github.com/Azure/azure-sdk/tree/master/docs/design).
        
        The Python implementation of the pipeline has some mechanisms specific to Python. This is due to the fact that both synchronous and asynchronous implementations of the pipeline must be supported independently.
        
        When constructing an SDK, a developer may consume the pipeline like so:
        
        ```python
        from azure.core.configuration import Configuration
        from azure.core.pipeline import Pipeline
        from azure.core.transport import RequestsTransport, HttpRequest
        from azure.core.pipeline.policies import (
            UserAgentPolicy,
            HeadersPolicy,
            RetryPolicy,
            RedirectPolicy,
            BearerTokenCredentialPolicy,
            ContentDecodePolicy,
            NetworkTraceLoggingPolicy,
            ProxyPolicy
        )
        
        class FooServiceClient:
        
            @staticmethod
            def _create_config(credential, scopes, **kwargs):
                # Here the SDK developer would define the default
                # config to interact with the service
                config = Configuration(**kwargs)
                config.headers_policy = kwargs.get('headers_policy', HeadersPolicy({"CustomHeader": "Value"}, **kwargs))
                config.user_agent_policy = kwargs.get('user_agent_policy', UserAgentPolicy("ServiceUserAgentValue", **kwargs))
                config.authentication_policy = kwargs.get('authentication_policy', BearerTokenCredentialPolicy(credential, scopes, **kwargs))
                config.retry_policy = kwargs.get('retry_policy', RetryPolicy(**kwargs))
                config.redirect_policy = kwargs.get('redirect_policy', RedirectPolicy(**kwargs))
                config.logging_policy = kwargs.get('logging_policy', NetworkTraceLoggingPolicy(**kwargs))
                config.proxy_policy = kwargs.get('proxy_policy', ProxyPolicy(**kwargs))
                return config
        
            def __init__(self, **kwargs):
                transport = kwargs.get('transport', RequestsTransport(**kwargs))
                config = FooServiceClient._create_config(**kwargs)
                policies = [
                    config.user_agent_policy,
                    config.headers_policy,
                    config.authentication_policy,
                    ContentDecodePolicy(),
                    config.proxy_policy,
                    config.redirect_policy,
                    config.retry_policy,
                    config.logging_policy,
                ]
                self._pipeline = Pipeline(transport, policies=policies)
        
            def get_foo_properties(self, **kwargs)
                # Create a generic HTTP Request. This is not specific to any particular transport
                # or pipeline configuration.
                new_request = HttpRequest("GET", "/")
        
                response = self._pipeline.run(new_request, **kwargs)
                return deserialize_data(response.http_response)
        ```
        
        An end user consuming this SDK may write code like so:
        ```python
        from azure.core.credentials import FooCredentials
        from azure.foo import FooServiceClient
        
        creds = FooCredentials("api-key")
        endpoint = "http://service.azure.net
        
        # Scenario using entirely default configuration
        # We use the SDK-developer defined configuration.
        client = FooServiceClient(endpoint, creds)
        response = client.get_foo_properties()
        
        # Scenario where user wishes to tweak a couple of settings
        # In this case the configurable options can be passed directly into the client constructor.
        client = FooServiceClient(endpoint, creds, logging_enable=True, retries_total=5)
        response = client.get_foo_properties()
        
        # Scenario where user wishes to tweak settings for only a specific request
        # All the options available on construction are available as per-request overrides.
        # These can also be specified by the SDK developer - and it will be up to them to resolve
        # conflicts with user-defined parameters.
        client = FooServiceClient(endpoint, creds)
        response = client.get_foo_properties(redirects_max=0)
        
        # Scenario where user wishes to fully customize the policies.
        # All configuration options are passed through kwargs
        client = FooServiceClient(
            endpoint,
            creds,
            retry_policy=CustomRetryPolicy()
            redirect_max=5,
            logging_enable=True
        )
        response = client.get_foo_properties()
        ```
        
        ### Configuration
        
        The Configuration object is the home of all the configurable policies in the pipeline.
        A new Configuration object provides *no default policies*.
        It is up to the SDK developer to specify each of the policy defaults as required by the service.
        
        *Configuration should not be exposed as part of the public API of the resulting SDK.*
        
        This can be seen in the above code sample as implemented in a staticmethod on the client class.
        The Configuration object does not specify in what order the policies will be added to the pipeline.
        It is up to the SDK developer to use the policies in the Configuration to construct the pipeline correctly, as well
        as inserting any unexposed/non-configurable policies.
        ```python
        transport = RequestsTransport(**kwargs)
        
        # SDK developer needs to build the policy order for the pipeline.
        config = FooServiceClient._create_config(**kwargs)
        policies = [
            config.headers_policy,
            config.user_agent_policy,
            config.authentication_policy,  # Authentication policy needs to be inserted after all request mutation to accommodate signing.
            ContentDecodePolicy(),
            config.redirect_policy,
            config.retry_policy,
            config.logging_policy,  # Logger should come last to accurately record the request/response as they are on the wire
        ]
        self._pipeline = Pipeline(transport, policies=policies)
        ```
        The policies that should currently be defined on the Configuration object are as follows:
        ```python
        - Configuration.headers_policy  # HeadersPolicy
        - Configuration.retry_policy  # RetryPolicy
        - Configuration.redirect_policy  # RedirectPolicy
        - Configuration.logging_policy  # NetworkTraceLoggingPolicy
        - Configuration.user_agent_policy  # UserAgentPolicy
        - Configuration.proxy_policy  # While this is a ProxyPolicy object, current implementation is transport configuration.
        - Configuration.authentication_policy  # BearerTokenCredentialPolicy
        
        ```
        
        ### Transport
        
        Various combinations of sync/async HTTP libraries as well as alternative event loop implementations are available. Therefore to support the widest range of customer scenarios, we must allow a customer to easily swap out the HTTP transport layer to one of those supported.
        
        The transport is the last node in the pipeline, and adheres to the same basic API as any policy within the pipeline.
        The only currently available transport for synchronous pipelines uses the `Requests` library:
        ```python
        from azure.core.pipeline.transport import RequestsTransport
        synchronous_transport = RequestsTransport()
        ```
        
        For asynchronous pipelines a couple of transport options are available. Each of these transports are interchangable depending on whether the user has installed various 3rd party dependencies (i.e. aiohttp or trio), and the user
        should easily be able to specify their chosen transport. SDK developers should use the `aiohttp` transport as the default for asynchronous pipelines where the user has not specified an alternative.
        ```python
        from azure.foo.aio import FooServiceClient
        from azure.core.pipeline.transport import (
            # Identical implementation as the synchronous RequestsTransport wrapped in an asynchronous using the
            # built-in asyncio event loop.
            AsyncioRequestsTransport,
        
            # Identical implementation as the synchronous RequestsTransport wrapped in an asynchronous using the
            # third party trio event loop.
            TrioRequestsTransport,
        
            # Fully asynchronous implementation using the aiohttp library, using the built-in asyncio event loop.
            AioHttpTransport,
        )
        
        client = FooServiceClient(endpoint, creds, transport=AioHttpTransport())
        response = await client.get_foo_properties()
        ```
        
        Some common properties can be configured on all transports. They must be passed
        as kwargs arguments while building the transport instance. These include the following properties:
        ```python
        transport = AioHttpTransport(
                # The connect and read timeout value. Defaults to 100 seconds.
                connection_timeout=100,
        
                # SSL certificate verification. Enabled by default. Set to False to disable,
                # alternatively can be set to the path to a CA_BUNDLE file or directory with
                # certificates of trusted CAs.
                connection_verify=True,
        
                # Client-side certificates. You can specify a local cert to use as client side
                # certificate, as a single file (containing the private key and the certificate)
                # or as a # tuple of both files' paths.
                connection_cert=None,
        
                # The block size of data sent over the connection. Defaults to 4096 bytes.
                connection_data_block_size=4096
        )
        ```
        
        ### HttpRequest and HttpResponse
        
        The HttpRequest and HttpResponse objects represent a generic concept of HTTP request and response constructs and are in no way tied to a particular transport or HTTP library.
        
        The HttpRequest has the following API. It does not vary between transports:
        ```python
        class HttpRequest(object):
        
            def __init__(self, method, url, headers=None, files=None, data=None):
                self.method = method
                self.url = url
                self.headers = CaseInsensitiveDict(headers)
                self.files = files
                self.data = data
        
            @property
            def body(self):
                return self.data
        
            @body.setter
            def body(self, value):
                self.data = value
        
            def format_parameters(self, params):
                """Format parameters into a valid query string.
                It's assumed all parameters have already been quoted as
                valid URL strings."""
        
            def set_xml_body(self, data):
                """Set an XML element tree as the body of the request."""
        
            def set_json_body(self, data):
                """Set a JSON-friendly object as the body of the request."""
        
            def set_multipart_body(self, data=None):
                """Set form-encoded data as the body of the request.
                Supported content-types are:
                    - application/x-www-form-urlencoded
                    - multipart/form-data
                """
        
            def set_bytes_body(self, data):
                """Set generic bytes as the body of the request."""
        
            def set_multipart_mixed(self, *requests, **kwargs):
                """Set requests for a multipart/mixed body.
                Optionally apply "policies" in kwargs to each request.
                """
        ```
        
        The HttpResponse object on the other hand will generally have a transport-specific derivative.
        This is to accomodate how the data is extracted for the object returned by the HTTP library.
        There is also an async flavor: AsyncHttpResponse. This is to allow for the asynchronous streaming of
        data from the response.
        For example:
        ```python
        from azure.core.pipeline.transport import (
            RequestsTransportResponse,  # HttpResponse
            AioHttpTransportResponse, # AsyncHttpResponse
            TrioRequestsTransportResponse,  # AsyncHttpResponse
            AsyncioRequestsTransportResponse,  # AsyncHttpResponse
        )
        ```
        The API for each of these response types is identical, so the consumer of the Response need not know about these
        particular types.
        
        The HttpResponse has the following API. It does not vary between transports:
        ```python
        class HttpResponse(object):
        
            def __init__(self, request, internal_response):
                self.request = request
                self.internal_response = internal_response  # The object returned by the HTTP library
                self.status_code = None
                self.headers = CaseInsensitiveDict()
                self.reason = None
                self.content_type = None
        
            def body(self):
                """Return the whole body as bytes in memory."""
        
            def text(self, encoding=None):
                """Return the whole body as a string."""
        
            def stream_download(self, chunk_size=None, callback=None):
                """Generator for streaming request body data.
                Should be implemented by sub-classes if streaming download
                is supported.
                For the AsyncHttpResponse object this function will return
                and asynchronous generator.
                """
        
            def parts(self):
                """An iterator of parts if content-type is multipart/mixed.
                For the AsyncHttpResponse object this function will return
                and asynchronous iterator.
                """
        
        ```
        
        ### PipelineRequest and PipelineResponse
        
        These objects provide containers for moving the HttpRequest and HttpResponse through the pipeline.
        While the SDK developer will not construct the PipelineRequest explicitly, they will handle the PipelineResponse
        object that is returned from `pipeline.run()`
        These objects are universal for all transports, both synchronous and asynchronous.
        
        The pipeline request and response containers are also responsible for carrying a `context` object. This is
        transport specific and can contain data persisted between pipeline requests (for example reusing an open connection
        pool or "session"), as well as used by the SDK developer to carry arbitrary data through the pipeline.
        
        The API for PipelineRequest and PipelineResponse is as follows:
        ```python
        class PipelineRequest(object):
        
            def __init__(self, http_request, context):
                self.http_request = http_request  # The HttpRequest
                self.context = context # A transport specific data container object
        
        
        class PipelineResponse(object):
        
            def __init__(self, http_request, http_response, context):
                self.http_request = http_request  # The HttpRequest
                self.http_response = http_response  # The HttpResponse
                self.history = []  # A list of redirect attempts.
                self.context = context  # A transport specific data container object
        ```
        
        ### Policies
        
        The Python pipeline implementation provides two flavors of policy. These are referred to as an HttpPolicy and a SansIOHTTPPolicy.
        
        #### SansIOHTTPPolicy
        
        If a policy just modifies or annotates the request based on the HTTP specification, it's then a subclass of SansIOHTTPPolicy and will work in either Pipeline or AsyncPipeline context.
        This is a simple abstract class, that can act before the request is done, or after. For instance:
        
        - Setting headers in the request
        - Logging the request and/or response
        
        A SansIOHTTPPolicy should implement one or more of the following methods:
        ```python
        def on_request(self, request):
            """Is executed before sending the request to next policy."""
        
        def on_response(self, request, response):
            """Is executed after the request comes back from the policy."""
        
        def on_exception(self, request):
            """Is executed if an exception is raised while executing this policy.
        
            Return True if the exception has been handled and should not
            be forwarded to the caller.
            """
        ```
        
        SansIOHTTPPolicy methods can be declared as coroutines, but then they can only be used with a AsyncPipeline.
        
        Current provided sans IO policies include:
        ```python
        from azure.core.pipeline.policies import (
            HeadersPolicy,  # Add custom headers to all requests
            UserAgentPolicy,  # Add a custom user agent header
            NetworkTraceLoggingPolicy,  # Log request and response contents
            ContentDecodePolicy,  # Mandatory policy for decoding unstreamed response content
        )
        ```
        
        #### HTTPPolicy and AsyncHTTPPolicy
        
        Some policies are more complex, like retry strategy, and need to have control of the HTTP workflow.
        In the current version, they are subclasses of HTTPPolicy or AsyncHTTPPolicy, and can be used only their corresponding synchronous or asynchronous pipeline type.
        
        An HTTPPolicy or AsyncHTTPPolicy must implement the `send` method, and this implementation must in include a call to process the next policy in the pipeline:
        ```python
        class CustomPolicy(HTTPPolicy):
        
            def __init__(self):
                self.next = None  # Will be set when pipeline is instantiated and all the policies chained.
        
            def send(self, request):
                """Mutate the request."""
        
                return self.next.send(request)
        
        class CustomAsyncPolicy(AsyncHTTPPolicy):
        
            async def send(self, request):
                """Mutate the request."""
        
                return await self.next.send(request)
        ```
        
        Currently provided HTTP policies include:
        ```python
        from azure.core.pipeline.policies import (
            RetryPolicy,
            AsyncRetryPolicy,
            RedirectPolicy,
            AsyncRedirectPolicy
        )
        ```
        
        ### The Pipeline
        
        The pipeline itself represents a chain of policies where the final node in the chain is the HTTP transport.
        A pipeline can either be synchronous or asynchronous.
        The pipeline does not expose the policy chain, so individual policies cannot/should not be further
        configured once the pipeline has been instantiated.
        
        The pipeline has a single exposed operation: `run(request)` which will send a new HttpRequest object down
        the pipeline. This operation returns a `PipelineResponse` object.
        
        ```python
        class Pipeline:
            """A pipeline implementation.
        
            This is implemented as a context manager, that will activate the context
            of the HTTP sender.
            """
        
            def __init__(self, transport, policies=None):
                # type: (HttpTransport, List[Union[HTTPPolicy, SansIOHTTPPolicy]]) -> None
                self._impl_policies = []  # type: List[HTTPPolicy]
                self._transport = transport  # type: HTTPPolicy
        
                for policy in (policies or []):
                    if isinstance(policy, SansIOHTTPPolicy):
                        self._impl_policies.append(_SansIOHTTPPolicyRunner(policy))
                    elif policy:
                        self._impl_policies.append(policy)
                for index in range(len(self._impl_policies)-1):
                    self._impl_policies[index].next = self._impl_policies[index+1]
                if self._impl_policies:
                    self._impl_policies[-1].next = _TransportRunner(self._transport)
        
            def run(self, request, **kwargs):
                # type: (HTTPRequestType, Any) -> PipelineResponse
                context = PipelineContext(self._transport, **kwargs)
                pipeline_request = PipelineRequest(request, context)  # type: PipelineRequest[HTTPRequestType]
                first_node = self._impl_policies[0] if self._impl_policies else _TransportRunner(self._transport)
                return first_node.send(pipeline_request)  # type: ignore
        
        ```
        
        
        
        # Release History
        
        -------------------
        
        ## 2019-10-07 Version 1.0.0b4
        
        ### Features
        
        - Tracing: network span context is available with the TRACING_CONTEXT in pipeline response  #7252
        - Tracing: Span contract now has `kind`, `traceparent` and is a context manager  #7252
        - SansIOHTTPPolicy methods can now be coroutines #7497
        - Add multipart/mixed support #7083:
        
          - HttpRequest now has a "set_multipart_mixed" method to set the parts of this request
          - HttpRequest now has a "prepare_multipart_body" method to build final body.
          - HttpResponse now has a "parts" method to return an iterator of parts
          - AsyncHttpResponse now has a "parts" methods to return an async iterator of parts
          - Note that multipart/mixed is a Python 3.x only feature
        
        ### Bug fixes
        
        - Tracing: policy cannot fail the pipeline, even in the worst condition  #7252
        - Tracing: policy pass correctly status message if exception  #7252
        - Tracing: incorrect span if exception raised from decorated function  #7133
        - Fixed urllib3 ConnectTimeoutError being raised by Requests during a socket timeout. Now this exception is caught and wrapped as a `ServiceRequestError`  #7542
        
        ### Breaking changes
        
        - Tracing: `azure.core.tracing.context` removed
        - Tracing: `azure.core.tracing.context.tracing_context.with_current_context` renamed to `azure.core.tracing.common.with_current_context`  #7252
        - Tracing: `link` renamed `link_from_headers`  and `link` takes now a string
        - Tracing: opencensus implementation has been moved to the package `azure-core-tracing-opencensus`
        - Some modules and classes that were importables from several differente places have been removed:
           
           - `azure.core.HttpResponseError` is now only `azure.core.exceptions.HttpResponseError`
           - `azure.core.Configuration` is now only `azure.core.configuration.Configuration`
           - `azure.core.HttpRequest` is now only `azure.core.pipeline.transport.HttpRequest`
           - `azure.core.version` module has been removed. Use `azure.core.__version__` to get version number.
           - `azure.core.pipeline_client` has been removed. Import from `azure.core` instead.
           - `azure.core.pipeline_client_async` has been removed. Import from `azure.core` instead.
           - `azure.core.pipeline.base` has been removed. Import from `azure.core.pipeline` instead.
           - `azure.core.pipeline.base_async` has been removed. Import from `azure.core.pipeline` instead.
           - `azure.core.pipeline.policies.base` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.base_async` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.authentication` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.authentication_async` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.custom_hook` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.redirect` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.redirect_async` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.retry` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.retry_async` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.distributed_tracing` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.pipeline.policies.universal` has been removed. Import from `azure.core.pipeline.policies` instead.
           - `azure.core.tracing.abstract_span` has been removed. Import from `azure.core.tracing` instead.
           - `azure.core.pipeline.transport.base` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.pipeline.transport.base_async` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.pipeline.transport.requests_basic` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.pipeline.transport.requests_asyncio` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.pipeline.transport.requests_trio` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.pipeline.transport.aiohttp` has been removed. Import from `azure.core.pipeline.transport` instead.
           - `azure.core.polling.poller` has been removed. Import from `azure.core.polling` instead.
           - `azure.core.polling.async_poller` has been removed. Import from `azure.core.polling` instead.
        
        ## 2019-09-09 Version 1.0.0b3
        
        ### Bug fixes
        
        -  Fix aiohttp auto-headers #6992
        -  Add tracing to policies module init  #6951
        
        ## 2019-08-05 Version 1.0.0b2
        
        ### Breaking changes
        
        - Transport classes don't take `config` parameter anymore (use kwargs instead)  #6372
        - `azure.core.paging` has been completely refactored  #6420
        - HttpResponse.content_type attribute is now a string (was a list)  #6490
        - For `StreamDownloadGenerator` subclasses, `response` is now an `HttpResponse`, and not a transport response like `aiohttp.ClientResponse` or `requests.Response`. The transport response is available in `internal_response` attribute  #6490
        
        ### Bug fixes
        
        - aiohttp is not required to import async pipelines classes #6496
        - `AsyncioRequestsTransport.sleep` is now a coroutine as expected #6490
        - `RequestsTransport` is not tight to `ProxyPolicy` implementation details anymore #6372
        - `AiohttpTransport` does not raise on unexpected kwargs  #6355
        
        ### Features
        
        - New paging base classes that support `continuation_token` and `by_page()`  #6420
        - Proxy support for `AiohttpTransport`  #6372
        
        ## 2019-06-26 Version 1.0.0b1
        
        - Preview 1 release
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/markdown
