Azure Core shared client library for Python - version 1.32.0

Azure core provides shared exceptions and modules for Python SDK client libraries. These libraries follow the Azure SDK Design Guidelines for Python .

If you are a client library developer, please reference client library developer reference for more information.

Source code | Package (Pypi) | Package (Conda) | API reference documentation

Getting started

Typically, you will not need to install azure core; it will be installed when you install one of the client libraries using it. In case you want to install it explicitly (to implement your own client library, for example), you can find it here.

Key concepts

Azure Core Library Exceptions

AzureError

AzureError is the base exception for all errors.

class AzureError(Exception):
    def __init__(self, message, *args, **kwargs):
        self.inner_exception = kwargs.get("error")
        self.exc_type, self.exc_value, self.exc_traceback = sys.exc_info()
        self.exc_type = self.exc_type.__name__ if self.exc_type else type(self.inner_exception)
        self.exc_msg = "{}, {}: {}".format(message, self.exc_type, self.exc_value)  # type: ignore
        self.message = str(message)
        self.continuation_token = kwargs.get("continuation_token")
        super(AzureError, self).__init__(self.message, *args)

message is any message (str) to be associated with the exception.

args are any additional args to be included with exception.

kwargs are keyword arguments to include with the exception. Use the keyword error to pass in an internal exception and continuation_token for a token reference to continue an incomplete operation.

The following exceptions inherit from AzureError:

ServiceRequestError

An error occurred while attempt to make a request to the service. No request was sent.

ServiceResponseError

The request was sent, but the client failed to understand the response. The connection may have timed out. These errors can be retried for idempotent or safe operations.

HttpResponseError

A request was made, and a non-success status code was received from the service.

class HttpResponseError(AzureError):
    def __init__(self, message=None, response=None, **kwargs):
        self.reason = None
        self.response = response
        if response:
            self.reason = response.reason
            self.status_code = response.status_code
        self.error = self._parse_odata_body(ODataV4Format, response)  # type: Optional[ODataV4Format]
        if self.error:
            message = str(self.error)
        else:
            message = message or "Operation returned an invalid status '{}'".format(
                self.reason
            )

        super(HttpResponseError, self).__init__(message=message, **kwargs)

message is the HTTP response error message (optional)

response is the HTTP response (optional).

kwargs are keyword arguments to include with the exception.

The following exceptions inherit from HttpResponseError:

DecodeError

An error raised during response de-serialization.

IncompleteReadError

An error raised if peer closes the connection before we have received the complete message body.

ResourceExistsError

An error response with status code 4xx. This will not be raised directly by the Azure core pipeline.

ResourceNotFoundError

An error response, typically triggered by a 412 response (for update) or 404 (for get/post).

ResourceModifiedError

An error response with status code 4xx, typically 412 Conflict. This will not be raised directly by the Azure core pipeline.

ResourceNotModifiedError

An error response with status code 304. This will not be raised directly by the Azure core pipeline.

ClientAuthenticationError

An error response with status code 4xx. This will not be raised directly by the Azure core pipeline.

TooManyRedirectsError

An error raised when the maximum number of redirect attempts is reached. The maximum amount of redirects can be configured in the RedirectPolicy.

class TooManyRedirectsError(HttpResponseError):
    def __init__(self, history, *args, **kwargs):
        self.history = history
        message = "Reached maximum redirect attempts."
        super(TooManyRedirectsError, self).__init__(message, *args, **kwargs)

history is used to document the requests/responses that resulted in redirected requests.

args are any additional args to be included with exception.

kwargs are keyword arguments to include with the exception.

StreamConsumedError

An error thrown if you try to access the stream of azure.core.rest.HttpResponse or azure.core.rest.AsyncHttpResponse once the response stream has been consumed.

StreamClosedError

An error thrown if you try to access the stream of the azure.core.rest.HttpResponse or azure.core.rest.AsyncHttpResponse once the response stream has been closed.

ResponseNotReadError

An error thrown if you try to access the content of azure.core.rest.HttpResponse or azure.core.rest.AsyncHttpResponse before reading in the response's bytes first.

Configurations

When calling the methods, some properties can be configured by passing in as kwargs arguments.

Async transport

The async transport is designed to be opt-in. AioHttp is one of the supported implementations of async transport. It is not installed by default. You need to install it separately.

Shared modules

MatchConditions

MatchConditions is an enum to describe match conditions.

class MatchConditions(Enum):
    Unconditionally = 1  # Matches any condition
    IfNotModified = 2  # If the target object is not modified. Usually it maps to etag=<specific etag>
    IfModified = 3  # Only if the target object is modified. Usually it maps to etag!=<specific etag>
    IfPresent = 4   # If the target object exists. Usually it maps to etag='*'
    IfMissing = 5   # If the target object does not exist. Usually it maps to etag!='*'

CaseInsensitiveEnumMeta

A metaclass to support case-insensitive enums.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

class MyCustomEnum(str, Enum, metaclass=CaseInsensitiveEnumMeta):
    FOO = 'foo'
    BAR = 'bar'

Null Sentinel Value

A falsy sentinel object which is supposed to be used to specify attributes with no data. This gets serialized to null on the wire.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.