dataretrieval.utils

Data-shaping helpers, and the historical home of the legacy query path.

What is defined here is frame munging that names no service: building a UTC datetime column out of the separate date/time/zone columns a caller points at. The one-shot HTTP query path that used to sit alongside it now lives in dataretrieval._querying, and the WQX3 / legacy-WQP column conventions live in dataretrieval._wqx; nothing here depends on either – the names below are re-exported so their documented dataretrieval.utils paths keep resolving.

By default, do not add new service-specific behavior here.

class dataretrieval.utils.Ambient(name: str, default: _T)

A ContextVar paired with a scoping contextmanager.

Bundles the var and its set/reset-token dance into one object, so an ambient value needs a single declaration instead of a var + setter-function pair. Read the current value with get(); set it for a with block by calling the instance. The previous value is restored on exit:

_base_url = Ambient("ogc_base_url", DEFAULT)
with _base_url(other):
    _base_url.get()  # -> other

__call__(value: _T) → Iterator[None][source]: Set the value for the duration of the with block.

__init__(name: str, default: _T) → None[source]

__weakref__: list of weak references to the object

get() → _T[source]: Return the current value, or the default outside an active scope.

class dataretrieval.utils.BaseMetadata(response: Response)

Base class for metadata.

url

Response url.

Type:: str

query_time

Response elapsed time.

Type:: datetime.timedelta

header

Response headers.

Type:: httpx.Headers

__init__(response: Response) → None[source]

Generate a standard set of metadata informed by the response.

Parameters:: response (httpx.Response) – Response object from the httpx module.

__repr__() → str[source]: Return repr(self).

__weakref__: list of weak references to the object

dataretrieval.utils.format_datetime(df: DataFrame, date_field: str, time_field: str, tz_field: str) → DataFrame[source]

Create a datetime field from separate date, time, and time zone fields.

Assumes ISO 8601.

Parameters:

df (pandas.DataFrame) – A data frame containing date, time, and timezone fields.
date_field (string) – Name of the date column in df.
time_field (string) – Name of the time column in df.
tz_field (string) – Name of the time zone column in df.

Returns:

df – The data frame with a formatted ‘datetime’ column.

Return type:

pandas.DataFrame

dataretrieval.utils.query(url: str, payload: dict[str, Any], delimiter: str = ',', ssl_check: bool = True) → Response

Send a query.

Wrapper for httpx.get that handles errors, converts listed query parameters to comma-separated strings, and returns the response.

Parameters:

url (string) – URL to query.
payload (dict) – Query parameters passed to httpx.get.
delimiter (string) – Delimiter to use with lists.
ssl_check (bool) – Whether to check SSL certificates. Default is True.

Returns:

response – The response from the API query httpx.get function call.

Return type:

httpx.Response

Raises:

DataRetrievalError – On an HTTP error response, the typed subclass for the status (see dataretrieval.exceptions.error_for_status() for the mapping); or NoSitesError when a 200 response reports no data matched; or NetworkError on a connection-level failure (timeout, DNS), with the underlying httpx exception on __cause__.

dataretrieval.utils.to_str(listlike: object, delimiter: str = ',') → str | None

Translate a list-like object into a delimited string.

Parameters:

listlike (list-like object) – A list, or a list-like object (e.g. pandas.core.series.Series).
delimiter (string, optional) – String placed between entries of listlike when it is turned into a string. Default value is a comma.

Returns:

listlike – The listlike object as a string separated by the delimiter.

Return type:

string

Examples

>>> dataretrieval.utils.to_str([1, "a", 2])
'1,a,2'

>>> dataretrieval.utils.to_str([0, 10, 42], delimiter="+")
'0+10+42'