singstat

Module contents

singstat.Url

alias of str

singstat.singstat

Client mixin for interacting with all of the API endpoints.

class singstat.singstat.SingStat(cache_backend: str | BaseCache = 'sqlite', is_test_api: bool = False)

Bases: object

Common library for other API Clients.

Normally, it does not need to be created by applications. But applications may use the public methods provided here.

The constructor sets the following:

Parameters:

  • cache_backend (str | BaseCache) – Cache backend name or instance to use. Refer to https://requests-cache.readthedocs.io/en/stable/user_guide/backends.html for more information and allowed values. Defaults to “sqlite”.

  • is_test_api (bool) – Whether to use SingStat’s test API. If this is set to True, then isTestApi=true is added to the parameters when calling send_request(). Defaults to False.

build_params(params_expected_type: Any, original_params: dict, default_params: dict | None = None) → dict

Build the list of parameters that are compatible for use with the endpoint URLs, e.g. camelCase parameter names instead of Python’s snake_case.

Parameters:

  • params_expected_type (Any) – The expected type of original_params. Should be one of the importable types from singstat.types_args.

  • original_params (dict) – The set of parameters to use for building.

  • default_params (dict or None) – The set of parameters’ default values. Should be of the same type as what is specified in params_expected_type. Defaults to None.

Returns:

The set of parameters that can be used with the API endpoints.

Return type:

dict

sanitise_data(value: Any, iterate: bool = True) → Any

Convert the following:

  • String that is like date or datetime: convert to datetime.date or datetime.datetime object respectively.

  • String value of specific dict keys: convert to integer or 2-value tuple. The dict keys are: “between”, “dataLastUpdated”, “dateGenerated”, “limit”, “offset”, “rowNo”, “total”

Parameters:

  • value (Any) – Value to sanitise.

  • iterate (bool) – If true, then list and dict objects are sanitised recursively. Defaults to True.

Returns:

The sanitised value.

Return type:

Any

send_request(url: str, params: dict | None = None, sanitise: bool = True) → Any

Send a request to an endpoint.

Normally, this method does not need to be called directly. However, if SingStat were to change their API specification but this package has not yet been updated to support that change, then applications may use this method to call the changed endpoints.

If the client had been instantiated with is_test_api=True, then isTestApi=true is added to the list of parameters to send to the endpoint.

Parameters:

  • url (Url) – The endpoint URL to send the request to.

  • params (dict) – List of parameters to be passed to the endpoint URL. Parameter names must match the names required by the endpoints, particularly with typecase (e.g. camelCase). Defaults to None.

  • sanitise (bool) – If true, then the response’s values are sanitised using the sanitise_data() method. Defaults to True.

Raises:

  • APIError – “No data records returned” when count of data is 0.

  • HTTPError – Error occurred during the request process.

Returns:

Response JSON content of the request.

Return type:

Any

singstat.exceptions

Exceptions that could occur when interacting with any API.

exception singstat.exceptions.APIError(message: str, data: Any | None = None, errors: Any | None = None)

Bases: Exception

Error when the API returns an error.

Parameters:

  • message (Any) – The general error message to display when the error is raised.

  • data (Any) – Data response obtained by the calling method. Defaults to None.

  • errors (Any | None) – Other messages that were part of the raised error. Defaults to None.

Return type:

None