azure-core

class azure.core.PipelineClient(base_url, **kwargs)

Service client core methods.

Builds a Pipeline client.

Parameters

base_url (str) – URL for the request.

Keyword Arguments

• config (Configuration) – If omitted, the standard configuration is used.

• pipeline (Pipeline) – If omitted, a Pipeline object is created and returned.

• policies (list[HTTPPolicy]) – If omitted, the standard policies of the configuration object is used.

• transport (HttpTransport) – If omitted, RequestsTransport is used for synchronous transport.

Returns

A pipeline object.

Return type

Pipeline

Example:

Builds the pipeline client.

from azure.core import PipelineClient
from azure.core.pipeline.policies import RedirectPolicy, UserAgentPolicy

# example configuration with some policies
policies = [
    UserAgentPolicy("myuseragent"),
    RedirectPolicy()
]

client = PipelineClient(base_url=url, policies=policies)
request = client.get("https://bing.com")

pipeline_response = client._pipeline.run(request)

close()

delete(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a DELETE request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

format_url(url_template: str, **kwargs: Any) → str

Format request URL with the client base URL, unless the supplied URL is already absolute.

Parameters

url_template (str) – The request URL to be formatted if necessary.

get(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a GET request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

head(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a HEAD request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

merge(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a MERGE request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

options(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, **kwargs: Any) → azure.core.pipeline.transport._base.HttpRequest

Create a OPTIONS request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

Keyword Arguments

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

patch(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a PATCH request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

post(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a POST request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

put(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a PUT request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

class azure.core.MatchConditions

An enum to describe match conditions.

IfMissing = 5

IfModified = 3

IfNotModified = 2

IfPresent = 4

Unconditionally = 1

class azure.core.AsyncPipelineClient(base_url, **kwargs)

Service client core methods.

Builds an AsyncPipeline client.

Parameters

base_url (str) – URL for the request.

Keyword Arguments

• config (Configuration) – If omitted, the standard configuration is used.

• pipeline (Pipeline) – If omitted, a Pipeline object is created and returned.

• policies (list[HTTPPolicy]) – If omitted, the standard policies of the configuration object is used.

• transport (HttpTransport) – If omitted, RequestsTransport is used for synchronous transport.

Returns

An async pipeline object.

Return type

AsyncPipeline

Example:

Builds the async pipeline client.

from azure.core import AsyncPipelineClient
from azure.core.pipeline.policies import AsyncRedirectPolicy, UserAgentPolicy
from azure.core.pipeline.transport import HttpRequest

# example policies
request = HttpRequest("GET", url)
policies = [
    UserAgentPolicy("myuseragent"),
    AsyncRedirectPolicy(),
]

async with AsyncPipelineClient(base_url=url, policies=policies) as client:
    response = await client._pipeline.run(request)

async close()

delete(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a DELETE request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

format_url(url_template: str, **kwargs: Any) → str

Format request URL with the client base URL, unless the supplied URL is already absolute.

Parameters

url_template (str) – The request URL to be formatted if necessary.

get(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a GET request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

head(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a HEAD request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

merge(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a MERGE request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

options(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, **kwargs: Any) → azure.core.pipeline.transport._base.HttpRequest

Create a OPTIONS request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

Keyword Arguments

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

patch(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a PATCH request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

post(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a POST request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

put(url: str, params: Optional[Dict[str, str]] = None, headers: Optional[Dict[str, str]] = None, content: Optional[Any] = None, form_content: Optional[Dict[str, Any]] = None, stream_content: Optional[Any] = None) → azure.core.pipeline.transport._base.HttpRequest

Create a PUT request object.

Parameters

• url (str) – The request URL.

• params (dict) – Request URL parameters.

• headers (dict) – Headers

• content – The body content

• form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

Subpackages

• azure.core.pipeline
  • Subpackages
    • azure.core.pipeline.policies
    • azure.core.pipeline.transport
• azure.core.polling
• azure.core.tracing
  • Submodules
  • azure.core.tracing.common
  • azure.core.tracing.decorator
  • azure.core.tracing.decorator_async

Submodules

azure.core.async_paging

class azure.core.async_paging.AsyncPageIterator(get_next: Callable[Optional[str], Awaitable[ResponseType]], extract_data: Callable[ResponseType, Awaitable[Tuple[str, AsyncIterator[ReturnType]]]], continuation_token: Optional[str] = None)

Return an async iterator of pages.

Parameters

• get_next – Callable that take the continuation token and return a HTTP response

• extract_data – Callable that take an HTTP response and return a tuple continuation token, list of ReturnType

• continuation_token (str) – The continuation token needed by get_next

class azure.core.async_paging.AsyncItemPaged(*args, **kwargs)

Return an async iterator of items.

args and kwargs will be passed to the AsyncPageIterator constructor directly, except page_iterator_class

by_page(continuation_token: Optional[str] = None) → AsyncIterator[AsyncIterator[ReturnType]]

Get an async iterator of pages of objects, instead of an async iterator of objects.

Parameters

continuation_token (str) – An opaque continuation token. This value can be retrieved from the continuation_token field of a previous generator object. If specified, this generator will begin returning results from this point.

Returns

An async iterator of pages (themselves async iterator of objects)

azure.core.credentials

class azure.core.credentials.AzureKeyCredential(key: str)

Credential type used for authenticating to an Azure service. It provides the ability to update the key without creating a new client.

Parameters

key (str) – The key used to authenticate to an Azure service

Raises

TypeError

update(key: str) → None

Update the key.

This can be used when you’ve regenerated your service key and want to update long-lived clients.

Parameters

key (str) – The key used to authenticate to an Azure service

Raises

ValueError or TypeError

property key

The value of the configured key.

Return type

str

class azure.core.credentials.AccessToken(token, expires_on)

Create new instance of AccessToken(token, expires_on)

count(value) → integer – return number of occurrences of value

index(value[, start[, stop]]) → integer – return first index of value.

Raises ValueError if the value is not present.

property expires_on

Alias for field number 1

property token

Alias for field number 0

azure.core.exceptions

exception azure.core.exceptions.AzureError(message, *args, **kwargs)

Base exception for all errors.

Parameters

message – The message object stringified as ‘message’ attribute

Keyword Arguments

error (Exception) – The original exception if any

Variables

• inner_exception (Exception) – The exception passed with the ‘error’ kwarg

• exc_type – The exc_type from sys.exc_info()

• exc_value – The exc_value from sys.exc_info()

• exc_traceback – The exc_traceback from sys.exc_info()

• exc_msg – A string formatting of message parameter, exc_type and exc_value

• message (str) – A stringified version of the message parameter

• continuation_token (str) – A token reference to continue an incomplete operation. This value is optional and will be None where continuation is either unavailable or not applicable.

raise_with_traceback()

exception azure.core.exceptions.ServiceRequestError(message, *args, **kwargs)

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

exception azure.core.exceptions.ServiceResponseError(message, *args, **kwargs)

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

exception azure.core.exceptions.HttpResponseError(message=None, response=None, **kwargs)

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

Parameters

• message (string) – HttpResponse’s error message

• response (HttpResponse or AsyncHttpResponse) – The response that triggered the exception.

Variables

• reason (str) – The HTTP response reason

• status_code (int) – HttpResponse’s status code

• response (HttpResponse or AsyncHttpResponse) – The response that triggered the exception.

• model (Model) – The request body/response body model

• error (ODataV4Format) – The formatted error

exception azure.core.exceptions.DecodeError(message=None, response=None, **kwargs)

Error raised during response deserialization.

exception azure.core.exceptions.ResourceExistsError(message=None, response=None, **kwargs)

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

exception azure.core.exceptions.ResourceNotFoundError(message=None, response=None, **kwargs)

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

exception azure.core.exceptions.ClientAuthenticationError(message=None, response=None, **kwargs)

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

exception azure.core.exceptions.ResourceModifiedError(message=None, response=None, **kwargs)

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

exception azure.core.exceptions.ResourceNotModifiedError(message=None, response=None, **kwargs)

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

exception azure.core.exceptions.TooManyRedirectsError(history, *args, **kwargs)

Reached the maximum number of redirect attempts.

exception azure.core.exceptions.ODataV4Error(response: _HttpResponseBase, **kwargs: Any)

An HTTP response error where the JSON is decoded as OData V4 error format.

http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html#_Toc372793091

Variables

• odata_json (dict) – The parsed JSON body as attribute for convenience.

• code (str) – Its value is a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.

• message (str) – Human-readable, language-dependent representation of the error.

• target (str) – The target of the particular error (for example, the name of the property in error). This field is optional and may be None.

• details (list[ODataV4Format]) – Array of ODataV4Format instances that MUST contain name/value pairs for code and message, and MAY contain a name/value pair for target, as described above.

• innererror (dict) – An object. The contents of this object are service-defined. Usually this object contains information that will help debug the service.

class azure.core.exceptions.ODataV4Format(json_object)

Class to describe OData V4 error format.

http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html#_Toc372793091

Parameters

json_object (dict) – A Python dict representing a ODataV4 JSON

Variables

• code (str) – Its value is a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.

• message (str) – Human-readable, language-dependent representation of the error.

• target (str) – The target of the particular error (for example, the name of the property in error). This field is optional and may be None.

• details (list[ODataV4Format]) – Array of ODataV4Format instances that MUST contain name/value pairs for code and message, and MAY contain a name/value pair for target, as described above.

• innererror (dict) – An object. The contents of this object are service-defined. Usually this object contains information that will help debug the service.

message_details()

Return a detailled string of the error.

CODE_LABEL = 'code'

DETAILS_LABEL = 'details'

INNERERROR_LABEL = 'innererror'

MESSAGE_LABEL = 'message'

TARGET_LABEL = 'target'

property error

azure.core.paging

class azure.core.paging.ItemPaged(*args, **kwargs)

Return an iterator of items.

args and kwargs will be passed to the PageIterator constructor directly, except page_iterator_class

by_page(continuation_token: Optional[str] = None) → Iterator[Iterator[ReturnType]]

Get an iterator of pages of objects, instead of an iterator of objects.

Parameters

continuation_token (str) – An opaque continuation token. This value can be retrieved from the continuation_token field of a previous generator object. If specified, this generator will begin returning results from this point.

Returns

An iterator of pages (themselves iterator of objects)

next()

Return the next item from the iterator. When exhausted, raise StopIteration

class azure.core.paging.PageIterator(get_next, extract_data, continuation_token=None)

Return an iterator of pages.

Parameters

• get_next – Callable that take the continuation token and return a HTTP response

• extract_data – Callable that take an HTTP response and return a tuple continuation token, list of ReturnType

• continuation_token (str) – The continuation token needed by get_next

next() → Iterator[ReturnType]

Return the next item from the iterator. When exhausted, raise StopIteration

azure.core.settings

Provide access to settings for globally used Azure configuration values.

class azure.core.settings.Settings

Settings for globally used Azure configuration values.

You probably don’t want to create an instance of this class, but call the singleton instance:

from azure.common.settings import settings
settings.log_level = log_level = logging.DEBUG

The following methods are searched in order for a setting:

4. immediate values 3. previously user-set value 2. environment variable 1. system setting 0. implicit default

An implicit default is (optionally) defined by the setting attribute itself.

A system setting value can be obtained from registries or other OS configuration for settings that support that method.

An environment variable value is obtained from os.environ

User-set values many be specified by assigning to the attribute:

settings.log_level = log_level = logging.DEBUG

Immediate values are (optionally) provided when the setting is retrieved:

settings.log_level(logging.DEBUG())

Immediate values are most often useful to provide from optional arguments to client functions. If the argument value is not None, it will be returned as-is. Otherwise, the setting searches other methods according to the precedence rules.

Immutable configuration snapshots can be created with the following methods:

• settings.defaults returns the base defaultsvalues , ignoring any environment or system or user settings

• settings.current returns the current computation of settings including prioritizatiom of configuration sources, unless defaults_only is set to True (in which case the result is identical to settings.defaults)

• settings.config can be called with specific values to override what settings.current would provide

# return current settings with log level overridden
settings.config(log_level=logging.DEBUG)

Variables

• log_level – a log level to use across all Azure client SDKs (AZURE_LOG_LEVEL)

• tracing_enabled – Whether tracing should be enabled across Azure SDKs (AZURE_TRACING_ENABLED)

• tracing_implementation – The tracing implementation to use (AZURE_SDK_TRACING_IMPLEMENTATION)

Example

>>> import logging
>>> from azure.core.settings import settings
>>> settings.log_level = logging.DEBUG
>>> settings.log_level()
10

>>> settings.log_level(logging.WARN)
30

config(**kwargs)

Return the currently computed settings, with values overridden by parameter values.

Examples:

# return current settings with log level overridden
settings.config(log_level=logging.DEBUG)

property current

Return the current values for all settings.

Return type

namedtuple

property defaults

Return implicit default values for all settings, ignoring environment and system.

Return type

namedtuple

property defaults_only

Whether to ignore environment and system settings and return only base default values.

Return type

bool

log_level

Return a value for a global setting according to configuration precedence.

The following methods are searched in order for the setting:

4. immediate values 3. previously user-set value 2. environment variable 1. system setting 0. implicit default

If a value cannot be determined, a RuntimeError is raised.

The env_var argument specifies the name of an environment to check for setting values, e.g. "AZURE_LOG_LEVEL".

The optional system_hook can be used to specify a function that will attempt to look up a value for the setting from system-wide configurations.

The optional default argument specified an implicit default value for the setting that is returned if no other methods provide a value.

A convert agument may be provided to convert values before they are returned. For instance to concert log levels in environment variables to logging module values.

tracing_enabled

Return a value for a global setting according to configuration precedence.

The following methods are searched in order for the setting:

4. immediate values 3. previously user-set value 2. environment variable 1. system setting 0. implicit default

If a value cannot be determined, a RuntimeError is raised.

The env_var argument specifies the name of an environment to check for setting values, e.g. "AZURE_LOG_LEVEL".

The optional system_hook can be used to specify a function that will attempt to look up a value for the setting from system-wide configurations.

The optional default argument specified an implicit default value for the setting that is returned if no other methods provide a value.

A convert agument may be provided to convert values before they are returned. For instance to concert log levels in environment variables to logging module values.

tracing_implementation

Return a value for a global setting according to configuration precedence.

The following methods are searched in order for the setting:

4. immediate values 3. previously user-set value 2. environment variable 1. system setting 0. implicit default

If a value cannot be determined, a RuntimeError is raised.

The env_var argument specifies the name of an environment to check for setting values, e.g. "AZURE_LOG_LEVEL".

The optional system_hook can be used to specify a function that will attempt to look up a value for the setting from system-wide configurations.

The optional default argument specified an implicit default value for the setting that is returned if no other methods provide a value.

A convert agument may be provided to convert values before they are returned. For instance to concert log levels in environment variables to logging module values.

azure.core.settings.settings = <azure.core.settings.Settings object>

The settings unique instance.