apeye.slumber_url

Subclass of URL with support for interacting with REST APIs with Slumber and Requests.

New in version 0.2.0.

Classes:

SlumberURL(​[url, auth, format, …])

Subclass of URL with support for interacting with REST APIs with Slumber and Requests.

class SlumberURL(url='', auth=None, format='json', append_slash=True, session=None, serializer=None, *, timeout=None, allow_redirects=True, proxies=None, verify=None, cert=None)[source]

Bases: URL

Subclass of URL with support for interacting with REST APIs with Slumber and Requests.

Parameters

timeout, allow_redirects, proxies, verify and cert are passed to Requests when making any HTTP requests, and are inherited by all children created from this URL.

Changed in version 0.3.0: The url parameter can now be a string or a URL.

Changed in version 1.1.0: When a RequestsURL object is deleted or garbage collected, the underlying requests.Session object it only closed if no objects hold references to the session. This prevents the session object of a global object from being inadvertently closed when one of its children is garbage collected.

Methods:

__del__(​)

Attempt to close session when garbage collected to avoid leaving connections open.

delete(​**params)

Perform a DELETE request using Slumber.

get(​**params)

Perform a GET request using Slumber.

head(​**kwargs)

Send a HEAD request using Requests.

options(​**kwargs)

Send an OPTIONS request using Requests.

patch(​[data, files])

Perform a PATCH request using Slumber.

post(​[data, files])

Perform a POST request using Slumber.

put(​[data, files])

Perform a PUT request using Slumber.

url(​)

Returns the URL as a string.

Attributes:

allow_redirects

Whether to allow redirects.

cert

The path to ssl client cert file or a tuple of ('cert', 'key').

proxies

Dictionary mapping protocol or protocol and hostname to the URL of the proxy.

serializer

The serializer used to (de)serialize the data when interacting with the API.

session

The underlying requests session.

timeout

How long to wait for the server to send data before giving up.

verify

Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.

__del__()[source]

Attempt to close session when garbage collected to avoid leaving connections open.

allow_redirects

Type:    Optional[bool]

Whether to allow redirects.

cert

Type:    Union[str, Tuple[str, str], None]

The path to ssl client cert file or a tuple of ('cert', 'key').

delete(**params)[source]

Perform a DELETE request using Slumber.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE

Parameters

params – Parameters to send in the query string of the requests.Request.

Return type

bool

Returns

True if the DELETE request succeeded. False otherwise.

get(**params)[source]

Perform a GET request using Slumber.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET

Parameters

params – Parameters to send in the query string of the requests.Request.

Return type

Dict

head(**kwargs)[source]

Send a HEAD request using Requests.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD

Parameters

kwargs – Optional arguments that requests.request() takes. If allow_redirects is not provided, it will be set to False (as opposed to the default requests.request() behavior).

Return type

CaseInsensitiveDict

options(**kwargs)[source]

Send an OPTIONS request using Requests.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS

Parameters

kwargs – Optional arguments that requests.request() takes.

Return type

str

patch(data=None, files=None, **params)[source]

Perform a PATCH request using Slumber.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH

Parameters
  • data – Dictionary, list of tuples, bytes, or file-like object to send in the body of the requests.Request. Default None.

  • files – Dictionary of 'name': file-like-objects (or {'name': file-tuple}) for multipart encoding upload. file-tuple can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where 'content-type' is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file. Default None.

  • params – Parameters to send in the query string of the requests.Request.

Return type

Dict

post(data=None, files=None, **params)[source]

Perform a POST request using Slumber.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST

Parameters
  • data (Union[None, str, bytes, MutableMapping[str, Any], Iterable[Tuple[str, Optional[str]]], IO]) – Dictionary, list of tuples, bytes, or file-like object to send in the body of the requests.Request. Default None.

  • files – Dictionary of 'name': file-like-objects (or {'name': file-tuple}) for multipart encoding upload. file-tuple can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where 'content-type' is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file. Default None.

  • params – Parameters to send in the query string of the requests.Request.

Return type

Dict

proxies

Type:    Optional[MutableMapping[str, str]]

Dictionary mapping protocol or protocol and hostname to the URL of the proxy.

put(data=None, files=None, **params)[source]

Perform a PUT request using Slumber.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT

Parameters
  • data – Dictionary, list of tuples, bytes, or file-like object to send in the body of the requests.Request. Default None.

  • files – Dictionary of 'name': file-like-objects (or {'name': file-tuple}) for multipart encoding upload. file-tuple can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where 'content-type' is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file. Default None.

  • params – Parameters to send in the query string of the requests.Request.

Return type

Dict

serializer

Type:    SerializerRegistry

The serializer used to (de)serialize the data when interacting with the API.

New in version 0.6.0.

session

Type:    Session

The underlying requests session.

New in version 0.6.0.

timeout

Type:    Union[None, float, Tuple[float, float], Tuple[float, None]]

How long to wait for the server to send data before giving up.

url()[source]

Returns the URL as a string.

Return type

str

verify

Type:    Union[None, bool, str]

Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.

slumber_url.serializers

JSON and YAML serializers for SlumberURL.

New in version 0.6.0.

Classes:

JsonSerializer(​)

Serializer for JSON data.

Serializer(​)

Base class for serializers.

SerializerRegistry(​[default, serializers])

Serializes and deserializes data for transfer to and from a REST API.

YamlSerializer(​)

