data-annotations 2.1.2__py3-none-any.whl

data_annotations/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from data-annotations!")

data_annotations/_decorators.py

@@ -0,0 +1,140 @@
+import inspect
+from collections.abc import Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from data_annotations.description.models import DocumentedArtifact
+    from data_annotations.provenance.models import ProducedFile
+
+DEFAULT_INPUT_ARGS = ("input_path", "input_paths")
+
+
+def bind_arguments(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> inspect.BoundArguments:
+    bound = inspect.signature(fn).bind(*args, **kwargs)
+    bound.apply_defaults()
+    return bound
+
+
+def normalized_path(path: str | Path) -> Path:
+    from data_annotations.provenance import writers as provenance_writers
+
+    return Path(provenance_writers._normalize_local_path(path))
+
+
+def argument_path(
+    bound: inspect.BoundArguments,
+    *,
+    argument_name: str,
+) -> Path:
+    try:
+        value = bound.arguments[argument_name]
+    except KeyError as exc:
+        raise ValueError(
+            f"decorator argument {argument_name!r} was not found in the wrapped call"
+        ) from exc
+    return normalized_path(value)
+
+
+def extract_params(
+    bound: inspect.BoundArguments,
+    *,
+    target_args: Iterable[str],
+    input_args: Iterable[str],
+) -> dict[str, Any]:
+    excluded = set(target_args) | set(input_args)
+    return {
+        name: value for name, value in bound.arguments.items() if name not in excluded
+    }
+
+
+def extract_inputs(
+    bound: inspect.BoundArguments,
+    *,
+    input_args: Iterable[str],
+) -> list[str]:
+    inputs: list[str] = []
+    for name in input_args:
+        if name not in bound.arguments:
+            continue
+        value = bound.arguments[name]
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple, set)):
+            inputs.extend(str(item) for item in value)
+            continue
+        inputs.append(str(value))
+    return inputs
+
+
+def coerce_produced_file(item: Any) -> "ProducedFile":
+    from data_annotations.description.models import DocumentedArtifact
+    from data_annotations.provenance import writers as provenance_writers
+    from data_annotations.provenance.models import ProducedFile
+
+    if isinstance(item, DocumentedArtifact):
+        path = normalized_path(item.path)
+        return ProducedFile(
+            path=str(path),
+            kind=item.kind,
+            sha256=provenance_writers.sha256_file(path) if path.exists() else None,
+        )
+
+    if isinstance(item, ProducedFile):
+        path = normalized_path(item.path)
+        return item.model_copy(update={"path": str(path)})
+
+    if isinstance(item, tuple) and len(item) == 2:
+        path, kind = item
+        normalized = normalized_path(path)
+        return ProducedFile(
+            path=str(normalized),
+            kind=kind,
+            sha256=(
+                provenance_writers.sha256_file(normalized)
+                if normalized.exists()
+                else None
+            ),
+        )
+
+    path = normalized_path(item)
+    return ProducedFile(
+        path=str(path),
+        kind="other",
+        sha256=provenance_writers.sha256_file(path) if path.exists() else None,
+    )
+
+
+def coerce_produced_files(items: Iterable[Any]) -> list["ProducedFile"]:
+    return [coerce_produced_file(item) for item in items]
+
+
+def coerce_documented_artifact(item: Any) -> "DocumentedArtifact":
+    from data_annotations.description.models import DocumentedArtifact
+    from data_annotations.provenance.models import ProducedFile
+
+    if isinstance(item, DocumentedArtifact):
+        return item.model_copy(update={"path": str(normalized_path(item.path))})
+
+    if isinstance(item, ProducedFile):
+        return DocumentedArtifact(
+            path=str(normalized_path(item.path)),
+            kind=item.kind,
+        )
+
+    if isinstance(item, tuple) and len(item) == 2:
+        path, kind = item
+        return DocumentedArtifact(
+            path=str(normalized_path(path)),
+            kind=kind,
+        )
+
+    return DocumentedArtifact(path=str(normalized_path(item)))
+
+
+def coerce_documented_artifacts(items: Iterable[Any]) -> list["DocumentedArtifact"]:
+    return [coerce_documented_artifact(item) for item in items]

data_annotations/annotations/__init__.py

@@ -0,0 +1,30 @@
+from .models import (
+    DirectoryAnnotationDocument,
+    DirectoryAnnotationResult,
+    DirectoryArtifactSubject,
+    FileAnnotationDocument,
+    FileAnnotationResult,
+    FileArtifactSubject,
+)
+from .decorators import record_directory_annotation, record_file_annotation
+from .writers import (
+    annotate_directory,
+    annotate_file,
+    write_directory_annotation,
+    write_file_annotation,
+)
+
+__all__ = [
+    "annotate_directory",
+    "annotate_file",
+    "record_directory_annotation",
+    "record_file_annotation",
+    "write_directory_annotation",
+    "write_file_annotation",
+    "DirectoryAnnotationDocument",
+    "DirectoryAnnotationResult",
+    "DirectoryArtifactSubject",
+    "FileAnnotationDocument",
+    "FileAnnotationResult",
+    "FileArtifactSubject",
+]

data_annotations/annotations/decorators.py

