datagovsg

Module contents

Package init.

datagovsg.Economy

alias of Client

datagovsg.Environment

alias of Client

datagovsg.Housing

alias of Client

datagovsg.Transport

alias of Client

datagovsg.datagovsg

Client mixin for interacting with all of the API endpoints.

class datagovsg.datagovsg.DataGovSg(api_key: str | None = None, cache_backend: str | BaseCache = 'sqlite')

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:
static validate_date(kwargs: Any, date_key: str, error_message: str, min_dt: datetime, max_dt: datetime | None = None) → None

Validate that the datetime value in kwargs with key date_key is between min_dt and max_dt (inclusive).

Parameters:

  • kwargs (Any (but is really dict[str, Any])) – The dict of key-value arguments to check for the datetime value.

  • date_key (str) – The key in kwargs that corresponds to the datetime value to check.

  • error_message (str) – The error message to raise if the datetime value is not between min_dt and max_dt.

  • min_dt (datetime) – The earliest possible datetime value.

  • max_dt (datetime or None) – The latest possible datetime value. If None, then implies now datetime. Defaults to None.

Raises:

ValueError – The datetime value is not between min_dt and max_dt.

Returns:

None

Return type:

None

static build_params(params_expected_type: Any, original_params: Any, default_params: dict[str, 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. camelCase parameter names instead of Python’s snake_case, datetime objects to strings.

Parameters:

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

  • original_params (Any but should really be dict) – The set of parameters to use for building.

  • 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 None.

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

  • 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

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 that is like date or datetime: convert to datetime.date or datetime.datetime object 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]) – List of dict keys to ignore when sanitising, if value is a dict. Defaults to [].

  • 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 | 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 Data.gov.sg 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.

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 {}.

  • 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]) – List of keys to ignore in the response value during sanitising when that response value is a dict. Defaults to [].

Raises:

HTTPError – Error occurred during the request process.

Returns:

Results from the response.

Return type:

Any

datagovsg.exceptions

Exceptions that could occur when interacting with any API endpoint.

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

Bases: Exception

Error when the API returns an error.

Parameters:

  • message (Any) – 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