corehttp package

class corehttp.MatchConditions(*values)[source]

An enum to describe match conditions.

IfMissing = 5: If the target object does not exist. Usually it maps to etag!=’*’

IfModified = 3: Only if the target object is modified. Usually it maps to etag!=<specific etag>

IfNotModified = 2: If the target object is not modified. Usually it maps to etag=<specific etag>

IfPresent = 4: If the target object exists. Usually it maps to etag=’*’

Unconditionally = 1: Matches any condition

Subpackages

Submodules

corehttp.credentials module

class corehttp.credentials.AccessTokenInfo(token: str, expires_on: int, *, token_type: str = 'Bearer', refresh_on: int | None = None)[source]

Information about an OAuth access token.

Parameters:

token (str) – The token string.
expires_on (int) – The token’s expiration time in Unix time.

Keyword Arguments:

token_type (str) – The type of access token. Defaults to ‘Bearer’.
refresh_on (int) – Specifies the time, in Unix time, when the cached token should be proactively refreshed. Optional.

expires_on: int: The token’s expiration time in Unix time.

refresh_on: int | None: Specifies the time, in Unix time, when the cached token should be proactively refreshed. Optional.

token: str: The token string.

token_type: str: The type of access token.

class corehttp.credentials.AsyncTokenCredential(*args, **kwargs)[source]

Protocol for classes able to provide OAuth tokens.

async close() → None[source]

async get_token_info(*scopes: str, options: TokenRequestOptions | None = None) → AccessTokenInfo[source]

Request an access token for scopes.

Parameters:: scopes (str) – The type of access needed.
Keyword Arguments:: options (TokenRequestOptions) – A dictionary of options for the token request. Unknown options will be ignored. Optional.
Return type:: AccessTokenInfo
Returns:: An AccessTokenInfo instance containing the token string and its expiration time in Unix time.

class corehttp.credentials.ServiceKeyCredential(key: str)[source]

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

Parameters:: key (str) – The key used to authenticate to a service
Raises:: TypeError

update(key: str) → None[source]

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 a service
Raises:: ValueError or TypeError

property key: str

The value of the configured key.

Return type:: str
Returns:: The value of the configured key.

class corehttp.credentials.ServiceNamedKeyCredential(name: str, key: str)[source]

Credential type used for working with any service needing a named key that follows patterns established by the other credential types.

Parameters:

name (str) – The name of the credential used to authenticate to a service.
key (str) – The key used to authenticate to a service.

Raises:

TypeError

update(name: str, key: str) → None[source]

Update the named key credential.

Both name and key must be provided in order to update the named key credential. Individual attributes cannot be updated.

Parameters:

name (str) – The name of the credential used to authenticate to a service.
key (str) – The key used to authenticate to a service.

property named_key: ServiceNamedKey

The value of the configured name.

Return type:: ServiceNamedKey
Returns:: The value of the configured name.

class corehttp.credentials.TokenCredential(*args, **kwargs)[source]

Protocol for classes able to provide OAuth access tokens.

close() → None[source]

get_token_info(*scopes: str, options: TokenRequestOptions | None = None) → AccessTokenInfo[source]

Request an access token for scopes.

Parameters:: scopes (str) – The type of access needed.
Keyword Arguments:: options (TokenRequestOptions) – A dictionary of options for the token request. Unknown options will be ignored. Optional.
Return type:: AccessTokenInfo
Returns:: An AccessTokenInfo instance containing information about the token.

class corehttp.credentials.TokenRequestOptions[source]

Options to use for access token requests. All parameters are optional.

clear(): Remove all items from the dict.

copy(): Return a shallow copy of the dict.

