API Reference¶
This section documents the public API of the CRUDs package.
Client¶
- class cruds.Client(host: str, auth=None, manager=None, timeout=300.0, raise_status=True, retries=4, backoff_factor=0.9, retry_status_codes=(504, 503, 502, 500, 429, 425, 408), serialize=True, verify_ssl=True)[source]¶
Bases:
objectRepresents an platform interface that supports CRUD operations as methods.
Data supplied as Dictionaries are automatically serialised and deserialized as JSON. All parameters are key-word values, and positional arguments are not accepted.
Instance Attributes¶
- status_ignore: set
A set of status codes to ignore by instances with raise for status enabled.
Methods¶
- create:
Makes a POST request to the API Server
- read:
Makes a GET request to the API Server
- update:
Makes a PATCH or PUT request to the API Server
- delete:
Makes a DELETE request to the API Server
- create(uri: str, data: dict, params: dict[Any, Any] | None = None, files: dict[str, str | bytes | tuple[str, str | bytes] | tuple[str, str | bytes, str]] | None = None) dict[Any, Any] | bytes[source]¶
Makes a basic Create request to the API, and returns the response.
The HTTP method used is POST, and the data can be either a dictionary that is serialised to JSON or bytes and strings that will be sent without serialisation.
When files is provided, the request is sent as multipart/form-data using urllib3’s fields parameter. This takes precedence over data serialisation.
For POST requests parameters are encoded into the URL. https://urllib3.readthedocs.io/en/stable/user-guide.html#query-parameters
Parameters¶
- uristr
The URI to be used to with the connection to the API
- datadict or bytes or string
Payload to be sent to the API
- paramsdict, optional
Parameters to be added to the URI
- filesdict, optional
Multipart form fields passed as urllib3 fields. Values can be plain strings/bytes for form data, (filename, data) tuples, or (filename, data, content_type) tuples for file uploads.
Returns¶
dict if the response is JSON, otherwise bytes
- delete(uri: str, params: dict[Any, Any] | None = None) dict[Any, Any] | bytes[source]¶
Makes a basic Delete request to the API, and returns the response
Parameters¶
- uristr
The URI to be used to with the connection to the API
- paramsdict, optional
Parameters to be added to the URI
Returns¶
dict if the response is JSON, otherwise bytes
- read(uri: str, params: dict[Any, Any] | None = None) dict[Any, Any] | bytes[source]¶
Makes a basic Retrieve request to the API, and returns the response
The HTTP method used is GET.
Parameters¶
- uristr
The URI to be used to with the connection to the API
- paramsdict, optional
Parameters to be added to the URI
Returns¶
dict if the response is JSON, otherwise bytes
- update(uri: str, data: dict[Any, Any] | str, params: dict[Any, Any] | None = None, replace: bool = False, files: dict[str, str | bytes | tuple[str, str | bytes] | tuple[str, str | bytes, str]] | None = None) dict[Any, Any] | bytes[source]¶
Makes a basic Update request to the API, and returns the response.
The HTTP method used is PATCH (or PUT with replace enabled), and the data can be either a dictionary that is serialised to JSON or bytes and strings that will be sent without serialisation.
When files is provided, the request is sent as multipart/form-data using urllib3’s fields parameter. This takes precedence over data serialisation.
For PUT requests parameters are encoded into the URL. https://urllib3.readthedocs.io/en/stable/user-guide.html#query-parameters
Parameters¶
- uristr
The URI to be used to with the connection to the API
- datadict or bytes or string
Payload to be sent to the API
- paramsdict, optional
Parameters to be added to the URI
- replacebool, optional
Requests a full replacement of the entire entity. Uses PUT Method.
- filesdict, optional
Multipart form fields passed as urllib3 fields. Values can be plain strings/bytes for form data, (filename, data) tuples, or (filename, data, content_type) tuples for file uploads.
Returns¶
dict if the response is JSON, otherwise bytes
Authentication¶
- class cruds.core.AuthABC[source]¶
Bases:
objectAn Abstract Base Class that is used for implement the required interface that is used for Authentcation by the Client class.
Complex authentication flows used to gain access with the CRUDs Client
- class cruds.auth.OAuth2(url: str, client_id: str, client_secret: str, scope: str, authorization_details=None, username=None, password=None, encryption_key: str | None = None, authorization_url: str | None = None, redirect_uri: str | None = None, state_length: int = 32)[source]¶
Bases:
AuthABCA client for the OAuth 2.0 specification, supporting access token using the ‘Client Credientials’, ‘Password’, and ‘Authorization Code’ grant types.
- access_token() str[source]¶
Retrives the access token from the server, and performs refreshing the token if supported by the protocol.
- Returns:
access token as a string
- exchange_code_for_token(authorization_code: str, state: str) str[source]¶
Exchange authorization code for access token (Authorization Code flow).
- Args:
authorization_code: The authorization code received from the authorization server state: The state parameter received from the authorization server
- Returns:
The access token
- Raises:
RuntimeError: If state parameter validation fails OAuthAccessTokenError: If token exchange fails
- get_authorization_url(additional_params: dict[str, str] | None = None) str[source]¶
Generate the authorization URL for the Authorization Code flow.
- Args:
additional_params: Additional parameters to include in the authorization URL
- Returns:
The complete authorization URL with state parameter
- Raises:
RuntimeError: If authorization_url or redirect_uri is not configured
- is_valid() bool[source]¶
Check if an access token is valid and hasn’t expired yet.
- Returns:
true if token is valid, otherwise false
- parse_authorization_response(redirect_url: str) tuple[str, str][source]¶
Parse the authorization response from the redirect URL.
- Args:
redirect_url: The full redirect URL received from the authorization server
- Returns:
Tuple of (authorization_code, state)
- Raises:
RuntimeError: If the redirect URL is invalid or missing required parameters
Exceptions¶
Custom Exceptions