Source code for osprey_connectors.archiver._field_names

"""The field name a channel address is stored under in the archive.

The archive holds one document per instant: ``date`` plus one field per
channel sampled at that instant. MongoDB does not take a field name as a
plain string everywhere it appears: in an update, a query filter or a
projection a ``.`` separates the parts of a path into sub-documents, a leading
``$`` names an operator, and a NUL byte cannot be stored at all. A channel
address carrying any of these is therefore stored under an escaped name.

The escape is ``%XX``, the uppercase hex of the byte: ``%`` is written as
``%25``, ``.`` as ``%2E`` and NUL as ``%00`` wherever they appear, and ``$``
as ``%24`` in the first position only. Every other character is kept.

The archive's documents carry fields of their own: ``_id``, ``date``,
``expireAt``, the densify marker, and the seed manifest's fields. An address
equal to one of them has its first character escaped too (``date`` is stored
as ``%64ate``), so no channel shares a field with the document that holds it.

So an address with no ``%``, no ``.``, no NUL, no leading ``$`` and not equal
to one of those fields is its own field name, byte for byte, and the escape is
injective: two distinct addresses never share a field.

Every writer and every reader of the archive collection names a channel's
field through :func:`field_name`, so a channel is written and read back under
one name. The module imports only the standard library.
"""

from __future__ import annotations

import re

__all__ = ["field_name"]

# The fields the archive's own documents carry beside channels: every
# document's ``_id``; a sample document's ``date``, ``expireAt`` and the densify
# marker ``osprey_densified``; and the seed manifest's ``fingerprint``,
# ``seeded_at``, ``touched_windows``, ``touched_anchor`` and ``coverage``, which
# live in the same collection. A test pins this set against the code that
# writes those fields.
_RESERVED_FIELDS = frozenset(
    {
        "_id",
        "coverage",
        "date",
        "expireAt",
        "fingerprint",
        "osprey_densified",
        "seeded_at",
        "touched_anchor",
        "touched_windows",
    }
)


[docs] def field_name(address: str) -> str: """The field name the archive stores ``address`` under. Args: address: A channel address. Returns: ``address`` with ``%``, ``.`` and NUL escaped as ``%25``, ``%2E`` and ``%00``, a leading ``$`` as ``%24``, and the first character of an address equal to one of the archive's own document fields; ``address`` itself when none of these applies. Raises: ValueError: for the empty address, which has no field name. """ if not address: raise ValueError("an empty channel address has no archive field name") reserved = address in _RESERVED_FIELDS parts: list[str] = [] for position, character in enumerate(address): if character in "%.\x00" or (position == 0 and (character == "$" or reserved)): parts.append(f"%{ord(character):02X}") else: parts.append(character) return "".join(parts)
def _address_of(field: str) -> str: """The channel address stored under ``field``: the inverse of :func:`field_name`. :func:`field_name` escapes every ``%``, so every ``%XX`` in a field name is an escape and decoding them restores the address. """ return re.sub(r"%([0-9A-F]{2})", lambda match: chr(int(match.group(1), 16)), field)