comb_utils.lib package

Submodules

comb_utils.lib.api_callers module

Classes for making API calls.

class comb_utils.lib.api_callers.BaseCaller(url)

Bases: ABC

An abstract class for making API calls.

See API Callers: Base Classes for Making API Calls.

Example

class MyGetCaller(BaseCaller):
    target_response_value

    _min_wait_seconds: float = 0.1
    # Initialize _wait_seconds and timeout as a class variable.
    # Instances will adjust for class.
    _wait_seconds: float = _min_wait_seconds
    _timeout: float = 10

    def _get_API_key(self) -> str | None:
    # Optionally wrap your own API key retrieval function here.
    return my_custom_key_retrieval_function()

    def _handle_200(self):
        super()._handle_200()
        self.target_response_value = self.response_json["target_key"]

my_caller = MyGetCaller(url="https://api.example.com/data")
my_caller.call_api()
target_response_value = my_caller.target_response_value

Important

You must initialize _wait_seconds, _timeout, and _min_wait_seconds in child classes. This allows child class instances to adjust the wait/timeout time for the child class.

Warning

There is a potential for this to run indefinitely for rate limiting and timeouts. It handles them somewhat intelligently, but the assumption is that someone is watching this run in the background and will stop it if it runs too long. It will eventually at least crash the memory, depending on available memory, mean time to failure, and time left in the universe.

call_api()

The main method for making the API call.

Handle errors, parse response, and decrease class wait time on success.

Raises:

  • ValueError – If the response status code is not expected.

  • requests.exceptions.HTTPError – For non-rate-limiting errors.

Return type:

None

response_json: dict[str, Any]

The JSON from the response.

class comb_utils.lib.api_callers.DeleteCaller(url)

Bases: PostCaller

A base class for making DELETE API calls.

Presets the timeout, initial wait time, and requests method.

class comb_utils.lib.api_callers.GetCaller(url)

Bases: BaseCaller

A base class for making GET API calls.

Presets the timeout, initial wait time, and requests method.

class comb_utils.lib.api_callers.PagedResponseGetter(page_url, params=None)

Bases: GetCaller

Class for getting paged responses.

next_page_salsa: str | None

The nextPageToken returned, but called salsa to avoid bandit.

class comb_utils.lib.api_callers.PostCaller(url)

Bases: BaseCaller

A base class for making POST API calls.

Presets the timeout, initial wait time, and requests method.

comb_utils.lib.api_callers.concat_response_pages(page_list, data_key)

Extract and concatenate the data lists from response pages.

Parameters:

  • page_list (list[dict[str, Any]]) – A list of response page dictionaries.

  • data_key (str) – The key to extract the data from each page.

Return type:

list[dict[str, Any]]

Returns:

A list of dictionaries containing the data from each page.

comb_utils.lib.api_callers.get_response_dict(response)

Safely handle a response that may not be JSON.

Parameters:

response (Response) – The response from the API call.

Return type:

dict[str, Any]

Returns:

A dictionary containing the response data.

comb_utils.lib.api_callers.get_responses(url, paged_response_class, params=None)

Get all responses from a paginated API endpoint.

Parameters:

  • url (str) – The base URL of the API endpoint.

  • paged_response_class (type[PagedResponseGetter]) – The class used to get the paginated response.

  • params (dict[str, str] | None) – The dictionary of query string parameters.

Return type:

list[dict[str, Any]]

Returns:

A list of dictionaries containing the responses from all pages.

comb_utils.lib.constants module

Constants for the comb_utils library.

class comb_utils.lib.constants.RateLimits

Bases: object

Default rate limits for API Callers: Base Classes for Making API Calls.

READ_SECONDS: Final[float] = 0.1
READ_TIMEOUT_SECONDS: Final[float] = 10
WAIT_DECREASE_SECONDS: Final[float] = 0.6
WAIT_INCREASE_SCALAR: Final[float] = 2
WRITE_SECONDS: Final[float] = 0.2
WRITE_TIMEOUT_SECONDS: Final[float] = 10

comb_utils.lib.docs module

Docstring formatting for sphinx API docs and click CLI help.

class comb_utils.lib.docs.DocString(opening, args, raises, returns, defaults=None)

Bases: object

Class to format docstrings and store argument defaults for public API sphinx docs and CLI click help.

Parameters:

  • opening (str) – The opening docstring.

  • args (dict[str, str]) – Argument names and their docstrings.

  • raises (list[ErrorDocString]) – Objects holding error types with their docstrings.

  • returns (list[str]) – The returns docstrings.

  • defaults (dict[str, Any] | None) – The parameter defaults. None casts to empty dict.

property api_docstring: str

Docstring formatted for Sphinx API docs.

args: dict[str, str] = {}
property cli_docstring: str

Docstring formatted for Click CLI help.

defaults: dict[str, Any] = {}
opening: str = ''
raises: list[ErrorDocString] = []
returns: list[str] = []
class comb_utils.lib.docs.ErrorDocString(error_type, docstring)

Bases: object

Error docstrings.

Parameters:

  • error_type (str) – The error type. E.g., “ValueError”.

  • docstring (str) – The error docstring. E.g., “When arg a is less than 0.”

docstring: Final[str]
error_type: Final[str]

comb_utils.lib.errors module

Module for custom exceptions.

exception comb_utils.lib.errors.CombUtilsError

Bases: Exception

Base class for exceptions in this module.

exception comb_utils.lib.errors.DuplicateKeysDetected

Bases: CombUtilsError

Raised when a user enters a query string key twice.

Module contents

lib init.