azure-core¶

class azure.core.PipelineClient(base_url, **kwargs)[source]¶

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()[source]¶

delete(url, params=None, headers=None, content=None, form_content=None)¶

Create a DELETE request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

format_url(url_template, **kwargs)¶

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, params=None, headers=None, content=None, form_content=None)¶

Create a GET request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

head(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a HEAD request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

merge(url, params=None, headers=None, content=None, form_content=None)¶

Create a MERGE request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

patch(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a PATCH request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

post(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a POST request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

put(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a PUT request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

class azure.core.MatchConditions[source]¶

An enum to describe match conditions.

IfMissing = 5¶

IfModified = 3¶

IfNotModified = 2¶

IfPresent = 4¶

Unconditionally = 1¶

class azure.core.AsyncPipelineClient(base_url, **kwargs)[source]¶

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()[source]¶

delete(url, params=None, headers=None, content=None, form_content=None)¶

Create a DELETE request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

format_url(url_template, **kwargs)¶

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, params=None, headers=None, content=None, form_content=None)¶

Create a GET request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

head(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a HEAD request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

merge(url, params=None, headers=None, content=None, form_content=None)¶

Create a MERGE request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

patch(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a PATCH request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

post(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a POST request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

put(url, params=None, headers=None, content=None, form_content=None, stream_content=None)¶

Create a PUT request object.

Parameters

url (str) – The request URL.
params (dict) – Request URL parameters.
headers (dict) – Headers
form_content (dict) – Form content

Returns

An HttpRequest object

Return type

HttpRequest

Subpackages¶

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)[source]¶

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)[source]¶

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]][source]¶

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.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)[source]¶

Base exception for all errors.

raise_with_traceback()[source]¶

exception azure.core.exceptions.ServiceRequestError(message, *args, **kwargs)[source]¶: An error occurred while attempt to make a request to the service. No request was sent.

exception azure.core.exceptions.ServiceResponseError(message, *args, **kwargs)[source]¶: 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)[source]¶

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

status_code – HttpResponse’s status code
response – The response that triggered the exception.

exception azure.core.exceptions.DecodeError(message=None, response=None, **kwargs)[source]¶: Error raised during response deserialization.

exception azure.core.exceptions.ResourceExistsError(message=None, response=None, **kwargs)[source]¶: 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)[source]¶: 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)[source]¶: 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)[source]¶: 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)[source]¶: 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)[source]¶: Reached the maximum number of redirect attempts.

exception azure.core.exceptions.ODataV4Error(response, **kwargs)[source]¶

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)[source]¶

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.

azure.core.paging¶

class azure.core.paging.ItemPaged(*args, **kwargs)[source]¶

Return an iterator of items.

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

by_page(continuation_token=None)[source]¶

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)[source]¶

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()¶: 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[source]¶

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)[source]¶

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.