Serializer for YAML data.

Exceptions:

SerializerNotAvailable(​content_type)

The chosen Serializer is not available.

class JsonSerializer[source]

Bases: Serializer

Serializer for JSON data.

Changed in version 0.6.0: Moved to apeye.slumber_url.serializers

Methods:

dumps(​data)

Serialize data using this Serializer.

loads(​data)

Deserialize data using this Serializer.

dumps(data)[source]

Serialize data using this Serializer.

Parameters

data (Mapping[str, Any])

Return type

str

loads(data)[source]

Deserialize data using this Serializer.

Parameters

data (str)

Return type

MutableMapping[str, Any]

class Serializer

Bases: ABC

Base class for serializers.

Changed in version 0.6.0: Moved to apeye.slumber_url.serializers

Attributes:

content_types

List of supported content types.

key

An identifier for the supported data type.

Methods:

dumps(​data)

Serialize data using this Serializer.

get_content_type(​)

Returns the first value from content_types.

loads(​data)

Deserialize data using this Serializer.

abstract property content_types

List of supported content types.

Return type

List[str]

abstract dumps(data)[source]

Serialize data using this Serializer.

Parameters

data (Mapping[str, Any])

Return type

str

get_content_type()[source]

Returns the first value from content_types.

Return type

str

abstract property key

An identifier for the supported data type.

For example, a YAML serializer would set this to 'yaml'.

Return type

str

abstract loads(data)[source]

Deserialize data using this Serializer.

Parameters

data (str)

Return type

MutableMapping[str, Any]

exception SerializerNotAvailable(content_type)[source]

Bases: apeye.slumber_url.exceptions.SlumberBaseException

The chosen Serializer is not available.

Changed in version 0.6.0: Moved to apeye.slumber_url.serializers

class SerializerRegistry(default='json', serializers=None)[source]

Bases: object

Serializes and deserializes data for transfer to and from a REST API.

Parameters

Changed in version 0.6.0: Moved to apeye.slumber_url.serializers

Attributes:

default

The default serializer to use if none is specified.

serializers

Mapping of formats to Serializer objects.

Methods:

dumps(​data[, format])

Serialize data of the given format.

get_content_type(​[format])

Returns the content type for the serializer that supports the given format.

get_serializer(​[name, content_type])

Returns the first Serializer that supports either the given format or the given content type.

loads(​data[, format])

Deserialize data of the given format.

default

Type:    str

The default serializer to use if none is specified.

dumps(data, format=None)[source]

Serialize data of the given format.

Parameters
Return type

str

get_content_type(format=None)[source]

Returns the content type for the serializer that supports the given format.

Parameters

format (Optional[str]) – The desired serialization format. Default None.

get_serializer(name=None, content_type=None)[source]

Returns the first Serializer that supports either the given format or the given content type.

Parameters
loads(data, format=None)[source]

Deserialize data of the given format.

Parameters
Return type

MutableMapping[str, Any]

serializers

Type:    Dict[str, Serializer]

Mapping of formats to Serializer objects.

class YamlSerializer[source]

Bases: Serializer

Serializer for YAML data.

Changed in version 0.6.0: Moved to apeye.slumber_url.serializers

Attention

Either PyYaml or ruamel.yaml must be installed to use this serializer.

Methods:

dumps(​data)

Serialize data using this Serializer.

loads(​data)

Deserialize data using this Serializer.

dumps(data)[source]

Serialize data using this Serializer.

Parameters

data (Mapping[str, Any])

Return type

str

loads(data)[source]

Deserialize data using this Serializer.

Parameters

data (str)

Return type

MutableMapping[str, Any]

slumber_url.exceptions

Exceptions for SlumberURL.

New in version 0.6.0.

Exceptions:

HttpClientError(​*args, **kwargs)

Raised when the server tells us there was a client error (4xx).

HttpNotFoundError(​*args, **kwargs)

Raised when the server sends a 404 error.

HttpServerError(​*args, **kwargs)

Raised when the server tells us there was a server error (5xx).

SlumberBaseException

All Slumber exceptions inherit from this exception.

SlumberHttpBaseException(​*args, **kwargs)

All Slumber HTTP Exceptions inherit from this exception.

exception HttpClientError(*args, **kwargs)[source]

Bases: apeye.slumber_url.exceptions.SlumberHttpBaseException

Raised when the server tells us there was a client error (4xx).

Changed in version 0.6.0: Moved to apeye.slumber_url.exceptions

exception HttpNotFoundError(*args, **kwargs)[source]

Bases: apeye.slumber_url.exceptions.HttpClientError

Raised when the server sends a 404 error.

Changed in version 0.6.0: Moved to apeye.slumber_url.exceptions

exception HttpServerError(*args, **kwargs)[source]

Bases: apeye.slumber_url.exceptions.SlumberHttpBaseException

Raised when the server tells us there was a server error (5xx).

Changed in version 0.6.0: Moved to apeye.slumber_url.exceptions

exception SlumberBaseException[source]

Bases: Exception

All Slumber exceptions inherit from this exception.

Changed in version 0.6.0: Moved to apeye.slumber_url.exceptions

exception SlumberHttpBaseException(*args, **kwargs)[source]

Bases: apeye.slumber_url.exceptions.SlumberBaseException

All Slumber HTTP Exceptions inherit from this exception.

Changed in version 0.6.0: Moved to apeye.slumber_url.exceptions