orangeqs.juice.identifiers._identifiers#

Module Contents#

Functions#

search_ids

Search for identifiers with the given prefix, filtered by name.

new_id

Generate a new identifier with the given prefix.

latest_id

Retrieve the latest identifier with the given prefix.

latest_detailed_id

Retrieve the latest identifier with full detail (name, description).

list_latest_ids

List all the identifiers between a given start and stop time with a given prefix.

list_detailed_latest_ids

List identifiers with full detail (name, description) with a given prefix.

current_ids

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

API#

orangeqs.juice.identifiers._identifiers.search_ids(prefix: str, contains: str | None = None, starts_with: str | None = None, ends_with: str | None = None, start: str = '-1w', stop: str = 'now()', limit: int = 100) → list[orangeqs.juice.schemas.identifiers.Identifier]#

Search for identifiers with the given prefix, filtered by name.

Parameters#

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

  • contains (str, optional): Only return identifiers whose name contains this substring.

  • starts_with (str, optional): Only return identifiers whose name starts with this substring.

  • ends_with (str, optional): Only return identifiers whose name ends with this substring.

  • If more than one of contains, starts_with, and ends_with are

  • provided, an identifier must satisfy all of them to be included

  • (combined with AND).

Returns#

  • (list[Identifier]): Identifiers matching the given prefix and name filters.

orangeqs.juice.identifiers._identifiers.new_id(prefix: str, name: str | None = None, description: str | None = None, allow_name_reuse: bool = False, allowed_devices: dict[str, str] | None = None) → 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.

  • name (str, optional): An optional human-readable name for the identifier, to make it easier to find again later. Must be unique among other identifiers with the same prefix, unless allow_name_reuse is set.

  • description (str, optional): An optional free-text description for the identifier.

  • allow_name_reuse (bool): If True, allow reusing a name that has already been used for this prefix. Defaults to False.

  • allowed_devices (dict[str, str], optional): An optional mapping of device ID to manufacturer, stored on the identifier. Interpretation and enforcement of this mapping is up to the caller; see orangeqs.juice.identifiers.run_id for the run identifier’s use of this field.

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.latest_detailed_id(prefix: str, service: str | None = None, start: str = '-1w', stop: str = 'now()') → orangeqs.juice.schemas.identifiers.Identifier | None#

Retrieve the latest identifier with full detail (name, description).

Similar to latest_id(), but returns the full Identifier object instead of just the plain identifier string.

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#

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

orangeqs.juice.identifiers._identifiers.list_latest_ids(prefix: str, service: str | None = None, start: str = '-1w', stop: str = 'now()', limit: int = 100) → list[str]#

List all the identifiers between a given start and stop time with a given prefix.

Similar to latest_id(), but returns a list of all identifiers between the given start and stop time, instead of just the latest.

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().

  • limit (int): The maximum number of identifiers to return. Defaults to 100.

Returns#

  • (list[str]): A list of identifiers matching the given criteria. Empty if no identifiers are found.

orangeqs.juice.identifiers._identifiers.list_detailed_latest_ids(prefix: str, service: str | None = None, start: str = '-1w', stop: str = 'now()', limit: int = 100) → list[orangeqs.juice.schemas.identifiers.Identifier]#

List identifiers with full detail (name, description) with a given prefix.

Similar to list_latest_ids(), but returns full Identifier objects instead of just the plain identifier strings.

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().

  • limit (int): The maximum number of identifiers to return. Defaults to 100.

Returns#

  • (list[Identifier]): A list of identifiers matching the given criteria. Empty if no identifiers are 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.