@@ -0,0 +1,147 @@
+from functools import wraps
+from typing import Any, Callable
+
+from data_annotations._decorators import (
+    DEFAULT_INPUT_ARGS,
+    argument_path,
+    bind_arguments,
+    coerce_documented_artifacts,
+    extract_inputs,
+    extract_params,
+)
+from data_annotations.description.models import DocumentedArtifact, FieldDefinition
+from data_annotations.provenance.models import ArtifactKind
+
+from .writers import annotate_directory, annotate_file
+
+
+def record_file_annotation(
+    *,
+    artifact_path_arg: str = "artifact_path",
+    input_args: tuple[str, ...] = DEFAULT_INPUT_ARGS,
+    title: str | None = None,
+    summary: str | None = None,
+    fields: list[FieldDefinition] | None = None,
+    primary_key: list[str] | None = None,
+    missing_value_codes: dict[str, str] | None = None,
+    acquisition_context: dict[str, Any] | None = None,
+    generation_context: dict[str, Any] | None = None,
+    artifact_kind: ArtifactKind = "other",
+    write_readme: bool = True,
+    write_schema: bool | None = None,
+    annotation_suffix: str = ".meta.json",
+    readme_suffix: str = ".README.md",
+):
+    """
+    Decorate a function that writes one annotated artifact.
+
+    Wrapped function contract:
+    - Accept a local output path argument, named ``artifact_path`` by default.
+    - Any bound arguments named in ``input_args`` are recorded as provenance inputs.
+    - Remaining bound arguments become provenance params.
+    - The decorator writes the annotation sidecars from ``artifact_path``.
+    - The return value is not inspected and is returned unchanged.
+    """
+
+    def deco(fn: Callable[..., Any]):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            bound = bind_arguments(fn, args, kwargs)
+            result = fn(*args, **kwargs)
+
+            artifact_path = argument_path(bound, argument_name=artifact_path_arg)
+            params = extract_params(
+                bound,
+                target_args=(artifact_path_arg,),
+                input_args=input_args,
+            )
+            inputs = extract_inputs(bound, input_args=input_args)
+            annotate_file(
+                artifact_path,
+                title=title,
+                summary=summary,
+                fields=fields,
+                primary_key=primary_key,
+                missing_value_codes=missing_value_codes,
+                acquisition_context=acquisition_context,
+                generation_context=generation_context,
+                artifact_kind=artifact_kind,
+                params=params,
+                inputs=inputs,
+                function=fn,
+                write_readme=write_readme,
+                write_schema=write_schema,
+                annotation_suffix=annotation_suffix,
+                readme_suffix=readme_suffix,
+            )
+            return result
+
+        return wrapper
+
+    return deco
+
+
+def record_directory_annotation(
+    *,
+    output_dir_arg: str = "output_dir",
+    input_args: tuple[str, ...] = DEFAULT_INPUT_ARGS,
+    title: str | None = None,
+    summary: str | None = None,
+    acquisition_context: dict[str, Any] | None = None,
+    generation_context: dict[str, Any] | None = None,
+    write_readme: bool = True,
+    write_schema: bool | None = None,
+    annotation_filename: str = "manifest.json",
+    readme_filename: str = "README.md",
+):
+    """
+    Decorate a function that writes several annotated outputs in a directory.
+
+    Wrapped function contract:
+    - Accept a local output directory argument, named ``output_dir`` by default.
+    - Return a materialized iterable, usually a ``list`` or ``tuple``.
+    - Supported return items are:
+      - DocumentedArtifact
+      - ProducedFile
+      - (path, kind)
+      - path-like objects (kind defaults to ``"other"``)
+    - Any bound arguments named in ``input_args`` are recorded as provenance inputs.
+    - Remaining bound arguments become provenance params.
+    - The original return value is passed through unchanged.
+    """
+
+    def deco(fn: Callable[..., Any]):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            bound = bind_arguments(fn, args, kwargs)
+            result = fn(*args, **kwargs)
+
+            items = list(result)
+            output_dir = argument_path(bound, argument_name=output_dir_arg)
+            artifacts: list[DocumentedArtifact] = coerce_documented_artifacts(items)
+            params = extract_params(
+                bound,
+                target_args=(output_dir_arg,),
+                input_args=input_args,
+            )
+            inputs = extract_inputs(bound, input_args=input_args)
+            annotate_directory(
+                output_dir,
+                artifacts=artifacts,
+                title=title,
+                summary=summary,
+                acquisition_context=acquisition_context,
+                generation_context=generation_context,
+                params=params,
+                inputs=inputs,
+                function=fn,
+                write_readme=write_readme,
+                write_schema=write_schema,
+                annotation_filename=annotation_filename,
+                readme_filename=readme_filename,
+            )
+            return result
+
+        return wrapper
+
+    return deco

data_annotations/annotations/models.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from data_annotations.description import DirectoryDescription, FileDescription
+from data_annotations.provenance import BaseProvenance, ProducedFile
+from data_annotations.provenance.models import ArtifactKind
+
+
+class FileArtifactSubject(BaseModel):
+    path: str
+    kind: ArtifactKind = "other"
+    sha256: str | None = None
+
+
+class DirectoryArtifactSubject(BaseModel):
+    path: str
+    produced_files: list[ProducedFile] = Field(default_factory=list)
+
+
+class FileAnnotationDocument(BaseModel):
+    annotation_version: Literal["3"] = "3"
+    subject: FileArtifactSubject
+    provenance: BaseProvenance
+    description: FileDescription
+
+
+class DirectoryAnnotationDocument(BaseModel):
+    annotation_version: Literal["3"] = "3"
+    subject: DirectoryArtifactSubject
+    provenance: BaseProvenance
+    description: DirectoryDescription
+
+
+class FileAnnotationResult(BaseModel):
+    artifact_path: Path
+    annotation_path: Path
+    readme_path: Path | None = None
+
+
+class DirectoryAnnotationResult(BaseModel):
+    output_dir: Path
+    annotation_path: Path
+    readme_path: Path | None = None