acquisition-namespace 1.2.0__tar.gz

acquisition_namespace-1.2.0/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# uv
+uv.lock
+
+# Distribution / packaging
+MANIFEST
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+*.cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Build artifacts (hatch-vcs generated)
+src/*/_version.py
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets / local config
+.env
+.env.*
+!.env.example

acquisition_namespace-1.2.0/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) [[ year ]] [[ author_name ]]
+All rights reserved.
+
+No license is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell copies of this software or its documentation without
+explicit written permission from the copyright holder.
+
+Replace this file with your chosen open-source license before publishing.
+Preferred default for research code: GNU GPL v3.0 (retains authorship rights,
+requires attribution and source disclosure for derivatives).
+Permissive alternatives: MIT or BSD-3-Clause (allow commercial use without
+source disclosure — use only if explicitly intended).

acquisition_namespace-1.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: acquisition-namespace
+Version: 1.2.0
+Summary: YAML-driven hierarchical path namespace builder for acquisition data pipelines.
+Project-URL: Repository, https://github.com/murineshiftwork/acquisition-namespace
+Project-URL: Issue Tracker, https://github.com/murineshiftwork/acquisition-namespace/issues
+Author-email: "Lars B. Rollik" <L.B.Rollik@protonmail.com>
+License: Copyright (c) [[ year ]] [[ author_name ]]
+        All rights reserved.
+        
+        No license is granted to use, copy, modify, merge, publish, distribute,
+        sublicense, or sell copies of this software or its documentation without
+        explicit written permission from the copyright holder.
+        
+        Replace this file with your chosen open-source license before publishing.
+        Preferred default for research code: GNU GPL v3.0 (retains authorship rights,
+        requires attribution and source disclosure for derivatives).
+        Permissive alternatives: MIT or BSD-3-Clause (allow commercial use without
+        source disclosure — use only if explicitly intended).
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: commitizen; extra == 'dev'
+Requires-Dist: mkdocs-material; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Acquisition Namespace
+
+YAML-driven hierarchical path namespace builder for acquisition data pipelines.
+
+Define your session directory layout once in a YAML spec; the library builds,
+parses, and validates paths at every level of the hierarchy — with zero
+hard-coded separators or string constants in your application code.
+
+## Installation
+
+```sh
+pip install acquisition-namespace
+```
+
+Or with uv:
+
+```sh
+uv add acquisition-namespace
+```
+
+## Quick start
+
+```python
+from acquisition_namespace import NamespaceBuilder
+
+builder = NamespaceBuilder.from_yaml("my_namespace.yaml")
+
+# Build the session basename from component values
+name = builder.build_path("session", {
+    "subject": "mouse_01",
+    "datetime": "20260524_143022_123456",
+    "task": "sequence",
+})
+# → "mouse_01__20260524_143022_123456__sequence"
+
+# Build the full directory path from root to the session level
+path = builder.generate_path("session", {...})
+# → "mouse_01/mouse_01__20260524_143022_123456__sequence"
+
+# Parse an existing path back into its fields
+parts = builder.extract_level_values("session", name)
+# → {"subject": "mouse_01", "datetime": "...", "task": "sequence"}
+```
+
+### Spec YAML format
+
+```yaml
+version: "1.0"
+description: "My acquisition namespace."
+hierarchy:
+  - subject
+  - session
+  - file
+optional_levels: []
+levels:
+  subject:
+    template: "{subject}"
+    regex: "(?P<subject>[\\w\\-]+)"
+    optional_fields: []
+  session:
+    template: "{subject}__{datetime}__{task}"
+    regex: "(?P<subject>[\\w\\-]+)__(?P<datetime>\\d{8}_\\d{6}(?:_\\d{6})?)__(?P<task>[\\w\\-]+)"
+    optional_fields: []
+  file:
+    template: "{session}.{suffix}.{extension}"
+    regex: "(?P<session>.+)\\.(?P<suffix>\\w+)\\.(?P<extension>\\w+)"
+    optional_fields: []
+```
+
+Higher-level templates may reference lower-level names (e.g. `{session}` in
+the `file` template); the builder resolves them automatically.
+
+## Development setup
+
+```sh
+git clone https://github.com/murineshiftwork/acquisition-namespace.git
+cd acquisition-namespace
+uv sync --group dev
+uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+uv run pytest
+```
+
+## Release workflow
+
+1. Work on a `feature/` or `fix/` branch, committing with `cz commit`
+2. Open a PR — CI (lint + tests + secrets scan) must pass before merge
+3. Merge to main → version bump and tag are created automatically
+4. Tag triggers release: GitHub release + PyPI publish
+
+## License
+
+See [LICENSE](LICENSE).

acquisition_namespace-1.2.0/README.md

@@ -0,0 +1,92 @@
+# Acquisition Namespace
+
+YAML-driven hierarchical path namespace builder for acquisition data pipelines.
+
+Define your session directory layout once in a YAML spec; the library builds,
+parses, and validates paths at every level of the hierarchy — with zero
+hard-coded separators or string constants in your application code.
+
+## Installation
+
+```sh
+pip install acquisition-namespace
+```
+
+Or with uv:
+
+```sh
+uv add acquisition-namespace
+```
+
+## Quick start
+
+```python
+from acquisition_namespace import NamespaceBuilder
+
+builder = NamespaceBuilder.from_yaml("my_namespace.yaml")
+
+# Build the session basename from component values
+name = builder.build_path("session", {
+    "subject": "mouse_01",
+    "datetime": "20260524_143022_123456",
+    "task": "sequence",
+})
+# → "mouse_01__20260524_143022_123456__sequence"
+
+# Build the full directory path from root to the session level
+path = builder.generate_path("session", {...})
+# → "mouse_01/mouse_01__20260524_143022_123456__sequence"
+
+# Parse an existing path back into its fields
+parts = builder.extract_level_values("session", name)
+# → {"subject": "mouse_01", "datetime": "...", "task": "sequence"}
+```
+
+### Spec YAML format
+
+```yaml
+version: "1.0"
+description: "My acquisition namespace."
+hierarchy:
+  - subject
+  - session
+  - file
+optional_levels: []
+levels:
+  subject:
+    template: "{subject}"
+    regex: "(?P<subject>[\\w\\-]+)"
+    optional_fields: []
+  session:
+    template: "{subject}__{datetime}__{task}"
+    regex: "(?P<subject>[\\w\\-]+)__(?P<datetime>\\d{8}_\\d{6}(?:_\\d{6})?)__(?P<task>[\\w\\-]+)"
+    optional_fields: []
+  file:
+    template: "{session}.{suffix}.{extension}"
+    regex: "(?P<session>.+)\\.(?P<suffix>\\w+)\\.(?P<extension>\\w+)"
+    optional_fields: []
+```
+
+Higher-level templates may reference lower-level names (e.g. `{session}` in
+the `file` template); the builder resolves them automatically.
+
+## Development setup
+
+```sh
+git clone https://github.com/murineshiftwork/acquisition-namespace.git
+cd acquisition-namespace
+uv sync --group dev
+uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+uv run pytest
+```
+
+## Release workflow
+
+1. Work on a `feature/` or `fix/` branch, committing with `cz commit`
+2. Open a PR — CI (lint + tests + secrets scan) must pass before merge
+3. Merge to main → version bump and tag are created automatically
+4. Tag triggers release: GitHub release + PyPI publish
+
+## License
+
+See [LICENSE](LICENSE).

acquisition_namespace-1.2.0/VERSION

@@ -0,0 +1 @@
+1.2.0

acquisition_namespace-1.2.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "acquisition-namespace"
+dynamic = ["version"]
+description = "YAML-driven hierarchical path namespace builder for acquisition data pipelines."
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+authors = [
+    { name = "Lars B. Rollik", email = "L.B.Rollik@protonmail.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2",
+    "pyyaml",
+]
+
+[project.urls]
+Repository = "https://github.com/murineshiftwork/acquisition-namespace"
+"Issue Tracker" = "https://github.com/murineshiftwork/acquisition-namespace/issues"
+
+# ---------------------------------------------------------------------------
+# Build
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "1.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/acquisition_namespace/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acquisition_namespace"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/pyproject.toml", "/VERSION"]
+
+# ---------------------------------------------------------------------------
+# Dependencies
+
+[project.optional-dependencies]
+dev = [
+    "commitizen",
+    "pytest>=8",
+    "pytest-cov",
+    "pre-commit",
+    "mypy",
+    "mkdocs-material",
+]
+
+# ---------------------------------------------------------------------------
+# Commitizen
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "commitizen"
+version = "1.2.0"
+version_files = ["VERSION"]
+tag_format = "v$version"
+update_changelog_on_bump = false
+
+# ---------------------------------------------------------------------------
+# Pytest
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src/acquisition_namespace --cov-report=term-missing --maxfail=5"
+
+# ---------------------------------------------------------------------------
+# Ruff
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "UP",       # pyupgrade
+    "B",        # flake8-bugbear
+    "SIM",      # flake8-simplify
+    "PTH",      # flake8-pathlib
+    "TCH",      # flake8-type-checking
+    "PYI",      # flake8-pyi
+    "YTT",      # flake8-2020
+    "N",        # pep8-naming
+]
+ignore = ["E501"]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+# ---------------------------------------------------------------------------
+# Mypy
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "yaml"
+ignore_missing_imports = true
+ignore_errors = true

acquisition_namespace-1.2.0/src/acquisition_namespace/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from acquisition_namespace.spec import (
+    NamespaceBuilder,
+    NamespaceLevelSpec,
+    NamespaceSpec,
+)
+
+try:
+    __version__ = version("acquisition_namespace")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+__all__ = [
+    "NamespaceBuilder",
+    "NamespaceLevelSpec",
+    "NamespaceSpec",
+]

acquisition_namespace-1.2.0/src/acquisition_namespace/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
+
+__commit_id__ = commit_id = None

acquisition_namespace-1.2.0/src/acquisition_namespace/spec.py

@@ -0,0 +1,299 @@
+"""Namespace spec: Pydantic models + YAML-backed NamespaceBuilder.
+
+Load a spec file and build / validate hierarchical acquisition paths:
+
+    builder = NamespaceBuilder.from_yaml("my_namespace.yaml")
+    basename = builder.build_path("session", {"subject": "mouse_01", ...})
+    parts    = builder.extract_level_values("session", basename)
+
+The spec YAML defines a hierarchy of levels, each with a ``template``
+(Python format-string) and a ``regex`` (named capture groups).  Higher
+levels may reference lower-level names in their template; the builder
+resolves them automatically.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import string
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, field_validator
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+
+
+class NamespaceLevelSpec(BaseModel):
+    template: str
+    regex: str
+    optional_fields: list[str] = []
+
+    @field_validator("regex")
+    @classmethod
+    def _check_regex(cls, v: str) -> str:
+        try:
+            re.compile(v)
+        except re.error as exc:
+            raise ValueError(f"Invalid regex {v!r}: {exc}") from exc
+        return v
+
+
+class NamespaceSpec(BaseModel):
+    version: str
+    description: str = ""
+    hierarchy: list[str]
+    optional_levels: list[str] = []
+    levels: dict[str, NamespaceLevelSpec]
+
+    @field_validator("levels")
+    @classmethod
+    def _all_hierarchy_levels_present(cls, v: dict, info: Any) -> dict:
+        if "hierarchy" in (info.data or {}):
+            missing = [h for h in info.data["hierarchy"] if h not in v]
+            if missing:
+                raise ValueError(
+                    f"Hierarchy level(s) {missing} have no entry in 'levels'"
+                )
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Helper
+
+
+def _template_fields(template: str) -> list[str]:
+    return [t[1] for t in string.Formatter().parse(template) if t[1]]
+
+
+# ---------------------------------------------------------------------------
+# NamespaceBuilder
+
+
+class NamespaceBuilder:
+    """Build and validate hierarchical acquisition paths from a YAML spec.
+
+    Each level in the hierarchy has a template (for construction) and a regex
+    (for parsing/validation).  Higher levels may reference lower-level names
+    in their template; the builder resolves them recursively.
+
+    Typical usage::
+
+        b = NamespaceBuilder.from_yaml("my_namespace.yaml")
+
+        # Build a path segment for a given level
+        name = b.build_path("session", {"subject": "m01", "datetime": "20260101"})
+
+        # Build the full directory path from root to a level
+        path = b.generate_path("session", values)
+
+        # Parse an existing path back into its component values
+        parts = b.validate_path(path, stop_at="session")
+
+        # Extract values from a single level's string
+        parts = b.extract_level_values("session", name)
+    """
+
+    def __init__(self, spec: NamespaceSpec) -> None:
+        self.spec = spec
+        self.hierarchy: list[str] = spec.hierarchy
+        self.optional_levels: list[str] = spec.optional_levels
+        self._compiled: dict[str, re.Pattern] = {
+            name: re.compile(level.regex) for name, level in spec.levels.items()
+        }
+
+    # ------------------------------------------------------------------
+    # Construction
+
+    @classmethod
+    def from_yaml(cls, config_path: str | Path) -> NamespaceBuilder:
+        """Load a :class:`NamespaceSpec` from *config_path* and return a builder."""
+        path = Path(config_path)
+        with path.open() as f:
+            data = yaml.safe_load(f)
+        spec = NamespaceSpec.model_validate(data)
+        logging.debug("Loaded NamespaceSpec v%s from %s", spec.version, path)
+        return cls(spec)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> NamespaceBuilder:
+        """Build from a plain dict (e.g. after :meth:`to_dict`)."""
+        return cls(NamespaceSpec.model_validate(data))
+
+    # ------------------------------------------------------------------
+    # Serialisation
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.spec.model_dump()
+
+    def __str__(self) -> str:
+        return f"NamespaceBuilder({json.dumps(self.to_dict())})"
+
+    def __repr__(self) -> str:
+        return f"NamespaceBuilder({self.to_dict()})"
+
+    def write_yaml(self, path: str | Path) -> None:
+        """Serialise the spec back to a YAML file."""
+        with Path(path).open("w") as f:
+            yaml.dump(
+                self.spec.model_dump(),
+                f,
+                default_flow_style=False,
+                allow_unicode=True,
+                sort_keys=False,
+            )
+        logging.info("NamespaceSpec written to %s", path)
+
+    # ------------------------------------------------------------------
+    # Path building
+
+    def _build_one(
+        self, level_name: str, values: dict[str, str], parts: dict[str, str]
+    ) -> str:
+        if level_name in parts:
+            return parts[level_name]
+        level = self.spec.levels[level_name]
+        fields = _template_fields(level.template)
+        for field in fields:
+            if field in self.hierarchy and field not in parts and field != level_name:
+                parts[field] = self._build_one(field, values, parts)
+            elif field not in values and field not in parts:
+                raise ValueError(
+                    f"Missing value for field '{field}' in level '{level_name}'"
+                )
+        fmt = {k: parts.get(k, values.get(k, "")) for k in fields}
+        result = level.template.format(**fmt)
+        parts[level_name] = result
+        return result
+
+    def build_path(self, level: str, values: dict[str, str]) -> str:
+        """Return the path segment string for *level* constructed from *values*.
+
+        Parent levels referenced in the template are resolved automatically.
+        """
+        if level not in self.spec.levels:
+            raise ValueError(f"Unknown level: {level!r}")
+        return self._build_one(level, values, {})
+
+    def generate_path(
+        self,
+        level: str,
+        values: dict[str, str],
+        include_optional_levels: bool = True,
+        level_overrides: dict[str, str] | None = None,
+    ) -> str:
+        """Return the full filesystem path from root up to (and including) *level*.
+
+        Joins each hierarchy level with :func:`pathlib.Path` so the result
+        uses the platform separator.
+
+        Parameters
+        ----------
+        level_overrides:
+            Pre-built segment strings keyed by level name.  When a level
+            appears here its value is used verbatim instead of being
+            constructed from *values*.  The segment is still recorded in the
+            internal parts dict so higher levels can reference it in their
+            templates.  Use this when a level's basename comes from an
+            external system (e.g. an OE acquisition name) and cannot be
+            reconstructed from the current session's values.
+        """
+        if level not in self.hierarchy:
+            raise ValueError(f"Unknown level: {level!r}")
+        overrides = level_overrides or {}
+        parts: dict[str, str] = {}
+        segments: list[str] = []
+        for name in self.hierarchy:
+            if name in self.optional_levels and not include_optional_levels:
+                continue
+            if name in overrides:
+                segment = overrides[name]
+                parts[name] = segment
+            else:
+                segment = self._build_one(name, values, parts)
+            segments.append(segment)
+            if name == level:
+                break
+        return str(Path(*segments))
+
+    # ------------------------------------------------------------------
+    # Parsing / validation
+
+    def _match_level(
+        self, level_name: str, segment: str, known_values: dict[str, str]
+    ) -> dict[str, str]:
+        level = self.spec.levels[level_name]
+        pattern = level.regex
+        for k, v in known_values.items():
+            if v is not None:
+                pattern = pattern.replace("{" + k + "}", re.escape(str(v)))
+        m = re.match(pattern, segment.strip())
+        if not m:
+            raise ValueError(
+                f"Segment {segment!r} did not match regex for level {level_name!r}"
+            )
+        return m.groupdict()
+
+    def validate_path_level(
+        self, level: str, segment: str, known_values: dict[str, str]
+    ) -> dict[str, str]:
+        """Match *segment* against the regex for *level*, return captured groups."""
+        return self._match_level(level, segment, known_values)
+
+    def validate_path(
+        self, path: str | Path, stop_at: str | None = None
+    ) -> dict[str, str]:
+        """Walk *path* level by level and return all captured values.
+
+        Parameters
+        ----------
+        path:
+            Filesystem path to validate (may be absolute or relative).
+        stop_at:
+            Stop after matching this hierarchy level.  If ``None``, walks
+            the entire hierarchy.
+
+        Raises
+        ------
+        ValueError
+            If any segment does not match the expected regex.
+        """
+        if stop_at and stop_at not in self.hierarchy:
+            raise ValueError(f"stop_at level {stop_at!r} is not in hierarchy")
+        max_depth = (
+            self.hierarchy.index(stop_at) + 1 if stop_at else len(self.hierarchy)
+        )
+        segments = Path(path).parts
+        result: dict[str, str] = {}
+        for i, (segment, level_name) in enumerate(
+            zip(segments, self.hierarchy, strict=False)
+        ):
+            if i >= max_depth:
+                break
+            result.update(self._match_level(level_name, segment, result))
+            if level_name == stop_at:
+                break
+        return result
+
+    def extract_level_values(self, level: str, name: str) -> dict[str, str]:
+        """Parse *name* as a *level* segment and return template-field values.
+
+        Unlike :meth:`validate_path` (which walks a directory path), this
+        matches a single string against a single level's regex.
+
+        Raises
+        ------
+        ValueError
+            If *level* is not in the hierarchy, or *name* does not match.
+        """
+        if level not in self.hierarchy:
+            raise ValueError(f"Unknown level: {level!r}")
+        match = self._compiled[level].match(name.strip())
+        if not match:
+            raise ValueError(f"Name {name!r} does not match regex for level {level!r}")
+        fields = _template_fields(self.spec.levels[level].template)
+        return {f: match.groupdict().get(f, "") for f in fields}

acquisition_namespace-1.2.0/tests/conftest.py

@@ -0,0 +1 @@
+from __future__ import annotations

acquisition_namespace-1.2.0/tests/data/namespace.v1.yaml

@@ -0,0 +1,21 @@
+version: "1.0"
+description: "Simplified namespace: subject > session > file; no acquisition level."
+hierarchy:
+  - subject
+  - session
+  - file
+optional_levels: []
+levels:
+  subject:
+    template: "{subject_prefix}{subject_id}_{exp_short_name}_m{mouse_id}_{ear}"
+    regex: "(?P<subject_prefix>[a-zA-Z])(?P<subject_id>\\d{3})_(?P<exp_short_name>\\w+)_m(?P<mouse_id>\\d+)_(?:-(?P<ear>[a-z]))?"
+    optional_fields:
+      - ear
+  session:
+    template: "{subject}__{paradigm}"
+    regex: "(?P<subject>.+)__(?P<paradigm>\\w+)"
+    optional_fields: []
+  file:
+    template: "{session}.{suffix}.{extension}"
+    regex: "(?P<session>.+)\\.(?P<suffix>\\w+)\\.(?P<extension>\\w+)"
+    optional_fields: []

acquisition_namespace-1.2.0/tests/data/namespace.v2.yaml

@@ -0,0 +1,27 @@
+version: "2.0"
+description: "Namespace with subject > acquisition > session > file; acquisition is optional."
+hierarchy:
+  - subject
+  - acquisition
+  - session
+  - file
+optional_levels:
+  - acquisition
+levels:
+  subject:
+    template: "{subject_prefix}{subject_id}_{exp_short_name}_m{mouse_id}_{ear}"
+    regex: "(?P<subject_prefix>[a-zA-Z])(?P<subject_id>\\d{3})_(?P<exp_short_name>\\w+)_m(?P<mouse_id>\\d+)_(?:-(?P<ear>[a-z]))?"
+    optional_fields:
+      - ear
+  acquisition:
+    template: "{subject}__{date}_{time}__{modality}"
+    regex: "(?P<subject>.+)__(?P<date>\\d{8})_(?P<time>\\d{6})__(?P<modality>\\w+)"
+    optional_fields: []
+  session:
+    template: "{acquisition}__{paradigm}"
+    regex: "(?P<acquisition>.+)__(?P<paradigm>\\w+)"
+    optional_fields: []
+  file:
+    template: "{session}.{suffix}.{extension}"
+    regex: "(?P<session>.+)\\.(?P<suffix>\\w+)\\.(?P<extension>\\w+)"
+    optional_fields: []

acquisition_namespace-1.2.0/tests/data/namespace.v3.yaml

@@ -0,0 +1,26 @@
+version: "3.0"
+description: "Full namespace: subject > acquisition > session > file; no optional levels."
+hierarchy:
+  - subject
+  - acquisition
+  - session
+  - file
+optional_levels: []
+levels:
+  subject:
+    template: "{subject_prefix}{subject_id}_{exp_short_name}_m{mouse_id}_{ear}"
+    regex: "(?P<subject_prefix>[a-zA-Z])(?P<subject_id>\\d{3})_(?P<exp_short_name>\\w+)_m(?P<mouse_id>\\d+)_(?:-(?P<ear>[a-z]))?"
+    optional_fields:
+      - ear
+  acquisition:
+    template: "{subject}__{date}_{time}__{modality}"
+    regex: "(?P<subject>.+)__(?P<date>\\d{8})_(?P<time>\\d{6})__(?P<modality>\\w+)"
+    optional_fields: []
+  session:
+    template: "{acquisition}__{paradigm}"
+    regex: "(?P<acquisition>.+)__(?P<paradigm>\\w+)"
+    optional_fields: []
+  file:
+    template: "{session}.{suffix}.{extension}"
+    regex: "(?P<session>.+)\\.(?P<suffix>\\w+)\\.(?P<extension>\\w+)"
+    optional_fields: []

acquisition_namespace-1.2.0/tests/integration/test_placeholder.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+
+def test_placeholder() -> None:
+    """Placeholder integration test — replace with real integration tests."""
+    assert True

acquisition_namespace-1.2.0/tests/unit/test_placeholder.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import acquisition_namespace
+
+
+def test_version() -> None:
+    assert acquisition_namespace.__version__ is not None
+    assert isinstance(acquisition_namespace.__version__, str)

acquisition_namespace-1.2.0/tests/unit/test_spec.py

@@ -0,0 +1,487 @@
+"""Tests for NamespaceBuilder — spec loading, path building, parsing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from acquisition_namespace import NamespaceBuilder, NamespaceLevelSpec, NamespaceSpec
+
+# ---------------------------------------------------------------------------
+# Inline spec fixtures
+
+_SIMPLE_SPEC = {
+    "version": "1.0",
+    "description": "Test spec",
+    "hierarchy": ["subject", "session"],
+    "optional_levels": [],
+    "levels": {
+        "subject": {
+            "template": "{subject}",
+            "regex": r"(?P<subject>[\w\-]+)",
+            "optional_fields": [],
+        },
+        "session": {
+            "template": "{subject}__{datetime}__{task}",
+            "regex": r"(?P<subject>[\w\-]+)__(?P<datetime>\d{8}_\d{6}(?:_\d{6})?)__(?P<task>[\w\-]+)",
+            "optional_fields": [],
+        },
+    },
+}
+
+_V3_SPEC = {
+    "version": "3.0",
+    "description": "Full hierarchy with file level",
+    "hierarchy": ["subject", "session", "file"],
+    "optional_levels": [],
+    "levels": {
+        "subject": {
+            "template": "{prefix}{id}_{exp}_m{mouse}",
+            "regex": r"(?P<prefix>[a-zA-Z])(?P<id>\d{3})_(?P<exp>\w+)_m(?P<mouse>\d+)",
+            "optional_fields": [],
+        },
+        "session": {
+            "template": "{subject}__{date}_{time}__{modality}",
+            "regex": r"(?P<subject>.+)__(?P<date>\d{8})_(?P<time>\d{6})__(?P<modality>\w+)",
+            "optional_fields": [],
+        },
+        "file": {
+            "template": "{session}.{suffix}.{extension}",
+            "regex": r"(?P<session>.+)\.(?P<suffix>\w+)\.(?P<extension>\w+)",
+            "optional_fields": [],
+        },
+    },
+}
+
+_V3_VALUES = {
+    "prefix": "s",
+    "id": "082",
+    "exp": "tabfixed",
+    "mouse": "1099615",
+    "date": "20240502",
+    "time": "131422",
+    "modality": "recording",
+    "suffix": "msw",
+    "extension": "pkl",
+}
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+
+
+# ---------------------------------------------------------------------------
+# NamespaceLevelSpec validation
+
+
+def test_level_spec_invalid_regex_raises():
+    with pytest.raises(ValidationError):
+        NamespaceLevelSpec(template="{x}", regex="(?P<x>[")
+
+
+def test_level_spec_stores_optional_fields():
+    spec = NamespaceLevelSpec(
+        template="{subject}__{tag}",
+        regex=r"(?P<subject>.+)(?:__(?P<tag>\w+))?",
+        optional_fields=["tag"],
+    )
+    assert "tag" in spec.optional_fields
+
+
+# ---------------------------------------------------------------------------
+# NamespaceSpec validation
+
+
+def test_spec_missing_hierarchy_level_raises():
+    with pytest.raises(ValidationError):
+        NamespaceSpec(
+            version="0",
+            hierarchy=["a", "b"],
+            levels={"a": NamespaceLevelSpec(template="{a}", regex=r"(?P<a>.+)")},
+        )
+
+
+def test_spec_optional_levels_stored():
+    spec = NamespaceSpec(
+        version="1",
+        hierarchy=["a", "b"],
+        optional_levels=["b"],
+        levels={
+            "a": NamespaceLevelSpec(template="{a}", regex=r"(?P<a>\w+)"),
+            "b": NamespaceLevelSpec(
+                template="{a}__{b}", regex=r"(?P<a>.+)__(?P<b>\w+)"
+            ),
+        },
+    )
+    assert spec.optional_levels == ["b"]
+
+
+# ---------------------------------------------------------------------------
+# NamespaceBuilder.from_dict
+
+
+def test_from_dict_simple():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    assert b.hierarchy == ["subject", "session"]
+    assert b.spec.version == "1.0"
+
+
+def test_from_dict_v3():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    assert b.hierarchy == ["subject", "session", "file"]
+
+
+# ---------------------------------------------------------------------------
+# NamespaceBuilder.from_yaml / write_yaml
+
+
+def test_from_yaml_write_and_reload(tmp_path):
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    out = tmp_path / "ns.yaml"
+    b.write_yaml(out)
+    b2 = NamespaceBuilder.from_yaml(out)
+    assert b2.hierarchy == b.hierarchy
+    assert b2.spec.version == b.spec.version
+
+
+def test_yaml_roundtrip_preserves_build(tmp_path):
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    out = tmp_path / "ns.yaml"
+    b.write_yaml(out)
+    b2 = NamespaceBuilder.from_yaml(out)
+    values = {
+        "subject": "mouse_01",
+        "datetime": "20260524_143022_123456",
+        "task": "sequence",
+    }
+    assert b2.build_path("session", values) == b.build_path("session", values)
+
+
+def test_write_yaml_preserves_optional_levels(tmp_path):
+    spec_dict = {
+        "version": "2.0",
+        "description": "",
+        "hierarchy": ["subject", "acquisition", "session"],
+        "optional_levels": ["acquisition"],
+        "levels": {
+            "subject": {
+                "template": "{subject}",
+                "regex": r"(?P<subject>\w+)",
+                "optional_fields": [],
+            },
+            "acquisition": {
+                "template": "{subject}__{date}",
+                "regex": r"(?P<subject>.+)__(?P<date>\d{8})",
+                "optional_fields": [],
+            },
+            "session": {
+                "template": "{acquisition}__{task}",
+                "regex": r"(?P<acquisition>.+)__(?P<task>\w+)",
+                "optional_fields": [],
+            },
+        },
+    }
+    b = NamespaceBuilder.from_dict(spec_dict)
+    out = tmp_path / "ns.yaml"
+    b.write_yaml(out)
+    b2 = NamespaceBuilder.from_yaml(out)
+    assert b2.optional_levels == ["acquisition"]
+
+
+# ---------------------------------------------------------------------------
+# Loading from tests/data real YAML
+
+
+def test_from_yaml_v3_data_file():
+    b = NamespaceBuilder.from_yaml(DATA_DIR / "namespace.v3.yaml")
+    assert b.hierarchy == ["subject", "acquisition", "session", "file"]
+    assert b.spec.version == "3.0"
+
+
+def test_v3_data_file_no_optional_levels():
+    b = NamespaceBuilder.from_yaml(DATA_DIR / "namespace.v3.yaml")
+    assert b.optional_levels == []
+
+
+def test_v3_data_file_has_four_levels():
+    b = NamespaceBuilder.from_yaml(DATA_DIR / "namespace.v3.yaml")
+    assert set(b.spec.levels.keys()) == {"subject", "acquisition", "session", "file"}
+
+
+def test_v3_data_file_subject_optional_fields():
+    b = NamespaceBuilder.from_yaml(DATA_DIR / "namespace.v3.yaml")
+    assert "ear" in b.spec.levels["subject"].optional_fields
+
+
+# ---------------------------------------------------------------------------
+# build_path
+
+
+def test_build_path_session():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    result = b.build_path(
+        "session",
+        {
+            "subject": "mouse_01",
+            "datetime": "20260524_143022_123456",
+            "task": "sequence",
+        },
+    )
+    assert result == "mouse_01__20260524_143022_123456__sequence"
+
+
+def test_build_path_subject():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    result = b.build_path("subject", _V3_VALUES)
+    assert result == "s082_tabfixed_m1099615"
+
+
+def test_build_path_session_v3():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    result = b.build_path("session", _V3_VALUES)
+    assert result == "s082_tabfixed_m1099615__20240502_131422__recording"
+
+
+def test_build_path_file_resolves_session_automatically():
+    """The file level references {session}; builder must resolve it from values."""
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    result = b.build_path("file", _V3_VALUES)
+    assert result == "s082_tabfixed_m1099615__20240502_131422__recording.msw.pkl"
+
+
+def test_build_path_unknown_level_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="Unknown level"):
+        b.build_path("bogus", {})
+
+
+def test_build_path_missing_field_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="Missing value"):
+        b.build_path("session", {"subject": "m01"})  # missing datetime and task
+
+
+def test_build_path_idempotent():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    vals = {
+        "subject": "mouse_01",
+        "datetime": "20260524_143022_123456",
+        "task": "sequence",
+    }
+    assert b.build_path("session", vals) == b.build_path("session", vals)
+
+
+# ---------------------------------------------------------------------------
+# generate_path
+
+
+def test_generate_path_to_session():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    path = b.generate_path("session", _V3_VALUES)
+    parts = path.split("/")
+    assert len(parts) == 2
+    assert parts[0] == "s082_tabfixed_m1099615"
+    assert "20240502" in parts[1]
+
+
+def test_generate_path_to_file():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    path = b.generate_path("file", _V3_VALUES)
+    parts = path.split("/")
+    assert len(parts) == 3
+    assert parts[-1].endswith(".msw.pkl")
+
+
+def test_generate_path_unknown_level_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="Unknown level"):
+        b.generate_path("bogus", {})
+
+
+def test_generate_path_to_subject_single_segment():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    path = b.generate_path("subject", _V3_VALUES)
+    assert "/" not in path
+    assert path == "s082_tabfixed_m1099615"
+
+
+# ---------------------------------------------------------------------------
+# extract_level_values
+
+
+def test_extract_session_values():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    vals = b.extract_level_values(
+        "session", "mouse_01__20260524_143022_123456__sequence"
+    )
+    assert vals["subject"] == "mouse_01"
+    assert vals["datetime"] == "20260524_143022_123456"
+    assert vals["task"] == "sequence"
+
+
+def test_extract_legacy_datetime():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    vals = b.extract_level_values("session", "mouse_01__20210718_152153__task")
+    assert vals["datetime"] == "20210718_152153"
+
+
+def test_extract_unknown_level_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="Unknown level"):
+        b.extract_level_values("bogus", "anything")
+
+
+def test_extract_no_match_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="does not match"):
+        b.extract_level_values("session", "this-does-not-match")
+
+
+def test_extract_roundtrip_with_build():
+    """build_path → extract_level_values must recover the original values."""
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    vals = {
+        "subject": "mouse_01",
+        "datetime": "20260524_143022_123456",
+        "task": "sequence",
+    }
+    name = b.build_path("session", vals)
+    recovered = b.extract_level_values("session", name)
+    assert recovered["subject"] == vals["subject"]
+    assert recovered["datetime"] == vals["datetime"]
+    assert recovered["task"] == vals["task"]
+
+
+def test_extract_file_values():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    name = b.build_path("file", _V3_VALUES)
+    parts = b.extract_level_values("file", name)
+    assert parts["suffix"] == "msw"
+    assert parts["extension"] == "pkl"
+
+
+# ---------------------------------------------------------------------------
+# validate_path
+
+
+def test_validate_path_stop_at():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    path = (
+        Path("s082_tabfixed_m1099615")
+        / "s082_tabfixed_m1099615__20240502_131422__recording"
+        / "s082_tabfixed_m1099615__20240502_131422__recording.msw.pkl"
+    )
+    result = b.validate_path(path, stop_at="session")
+    assert result["date"] == "20240502"
+    assert result["modality"] == "recording"
+
+
+def test_validate_path_bad_stop_at_raises():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    with pytest.raises(ValueError, match="not in hierarchy"):
+        b.validate_path("anything", stop_at="bogus")
+
+
+def test_validate_path_full_hierarchy():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    subject = b.build_path("subject", _V3_VALUES)
+    session = b.build_path("session", _V3_VALUES)
+    file = b.build_path("file", _V3_VALUES)
+    path = Path(subject) / session / file
+    result = b.validate_path(path)
+    assert result["prefix"] == "s"
+    assert result["date"] == "20240502"
+    assert result["suffix"] == "msw"
+
+
+def test_validate_path_level_direct():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    vals = b.validate_path_level(
+        "session",
+        "mouse_01__20260524_143022__task",
+        {},
+    )
+    assert vals["subject"] == "mouse_01"
+    assert vals["task"] == "task"
+
+
+# ---------------------------------------------------------------------------
+# to_dict / from_dict round-trip
+
+
+def test_to_dict_roundtrip():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    b2 = NamespaceBuilder.from_dict(b.to_dict())
+    assert b2.hierarchy == b.hierarchy
+    assert b2.spec.version == b.spec.version
+
+
+def test_to_dict_roundtrip_v3():
+    b = NamespaceBuilder.from_dict(_V3_SPEC)
+    b2 = NamespaceBuilder.from_dict(b.to_dict())
+    assert b2.hierarchy == b.hierarchy
+    assert b.build_path("file", _V3_VALUES) == b2.build_path("file", _V3_VALUES)
+
+
+# ---------------------------------------------------------------------------
+# __repr__ / __str__
+
+
+def test_repr_contains_hierarchy():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    r = repr(b)
+    assert "hierarchy" in r
+
+
+def test_str_is_valid_json():
+    b = NamespaceBuilder.from_dict(_SIMPLE_SPEC)
+    s = str(b)
+    # str() wraps the dict in NamespaceBuilder(...); extract JSON part
+    assert s.startswith("NamespaceBuilder(")
+    inner = s[len("NamespaceBuilder(") : -1]
+    parsed = json.loads(inner)
+    assert "hierarchy" in parsed
+
+
+# ---------------------------------------------------------------------------
+# Optional levels
+
+
+def test_optional_level_skipped_in_generate_path():
+    spec = {
+        "version": "1.0",
+        "description": "",
+        "hierarchy": ["subject", "acquisition", "session"],
+        "optional_levels": ["acquisition"],
+        "levels": {
+            "subject": {
+                "template": "{subject}",
+                "regex": r"(?P<subject>[\w]+)",
+                "optional_fields": [],
+            },
+            "acquisition": {
+                "template": "{subject}__{date}",
+                "regex": r"(?P<subject>.+)__(?P<date>\d{8})",
+                "optional_fields": [],
+            },
+            "session": {
+                "template": "{acquisition}__{paradigm}",
+                "regex": r"(?P<acquisition>.+)__(?P<paradigm>\w+)",
+                "optional_fields": [],
+            },
+        },
+    }
+    b = NamespaceBuilder.from_dict(spec)
+    path_with = b.generate_path(
+        "session",
+        {"subject": "m01", "date": "20260101", "paradigm": "ps"},
+        include_optional_levels=True,
+    )
+    path_without = b.generate_path(
+        "session",
+        {"subject": "m01", "date": "20260101", "paradigm": "ps"},
+        include_optional_levels=False,
+    )
+    assert path_with.count("/") == 2  # subject / acquisition / session
+    assert path_without.count("/") == 1  # subject / session