vcti-path-format 1.2.0__tar.gz

vcti_path_format-1.2.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_path_format-1.2.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: vcti-path-format
+Version: 1.2.0
+Summary: File format identification framework with heuristic evaluators and feature validators for Python
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: vcti-plugin-catalog>=1.0.1
+Requires-Dist: vcti-lookup>=1.0.1
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Dynamic: license-file
+
+# Path Format
+
+File format identification framework with heuristic evaluators and feature validators for Python.
+
+## Installation
+
+```bash
+pip install vcti-path-format>=1.2.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-path-format>=1.2.0",
+]
+```
+
+---
+
+## Quick Start
+
+```python
+from pathlib import Path
+from vcti.pathformat import (
+    FormatDescriptor,
+    FormatIdentifier,
+    FormatRegistry,
+    MatchConfidence,
+)
+from vcti.pathformat.evaluator import HeuristicEvaluator
+
+# Define a format descriptor with validators
+hdf5_descriptor = FormatDescriptor(
+    id="hdf5-file",
+    name="HDF5 File",
+    evaluator=(
+        HeuristicEvaluator()
+        .check_magic_bytes(b"\x89HDF\r\n\x1a\n")  # GATE
+        .check_extension([".h5", ".hdf5", ".he5"])  # EVIDENCE
+    ),
+    attributes={"path_type": "file", "structure": "hdf5"},
+)
+
+# Register in a format registry
+registry = FormatRegistry()
+registry.register(hdf5_descriptor)
+
+# Identify a file
+identifier = FormatIdentifier(registry)
+results = identifier.identify_file_format(Path("data.h5"))
+
+for result in results:
+    print(f"{result.descriptor.name}: {result.confidence.name}")
+
+# Get best match above a confidence threshold
+best = identifier.get_best_match(
+    Path("data.h5"),
+    min_confidence=MatchConfidence.LIKELY,
+)
+```
+
+---
+
+## Core Concepts
+
+### FormatDescriptor
+
+Extends `Descriptor[Evaluator]` from vcti-plugin-catalog. Wraps an evaluator
+with format metadata and attributes.
+
+### FormatRegistry
+
+Extends `Registry[FormatDescriptor]`. Central catalog of known formats with
+attribute-based filtering via `registry.lookup`.
+
+### FormatIdentifier
+
+Evaluates a path against all (or filtered) registered formats and returns
+results sorted by confidence.
+
+### HeuristicEvaluator
+
+Builder-pattern evaluator that aggregates validation evidence:
+
+```python
+evaluator = (
+    HeuristicEvaluator()
+    .check_magic_bytes(b"\x89PNG\r\n\x1a\n")  # GATE
+    .check_extension([".png"])                   # EVIDENCE
+    .add_validator(custom_validator)             # Custom
+)
+```
+
+**Heuristic rules:**
+- Failed GATE -> `CERTAINLY_NOT`
+- All passed + GATE present -> `DEFINITE`
+- All passed + no GATE -> `LIKELY`
+- Some EVIDENCE failed -> `UNLIKELY`
+- No validators -> `CANT_EVALUATE`
+
+### Feature Validators
+
+| Validator | Role | Tier | Checks |
+|-----------|------|------|--------|
+| `MagicBytesValidator` | GATE | IDENTIFICATION | File signature bytes |
+| `ExtensionValidator` | EVIDENCE | IDENTIFICATION | File extension |
+
+Custom validators implement the `FeatureValidator` protocol.
+
+---
+
+## Validation Tiers
+
+Control evaluation depth with `max_tier`:
+
+| Tier | Cost | Examples |
+|------|------|---------|
+| `IDENTIFICATION` | Cheap | Magic bytes, file extension |
+| `STRUCTURE` | Medium | Schema validation, header parsing |
+| `SEMANTIC` | Expensive | Content analysis, business logic |
+
+```python
+from vcti.pathformat import ValidationTier
+
+# Only run cheap checks
+results = identifier.identify_file_format(path, max_tier=ValidationTier.IDENTIFICATION)
+```
+
+---
+
+## Custom Validators
+
+Implement the `FeatureValidator` protocol to add domain-specific checks:
+
+```python
+from pathlib import Path
+from vcti.pathformat.feature_validator import (
+    FeatureValidator,
+    ValidationResult,
+    ValidationTier,
+    ValidatorRole,
+)
+
+class HeaderValidator:
+    """Checks for a text header line in the first line of a file."""
+
+    id = "header-check"
+    description = "Header line validator"
+    role = ValidatorRole.EVIDENCE
+    tier = ValidationTier.STRUCTURE
+
+    def __init__(self, expected_header: str):
+        self.expected_header = expected_header
+
+    def validate(self, path: Path) -> ValidationResult:
+        try:
+            first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
+            is_passed = first_line.strip() == self.expected_header
+        except (OSError, UnicodeDecodeError):
+            is_passed = False
+        return ValidationResult(
+            validator_id=self.id,
+            role=self.role,
+            is_passed=is_passed,
+            details=f"Header {'matches' if is_passed else 'mismatch'}",
+        )
+
+# Use with the builder pattern
+evaluator = (
+    HeuristicEvaluator()
+    .check_extension([".csv"])
+    .add_validator(HeaderValidator("id,name,value"))
+)
+```
+
+---
+
+## Evaluator Caching
+
+`HeuristicEvaluator` includes an LRU cache keyed by `(path, max_tier)`:
+
+```python
+# Default: 128 entries
+evaluator = HeuristicEvaluator(cache_size=128)
+
+# Disable caching
+evaluator = HeuristicEvaluator(cache_size=0)
+
+# Bypass cache for a single call
+report = descriptor.evaluate(path, use_cache=False)
+
+# Inspect and manage
+info = evaluator.cache_info()  # (hits, misses, maxsize, currsize) or None
+evaluator.clear_cache()
+```
+
+Cache entries become stale if file contents change. Call `clear_cache()` after
+known file modifications, or pass `use_cache=False` for one-off re-evaluation.
+
+---
+
+## Pre-filtering with Rules
+
+```python
+from vcti.lookup import Rule
+
+# Only evaluate formats with structure="hdf5"
+results = identifier.identify_file_format(
+    path,
+    rules=[Rule("structure", "==", "hdf5")],
+)
+```
+
+---
+
+## Error Handling
+
+The framework raises typed exceptions:
+
+| Exception | When |
+|-----------|------|
+| `FileNotFoundError` | Path does not exist |
+| `PathAccessError` | Path is not a file or directory, or cannot be read |
+| `EvaluatorError` | Base class for evaluator errors |
+| `ValidationError` | A validator raised an unexpected exception |
+| `InvalidValidatorError` | Invalid validator passed to builder |
+
+```python
+from vcti.pathformat import PathAccessError
+
+try:
+    results = identifier.identify_file_format(path)
+except FileNotFoundError:
+    print("File not found")
+except PathAccessError as e:
+    print(f"Cannot access path: {e}")
+```
+
+---
+
+## Ecosystem
+
+This package is the identification engine in a three-repo system:
+
+| Package | Role |
+|---------|------|
+| **vcti-path-format** | Framework: evaluators, validators, registry, identifier |
+| [vcti-path-format-attributes](https://pypi.org/project/vcti-path-format-attributes/) | Vocabulary: standardized attribute enums |
+| [vcti-path-format-descriptors](https://pypi.org/project/vcti-path-format-descriptors/) | Built-in format definitions (HDF5, CAX, etc.) |
+
+---
+
+## Dependencies
+
+- [vcti-plugin-catalog](https://pypi.org/project/vcti-plugin-catalog/) (>=1.0.1) — descriptor/registry framework
+- [vcti-lookup](https://pypi.org/project/vcti-lookup/) (>=1.0.1) — attribute-based filtering

vcti_path_format-1.2.0/README.md

@@ -0,0 +1,257 @@
+# Path Format
+
+File format identification framework with heuristic evaluators and feature validators for Python.
+
+## Installation
+
+```bash
+pip install vcti-path-format>=1.2.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-path-format>=1.2.0",
+]
+```
+
+---
+
+## Quick Start
+
+```python
+from pathlib import Path
+from vcti.pathformat import (
+    FormatDescriptor,
+    FormatIdentifier,
+    FormatRegistry,
+    MatchConfidence,
+)
+from vcti.pathformat.evaluator import HeuristicEvaluator
+
+# Define a format descriptor with validators
+hdf5_descriptor = FormatDescriptor(
+    id="hdf5-file",
+    name="HDF5 File",
+    evaluator=(
+        HeuristicEvaluator()
+        .check_magic_bytes(b"\x89HDF\r\n\x1a\n")  # GATE
+        .check_extension([".h5", ".hdf5", ".he5"])  # EVIDENCE
+    ),
+    attributes={"path_type": "file", "structure": "hdf5"},
+)
+
+# Register in a format registry
+registry = FormatRegistry()
+registry.register(hdf5_descriptor)
+
+# Identify a file
+identifier = FormatIdentifier(registry)
+results = identifier.identify_file_format(Path("data.h5"))
+
+for result in results:
+    print(f"{result.descriptor.name}: {result.confidence.name}")
+
+# Get best match above a confidence threshold
+best = identifier.get_best_match(
+    Path("data.h5"),
+    min_confidence=MatchConfidence.LIKELY,
+)
+```
+
+---
+
+## Core Concepts
+
+### FormatDescriptor
+
+Extends `Descriptor[Evaluator]` from vcti-plugin-catalog. Wraps an evaluator
+with format metadata and attributes.
+
+### FormatRegistry
+
+Extends `Registry[FormatDescriptor]`. Central catalog of known formats with
+attribute-based filtering via `registry.lookup`.
+
+### FormatIdentifier
+
+Evaluates a path against all (or filtered) registered formats and returns
+results sorted by confidence.
+
+### HeuristicEvaluator
+
+Builder-pattern evaluator that aggregates validation evidence:
+
+```python
+evaluator = (
+    HeuristicEvaluator()
+    .check_magic_bytes(b"\x89PNG\r\n\x1a\n")  # GATE
+    .check_extension([".png"])                   # EVIDENCE
+    .add_validator(custom_validator)             # Custom
+)
+```
+
+**Heuristic rules:**
+- Failed GATE -> `CERTAINLY_NOT`
+- All passed + GATE present -> `DEFINITE`
+- All passed + no GATE -> `LIKELY`
+- Some EVIDENCE failed -> `UNLIKELY`
+- No validators -> `CANT_EVALUATE`
+
+### Feature Validators
+
+| Validator | Role | Tier | Checks |
+|-----------|------|------|--------|
+| `MagicBytesValidator` | GATE | IDENTIFICATION | File signature bytes |
+| `ExtensionValidator` | EVIDENCE | IDENTIFICATION | File extension |
+
+Custom validators implement the `FeatureValidator` protocol.
+
+---
+
+## Validation Tiers
+
+Control evaluation depth with `max_tier`:
+
+| Tier | Cost | Examples |
+|------|------|---------|
+| `IDENTIFICATION` | Cheap | Magic bytes, file extension |
+| `STRUCTURE` | Medium | Schema validation, header parsing |
+| `SEMANTIC` | Expensive | Content analysis, business logic |
+
+```python
+from vcti.pathformat import ValidationTier
+
+# Only run cheap checks
+results = identifier.identify_file_format(path, max_tier=ValidationTier.IDENTIFICATION)
+```
+
+---
+
+## Custom Validators
+
+Implement the `FeatureValidator` protocol to add domain-specific checks:
+
+```python
+from pathlib import Path
+from vcti.pathformat.feature_validator import (
+    FeatureValidator,
+    ValidationResult,
+    ValidationTier,
+    ValidatorRole,
+)
+
+class HeaderValidator:
+    """Checks for a text header line in the first line of a file."""
+
+    id = "header-check"
+    description = "Header line validator"
+    role = ValidatorRole.EVIDENCE
+    tier = ValidationTier.STRUCTURE
+
+    def __init__(self, expected_header: str):
+        self.expected_header = expected_header
+
+    def validate(self, path: Path) -> ValidationResult:
+        try:
+            first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
+            is_passed = first_line.strip() == self.expected_header
+        except (OSError, UnicodeDecodeError):
+            is_passed = False
+        return ValidationResult(
+            validator_id=self.id,
+            role=self.role,
+            is_passed=is_passed,
+            details=f"Header {'matches' if is_passed else 'mismatch'}",
+        )
+
+# Use with the builder pattern
+evaluator = (
+    HeuristicEvaluator()
+    .check_extension([".csv"])
+    .add_validator(HeaderValidator("id,name,value"))
+)
+```
+
+---
+
+## Evaluator Caching
+
+`HeuristicEvaluator` includes an LRU cache keyed by `(path, max_tier)`:
+
+```python
+# Default: 128 entries
+evaluator = HeuristicEvaluator(cache_size=128)
+
+# Disable caching
+evaluator = HeuristicEvaluator(cache_size=0)
+
+# Bypass cache for a single call
+report = descriptor.evaluate(path, use_cache=False)
+
+# Inspect and manage
+info = evaluator.cache_info()  # (hits, misses, maxsize, currsize) or None
+evaluator.clear_cache()
+```
+
+Cache entries become stale if file contents change. Call `clear_cache()` after
+known file modifications, or pass `use_cache=False` for one-off re-evaluation.
+
+---
+
+## Pre-filtering with Rules
+
+```python
+from vcti.lookup import Rule
+
+# Only evaluate formats with structure="hdf5"
+results = identifier.identify_file_format(
+    path,
+    rules=[Rule("structure", "==", "hdf5")],
+)
+```
+
+---
+
+## Error Handling
+
+The framework raises typed exceptions:
+
+| Exception | When |
+|-----------|------|
+| `FileNotFoundError` | Path does not exist |
+| `PathAccessError` | Path is not a file or directory, or cannot be read |
+| `EvaluatorError` | Base class for evaluator errors |
+| `ValidationError` | A validator raised an unexpected exception |
+| `InvalidValidatorError` | Invalid validator passed to builder |
+
+```python
+from vcti.pathformat import PathAccessError
+
+try:
+    results = identifier.identify_file_format(path)
+except FileNotFoundError:
+    print("File not found")
+except PathAccessError as e:
+    print(f"Cannot access path: {e}")
+```
+
+---
+
+## Ecosystem
+
+This package is the identification engine in a three-repo system:
+
+| Package | Role |
+|---------|------|
+| **vcti-path-format** | Framework: evaluators, validators, registry, identifier |
+| [vcti-path-format-attributes](https://pypi.org/project/vcti-path-format-attributes/) | Vocabulary: standardized attribute enums |
+| [vcti-path-format-descriptors](https://pypi.org/project/vcti-path-format-descriptors/) | Built-in format definitions (HDF5, CAX, etc.) |
+
+---
+
+## Dependencies
+
+- [vcti-plugin-catalog](https://pypi.org/project/vcti-plugin-catalog/) (>=1.0.1) — descriptor/registry framework
+- [vcti-lookup](https://pypi.org/project/vcti-lookup/) (>=1.0.1) — attribute-based filtering

vcti_path_format-1.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-path-format"
+version = "1.2.0"
+description = "File format identification framework with heuristic evaluators and feature validators for Python"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "vcti-plugin-catalog>=1.0.1",
+    "vcti-lookup>=1.0.1",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.pathformat", "vcti.pathformat.*"]
+
+[tool.setuptools.package-data]
+"vcti.pathformat" = ["py.typed"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.pathformat --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_path_format-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_path_format-1.2.0/src/vcti/pathformat/__init__.py

@@ -0,0 +1,29 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.pathformat — File format identification framework with heuristic evaluators."""
+
+from importlib.metadata import version
+
+from .descriptor import FormatDescriptor
+from .evaluator.base import EvaluationReport, Evaluator, MatchConfidence
+from .evaluator.heuristic import PathAccessError
+from .feature_validator.base import ValidationResult, ValidationTier
+from .identifier import FormatIdentifier, IdentificationResult, identify_file_format
+from .registry import FormatRegistry
+
+__version__ = version("vcti-path-format")
+
+__all__ = [
+    "__version__",
+    "EvaluationReport",
+    "Evaluator",
+    "FormatDescriptor",
+    "FormatIdentifier",
+    "FormatRegistry",
+    "IdentificationResult",
+    "MatchConfidence",
+    "PathAccessError",
+    "ValidationResult",
+    "ValidationTier",
+    "identify_file_format",
+]

vcti_path_format-1.2.0/src/vcti/pathformat/descriptor.py

@@ -0,0 +1,94 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Format descriptor for supported file or folder formats.
+
+Defines the FormatDescriptor class, which encapsulates metadata, validation logic,
+and attributes for a specific data format.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from vcti.plugincatalog import Descriptor
+
+from .evaluator.base import EvaluationReport, Evaluator, MatchConfidence
+from .feature_validator.base import ValidationTier
+
+
+class FormatDescriptor(Descriptor[Evaluator]):
+    """Describes a supported data format (file or folder).
+
+    Each FormatDescriptor instance defines the metadata and validation logic
+    for a specific data format. Extends the generic Descriptor with an Evaluator instance.
+
+    Args:
+        id: Unique identifier for the format (e.g., 'csv', 'hdf5-file').
+        name: Human-readable name for the format.
+        evaluator: Evaluator instance for determining match confidence.
+        description: Optional description of the format.
+        attributes: Optional format-specific attributes as key-value pairs.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        evaluator: Evaluator,
+        description: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ):
+        if not isinstance(evaluator, Evaluator):
+            raise TypeError(
+                f"evaluator must be an Evaluator instance, got {type(evaluator).__name__}"
+            )
+        super().__init__(
+            id=id,
+            name=name,
+            instance=evaluator,
+            description=description,
+            attributes=attributes,
+        )
+
+    @property
+    def evaluator(self) -> Evaluator:
+        """Get the evaluator instance."""
+        return self.instance
+
+    def evaluate(
+        self,
+        path: Path,
+        max_tier: ValidationTier = ValidationTier.SEMANTIC,
+        use_cache: bool = True,
+    ) -> EvaluationReport:
+        """Validate file features and evaluate match confidence.
+
+        Args:
+            path: Path to the file or folder to evaluate.
+            max_tier: Maximum validation tier to execute (inclusive).
+            use_cache: If True and evaluator supports caching, use cached results.
+
+        Returns:
+            The evaluation report for format matching.
+        """
+        return self.evaluator.evaluate(path, max_tier, use_cache=use_cache)
+
+    def evaluate_confidence(
+        self,
+        path: Path,
+        max_tier: ValidationTier = ValidationTier.SEMANTIC,
+        use_cache: bool = True,
+    ) -> MatchConfidence:
+        """Convenience wrapper returning only the confidence value.
+
+        Args:
+            path: Path to the file or folder to evaluate.
+            max_tier: Maximum validation tier to execute (inclusive).
+            use_cache: If True and evaluator supports caching, use cached results.
+
+        Returns:
+            The confidence level of the match.
+        """
+        return self.evaluate(path, max_tier, use_cache).confidence
+
+    def __repr__(self) -> str:
+        return f"FormatDescriptor(id={self.id!r}, name={self.name!r})"