singstat

Module contents

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

Client mixin 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: Any, default_params: Any | None = None, key_map: dict[str, str] | None = None, remove_none_values: bool = True) → dict[str, Any]

Build the list of parameters that are compatible for use with the endpoint URLs, e.g. datetime objects to strings.

Parameters:

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

  • original_params (Any) – The set of parameters to use for building. Should be of the same type as what is specified in params_expected_type.

  • default_params (dict[str, Any] or None) – The set of parameters’ default values. Should be of the same type as what is specified in params_expected_type. Defaults to {}, i.e. empty dict.

  • key_map (dict[str, str] or None) – Mapping of keys used in params_expected_types to parameters expected by the endpoint. Defaults to {}, i.e. empty dict.

  • remove_none_values (bool) – If True, then parameters with None values are removed from the returned parameters. Defaults to True.

Returns:

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

Return type:

dict[str, Any]

sanitise_data(value: Any, iterate: bool = True, ignore_keys: list[str] | None = None, key_path: str = '') → Any

Convert the following:

  • If iterate is True and value is a dict or list: sanitise the value’s contents.

  • String with commas: convert to a tuple of numbers if all values are number-like.

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

  • String that is number-like: convert to int or float appropriately.

  • Finally: leave the value as-is.

Parameters:

  • value (Any) – Value to sanitise.

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

  • ignore_keys (list[str] or None) – List of dict keys to ignore when sanitising, if value is a dict. Defaults to [], i.e. empty list.

  • key_path (str) – Current path of key in the dict. Defaults to blank string.

Returns:

The sanitised value.

Return type:

Any

send_request(url: str, params: dict[str, Any] | None = None, cache_duration: int = 0, sanitise: bool = True, sanitise_ignore_keys: list[str] | None = None) → Any

Send a request to an endpoint and return its response.

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[str, Any] or None) – 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 {}, i.e. empty dict.

  • cache_duration (int) – Number of seconds before the cache expires. Defaults to 0, i.e. do not cache.

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

  • sanitise_ignore_keys (list[str] or None) – List of keys to ignore in the response value during sanitising when that response value is a dict. Defaults to [], i.e. empty list.

Raises:

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

  • APIError – “One or more validation errors occurred.” when HTTP 400 status is returned.

  • requests.exceptions.HTTPError – Error occurred during the request process.

  • requests.exceptions.JSONDecodeError – Error occurred when JSON-parsing the response.

Returns:

Response JSON content of the request.

Return type:

Any

singstat.timezone

Standardise all datetime-related timezones to SGT (Singapore Time).

singstat.timezone.datetime_from_string(val: str) → datetime | date | time

Convert a string into a datetime in SGT timezone.

Strings are parsed according to the following formats, in order:

  1. %Y-%m-%dT%H:%M:%S.%f%z

  2. %Y-%m-%dT%H:%M:%S%z

  3. %Y-%m-%dT%H:%M:%S.%f

  4. %Y-%m-%dT%H:%M:%S

  5. %Y%m%dT%H:%M:%S.%f%z

  6. %Y%m%dT%H:%M:%S%z

  7. %Y%m%dT%H:%M:%S.%f

  8. %Y%m%dT%H:%M:%S

  9. %Y-%m-%d %H:%M:%S.%f%z

  10. %Y-%m-%d %H:%M:%S%z

  11. %Y-%m-%d %H:%M:%S.%f

  12. %Y-%m-%d %H:%M:%S

  13. %Y-%m-%d

  14. %Y%m%d

  15. %d/%m/%Y

  16. %H:%M:%S.%f%z

  17. %H:%M:%S%z

  18. %H:%M:%S.%f

  19. %H:%M%z

  20. %H:%M

  21. %H%M

Parameters:

val (str) – String to convert to a datetime.

Raises:

ValueError – val is not a recognised datetime string.

Returns:

The value as a datetime, or date if there is no time, or time if there is no date.

Return type:

datetime or date or time

singstat.exceptions

Exceptions that could occur when interacting with any API endpoint.

exception singstat.exceptions.APIError(message: str = 'Unexpected error occurred.', data: Any = None, errors: Any = None)

Bases: Exception

Error when the API returns an error.

Parameters:

  • message (str) – The general error message to display when the error is raised. Defaults to "Unexpected error occurred.".

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

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

Return type:

None