classmethod fromkeys(iterable, value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items(): Return a set-like object providing a view on the dict’s items.

keys(): Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values(): Return an object providing a view on the dict’s values.

claims: str: Additional claims required in the token, such as those returned in a resource provider’s claims challenge following an authorization failure.

tenant_id: str: The tenant ID to include in the token request.

corehttp.exceptions module

exception corehttp.exceptions.BaseError(message: object | None, *args: Any, **kwargs: Any)[source]

Base exception for all errors.

Parameters:

message (object) – 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.

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception corehttp.exceptions.ClientAuthenticationError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.DecodeError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

Error raised during response deserialization.

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.DeserializationError[source]

Raised if an error is encountered during deserialization.

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception corehttp.exceptions.HttpResponseError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

Parameters:

message (object) – The message object stringified as ‘message’ attribute
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 (Any) – The response body model

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.ResourceExistsError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

model: Any | None

reason: str | None

response: _HttpResponseCommonAPI | None

status_code: int | None

exception corehttp.exceptions.ResourceModifiedError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

model: Any | None

reason: str | None

response: _HttpResponseCommonAPI | None

status_code: int | None

exception corehttp.exceptions.ResourceNotFoundError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

model: Any | None

reason: str | None

response: _HttpResponseCommonAPI | None

status_code: int | None

exception corehttp.exceptions.ResourceNotModifiedError(message: object | None = None, response: _HttpResponseCommonAPI | None = None, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

model: Any | None

reason: str | None

response: _HttpResponseCommonAPI | None

status_code: int | None

exception corehttp.exceptions.ResponseNotReadError(response: _HttpResponseCommonAPI)[source]

Error thrown if you try to access a response’s content without reading first.

It is thrown if you try to access an ~corehttp.rest.HttpResponse or ~corehttp.rest.AsyncHttpResponse’s content without first reading the response’s bytes in first.

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.SerializationError[source]

Raised if an error is encountered during serialization.

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception corehttp.exceptions.ServiceRequestError(message: object | None, *args: Any, **kwargs: Any)[source]

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.ServiceResponseError(message: object | None, *args: Any, **kwargs: Any)[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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.StreamClosedError(response: _HttpResponseCommonAPI)[source]

Error thrown if you try to access the stream of a response once closed.

It is thrown if you try to read / stream an ~corehttp.rest.HttpResponse or ~corehttp.rest.AsyncHttpResponse once the response’s stream has been closed.

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

exception corehttp.exceptions.StreamConsumedError(response: _HttpResponseCommonAPI)[source]

Error thrown if you try to access the stream of a response once consumed.

It is thrown if you try to read / stream an ~corehttp.rest.HttpResponse or ~corehttp.rest.AsyncHttpResponse once the response’s stream has been consumed.

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

add_note(object, /): Exception.add_note(note) – add a note to the exception

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

continuation_token: str | None

exc_msg: str

exc_traceback: TracebackType | None

exc_type: Type[Any] | None

exc_value: BaseException | None

inner_exception: BaseException | None

message: str

corehttp.paging module

class corehttp.paging.AsyncItemPaged(*args: Any, **kwargs: Any)[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: str | None = 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)
Return type:: AsyncIterator[AsyncIterator[ReturnType]]

class corehttp.paging.AsyncPageIterator(get_next: Callable[[str | None], Awaitable[ResponseType]], extract_data: Callable[[ResponseType], Awaitable[Tuple[str, AsyncIterator[ReturnType]]]], continuation_token: str | None = 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 corehttp.paging.ItemPaged(*args: Any, **kwargs: Any)[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: str | None = None) → Iterator[Iterator[ReturnType]][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)
Return type:: iterator[iterator[ReturnType]]

next() → ReturnType: Return the next item from the iterator. When exhausted, raise StopIteration

class corehttp.paging.PageIterator(get_next: Callable[[str | None], ResponseType], extract_data: Callable[[ResponseType], Tuple[str, Iterable[ReturnType]]], continuation_token: str | None = 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() → Iterator[ReturnType]: Return the next item from the iterator. When exhausted, raise StopIteration

corehttp.serialization module

class corehttp.serialization.CoreJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

A JSON encoder that’s capable of serializing datetime objects and bytes.

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o: Any) → Any[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

encode(o)

Return a JSON string representation of a Python data structure.

>>> from json.encoder import JSONEncoder
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example:

for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

item_separator = ', '

key_separator = ': '

corehttp.serialization.NULL = <corehttp.serialization._Null object>: A falsy sentinel object which is supposed to be used to specify attributes with no data. This gets serialized to null on the wire.