orangeqs.juice.identifiers._identifiers#

Module Contents#

Functions#

new_id

Generate a new identifier with the given prefix.

latest_id

Retrieve the latest identifier with the given prefix.

current_ids

Retrieve the current identifiers for all prefixes used by the current service.

API#

orangeqs.juice.identifiers._identifiers.new_id(prefix: str) → str#

Generate a new identifier with the given prefix.

This function can only be called from a service, and only if the service is configured to manage identifiers with the given prefix. See the identifiers.toml configuration for more details.

Stores the identifier in the database and publish an Identifier event. This synchronizes the identifier across all services that call latest_id() or current_ids().

The identifier will be in the format {prefix}_{service}_{timestamp}, where service is the name of the current service and timestamp is the current UTC time in YYYYMMDDHHMMSS format.

Parameters#

  • prefix (str): The prefix for the identifier.

Returns#

  • (str): The generated identifier.

orangeqs.juice.identifiers._identifiers.latest_id(prefix: str, service: str | None = None, start: str = '-1w', stop: str = 'now()') → str | None#

Retrieve the latest identifier with the given prefix.

The main use case of this function is determining the identifier before querying data from the database or loading files from disk. This function is context-agnostic, meaning it it will produce identical results regardless of where it was called from. It can be called from both services and user containers.

Note that multiple services can generate identifiers with the same prefix. If service is None, the most recent identifier with the given prefix across all services will be returned.

Fetches the most recent identifier through pubsub or from the local cache. If not found, queries InfluxDB to update the cache and tries again.

Parameters#

  • prefix (str): The prefix for the identifier.

  • service (str | None): The service name to filter for. If None, do not filter by service.

  • start (str): The start time for the query, in InfluxDB time format. Defaults to -1w.

  • stop (str): The stop time for the query, in InfluxDB time format. Defaults to now().

Returns#

  • (str | None): The most recent identifier with the given prefix, or None if not found.

orangeqs.juice.identifiers._identifiers.current_ids(context: str | None = None, start: str = '-1w', stop: str = 'now()') → dict[str, str]#

Retrieve the current identifiers for all prefixes used by the current service.

The main use case of this function is to get the identifiers for tagging data before writing to disk or the database. Should be called each time before writing data, to ensure the identifiers are up-to-date.

Determines the identifiers in the context of the current service by default. It is also possible to get the identifiers in the context of a different service by specifying the context parameter.

See the identifiers.toml configuration for more details.

Fetches the most recent identifier through pubsub or from the local cache. If not found, queries InfluxDB to update the cache and tries again.

Parameters#

  • context (str, optional): The service to use as context for retrieving identifiers. Must be the name of a service configured for identifiers. Defaults to None, which means the current service.

  • start (str): The start time for the query, in InfluxDB time format. Defaults to -1w.

  • stop (str): The stop time for the query, in InfluxDB time format. Defaults to now().

Returns#

  • (dict[str, str]): A dictionary mapping prefixes to their most recent identifiers. Contains an entry for each prefix configured for the service.

Raises#

  • (ValueError): If not able to determine the current service context, or if the service is not configured for identifiers, or if no identifier could be found for a configured prefix.