Sync Client

Attributes
Methods
class arya_api_framework.SyncClient(uri=None, *args, headers=None, cookies=None, parameters=None, error_responses=None, bearer_token=None, rate_limit=None, rate_limit_interval=None, **kwargs)

The synchronous API client class. Utilizes the requests module.

Parameters

uri (Optional[str]) –

The base URI that will prepend all requests made using the client.

Warning

This should always either be passed as an argument here or as a subclass argument. If neither are given, an errors.SyncClientError exception will be raised.

Keyword Arguments

  • headers (Optional[Union[dict, BaseModel]) – The default headers to pass with every request. Can be overridden by individual requests. Defaults to None.

  • cookies (Optional[Union[dict, BaseModel]) – The default cookies to pass with every request. Can be overridden by individual requests. Defaults to None.

  • parameters (Optional[Union[dict, BaseModel]]) – The default parameters to pass with every request. Can be overridden by individual requests. Defaults to None.

  • error_responses (Optional[dict]) – A mapping of int error codes to BaseModel types to use when that error code is received. Defaults to None and raises default exceptions for error codes.

  • bearer_token (Optional[str, pydantic.SecretStr) – A bearer_token that will be sent with requests in the Authorization header. Defaults to None

  • rate_limit (Optional[Union[int, float]]) – The number of requests to allow over rate_limit_interval seconds. Defaults to None

  • rate_limit_interval (Optional[Union[int, float]]) – The period of time, in seconds, over which to apply the rate limit per every rate_limit requests. Defaults to 1 second.

Tip

All of the arguments that can be used when instantiating a client can also be used as subclass parameters:

class MyClient(SyncClient, uri="https://exampleurl.com", parameters={"arg1": "abc"}):
    pass

Then, when instantiating the client, any arguments passed directly to the class will update the subclass parameters.

closed

Whether of not the internal requests.Session has been closed. If the session has been closed, the client will not allow any further requests to be made.

Type

bool

uri

The base URI that will prepend all requests made using the client.

Type

Optional[str]

uri_root

The root origin of the uri given to the client.

Type

Optional[str]

uri_path

The path from the uri_root to the uri path.

Type

Optional[str]

headers

The default headers that will be passed into every request, unless overridden.

Type

Optional[dict]

cookies

The default cookies that will be passed into every request, unless overridden.

Type

Optional[dict]

parameters

The default parameters that will be passed into every request, unless overridden.

Type

Optional[dict]

error_responses

A mapping of int error codes to the BaseModel that should be used to represent them.

Note

By default, an internal exception mapping is used. See Exception Hierarchy.

Type

Optional[dict]

rate_limit

The number of requests per rate_limit_interval the client is allowed to send.

Type

Optional[Union[int, float]]

rate_limit_interval

The interval, in seconds, over which to apply a rate limit for rate_limit requests per interval.

Type

Optional[Union[int, float]]

is_rate_limited

Whether or not the client has a rate limit set.

Type

bool

__post_init__(*args, **kwargs)

This method is run after the __init__ method is called, and is passed any extra arguments or keyword arguments that the regular init method did not recognize.

Tip

By using this method, it becomes unnecessary to override the __init__ method. Instead, any extra parameters can be provided in this method, which has no implementation at default.

Example

This is a quick example showing how one might add a default apiKey parameter to their custom API client using the __post_init__() method.

class MySyncClient(SyncClient):
    api_key: str

    def __post_init__(self, *args, api_key: str = None, **kwargs):
        self.api_key = api_key

        self.parameters['apiKey'] = self.api_key

client = MySyncClient('https://exampleurl.com', api_key='mysecretkey')

# >>> client.parameters
{
    "apiKey": "mysecretkey"
}
request(method, path=None, *, body=None, data=None, files=None, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a request to the path specified using the internal requests.Session.

Note

If the client has been closed (using close()), the request will not be processed. Instead, a warning will be logged, and this method will return None.

Parameters

  • method (str) – The request method to use for the request (see HTTP Request Methods).

  • path (Optional[str]) – The path, relative to the client’s uri, to send the request to.

Keyword Arguments

  • body (Optional[Union[dict, BaseModel]) – Optional data to send as a JSON structure in the body of the request. Defaults to None.

  • data (Optional[Any]) – Optional data of any type to send in the body of the request, without any pre-processing. Defaults to None.

  • files (Optional[dict]) – A mapping of str file names to file objects to send in the request.

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

upload_file(file, path=None, *, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a POST request to the path specified using the internal requests.Session, which will upload a given file.

Tip

To stream larger file uploads, use the stream_file() method.

Parameters

  • file (str) – The path to the file to upload.

  • path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

stream_file(file, path=None, *, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a POST request to the path specified using the internal requests.Session, which will upload a given file.

Tip

This method is meant to upload larger files in a stream manner, while the upload_file() method uploads the file without streaming it.

Parameters

  • file (str) – The path to the file to upload.

  • path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

get(path=None, *, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a GET request to the path specified using the internal requests.Session.

Parameters

path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the GET request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the GET request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the GET request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

post(path=None, *, body=None, data=None, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a POST request to the path specified using the internal requests.Session.

Parameters

path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • body (Optional[Union[dict, BaseModel]) – Optional data to send as a JSON structure in the body of the request. Defaults to None.

  • data (Optional[Any]) – Optional data of any type to send in the body of the request, without any pre-processing. Defaults to None.

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

patch(path=None, *, body=None, data=None, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a PATCH request to the path specified using the internal requests.Session.

Parameters

path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • body (Optional[Union[dict, BaseModel]) – Optional data to send as a JSON structure in the body of the request. Defaults to None.

  • data (Optional[Any]) – Optional data of any type to send in the body of the request, without any pre-processing. Defaults to None.

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

put(path=None, *, body=None, data=None, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a PUT request to the path specified using the internal requests.Session.

Parameters

path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • body (Optional[Union[dict, BaseModel]) – Optional data to send as a JSON structure in the body of the request. Defaults to None.

  • data (Optional[Any]) – Optional data of any type to send in the body of the request, without any pre-processing. Defaults to None.

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

delete(path=None, *, body=None, data=None, headers=None, cookies=None, parameters=None, response_format=None, timeout=300, error_responses=None)

Sends a DELETE request to the path specified using the internal requests.Session.

Parameters

path (Optional[str]) – The path, relative to the client’s uri, to send the request to. If this is set to None, the request will be sent to the client’s uri.

Keyword Arguments

  • body (Optional[Union[dict, BaseModel]) – Optional data to send as a JSON structure in the body of the request. Defaults to None.

  • data (Optional[Any]) – Optional data of any type to send in the body of the request, without any pre-processing. Defaults to None.

  • headers (Optional[dict, BaseModel]) – Request-specific headers to send with the request. Defaults to None and uses the default client headers.

  • cookies (Optional[dict, BaseModel]) – Request-specific cookies to send with the request. Defaults to None and uses the default client cookies.

  • parameters (Optional[dict, BaseModel]) – Request-specific query string parameters to send with the request. Defaults to None and uses the default client parameters.

  • response_format (Optional[Type[Response]]) – The model to use as the response format. This offers direct data validation and easy object-oriented implementation. Defaults to None, and the request will return a JSON structure.

  • timeout (Optional[int]) – The length of time, in seconds, to wait for a response to the request before raising a timeout error. Defaults to 300 seconds, or 5 minutes.

  • error_responses (Optional[dict]) – A mapping of int status codes to BaseModel models to use as error responses. Defaults to None, and uses the default error_responses attribute. If the error_responses is also None, or a status code does not have a specified response format, the default status code exceptions will be raised.

Returns

Optional[Union[dict, Response]] – The request response JSON, loaded into the response_format model if provided, or as a raw dict otherwise.

close()

Closes the current requests.Session, if not already closed.