Conventions

class ArchiveKey(StoreKey):
    """The directory holding one archived file, and the files in it.

    Layout: ``archive/5a/6a/cf/5a6acf229ba576d9a40b09292595658bbb74ef56/``

    One checksum is stored once, but it can have arrived by several source
    paths and been read by several text extractors – hence
    [`meta`][ArchiveKey.meta] and [`txt`][ArchiveKey.txt] being keyed rather
    than fixed like [`blob`][ArchiveKey.blob].

    Args:
        checksum: SHA256 checksum of the file
    """

    def __init__(self, checksum: str) -> None:
        super().__init__(ARCHIVE, make_checksum_key(checksum))

    @property
    def blob(self) -> StoreKey:
        """The file's content, stored once per checksum."""
        return self / ARCHIVE_BLOB

    def meta(self, file_id: str) -> StoreKey:
        """Metadata for one file instance.

        Several files with the same checksum but different source paths each
        get their own metadata, keyed by their ``File.id``.

        Layout: ``archive/5a/6a/cf/.../file-abc123.json``

        Args:
            file_id: The ``File.id`` (hash of source path + checksum)

        Raises:
            ValueError: If ``file_id`` is malformed.
        """
        return self / f"{safe_name(file_id, 'file_id')}.json"

    def txt(self, origin: str) -> StoreKey:
        """Extracted text for one extraction origin.

        Several extractions can exist per file, keyed by origin (different OCR
        engines or extraction methods).

        Layout: ``archive/5a/6a/cf/.../{origin}.txt``

        Args:
            origin: The extraction origin / engine name

        Raises:
            ValueError: If ``origin`` is malformed.
        """
        return self / f"{validate_origin(origin)}.txt"

class VersionsKey(CallableKey):
    """``versions/``: a prefix to iterate, and a factory for one snapshot."""

    def __init__(self) -> None:
        super().__init__("versions")

    def __call__(self, name: str, ts: datetime | str | None = None) -> StoreKey:
        """Get a versioned snapshot path for a file (``index.json``, ``config.yml``).

        Layout: ``versions/YYYY/MM/{TS_FORMAT}/<name>``

        Args:
            name: The file name to version (e.g. ``config.yml``, ``index.json``)
            ts: Timestamp of the snapshot, omit to use current time

        Returns:
            Key like ``versions/2025/01/20250115T103000000000Z/config.yml``
        """
        if not isinstance(ts, str):
            ts = make_ts(ts, TS_FORMAT)
        return self / ts[:4] / ts[4:6] / ts / name