amati 0.3.14__tar.gz → 0.3.15__tar.gz

{amati-0.3.14 → amati-0.3.15}/.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.14.6
+  rev: v0.14.8
   hooks:
     # Run the linter.
     - id: ruff-check
@@ -16,4 +16,4 @@ repos:
   rev: v0.7.2
   hooks:
     - id: shellcheck
-      args: [-x]
+      args: [-x]

{amati-0.3.14 → amati-0.3.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amati
-Version: 0.3.14
+Version: 0.3.15
 Summary: Validates that a .yaml or .json file conforms to the OpenAPI Specifications 3.x.
 Project-URL: Homepage, https://github.com/gwyli/amati
 Project-URL: Issues, https://github.com/gwyli/amati/issues

amati-0.3.15/amati/_error_handler.py

@@ -0,0 +1,48 @@
+"""
+Handles Pydantic errors and amati logs to provide a consistent view to the user.
+"""
+
+import json
+from typing import cast
+
+from amati._logging import Log
+
+type JSONPrimitive = str | int | float | bool | None
+type JSONArray = list["JSONValue"]
+type JSONObject = dict[str, "JSONValue"]
+type JSONValue = JSONPrimitive | JSONArray | JSONObject
+
+
+class ErrorHandler:
+    def __init__(self) -> None:
+        self._errors: list[JSONObject] = []
+
+    def register_logs(self, logs: list[Log]):
+        self._errors.extend(cast(list[JSONObject], logs))
+
+    def register_log(self, log: Log):
+        self._errors.append(cast(JSONObject, log))
+
+    def register_errors(self, errors: list[JSONObject]):
+        self._errors.extend(errors)
+
+    def deduplicate(self):
+        """
+        Remove duplicates by converting each dict to a JSON string for comparison.
+        """
+        seen: set[str] = set()
+        unique_data: list[JSONObject] = []
+
+        item: JSONObject
+        for item in self._errors:
+            # Convert to JSON string with sorted keys for consistent hashing
+            item_json = json.dumps(item, sort_keys=True, separators=(",", ":"))
+            if item_json not in seen:
+                seen.add(item_json)
+                unique_data.append(item)
+
+        self._errors = unique_data
+
+    @property
+    def errors(self) -> list[JSONObject]:
+        return self._errors

amati-0.3.15/amati/_references.py

@@ -0,0 +1,226 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from amati.fields import URI, URIType
+
+
+@dataclass(frozen=True)
+class URIReference:
+    """Immutable record of a URI found during validation"""
+
+    uri: URI
+    source_document: Path
+    source_model_name: str  # Just the string name for error reporting
+    source_field: str
+    target_model: type[BaseModel]  # The model type to validate with
+
+    def resolve(self) -> Path:
+        """Resolve URI relative to source document, see
+        https://spec.openapis.org/oas/v3.1.1.html#relative-references-in-api-description-uris
+        """
+
+        if self.uri.scheme == "file":
+            if not self.uri.path:
+                raise ValueError("File URI must have a path component")
+
+            netloc: Path | None = (
+                Path(self.uri.authority)
+                if self.uri.authority
+                else Path(self.uri.host)
+                if self.uri.host
+                else None
+            )
+
+            return (
+                (netloc / self.uri.path).resolve()
+                if netloc
+                else Path(self.uri.path).resolve()
+            )
+
+        if self.uri.type == URIType.ABSOLUTE:
+            raise NotImplementedError("Absolute URI resolution not implemented")
+
+        if self.uri.type == URIType.NETWORK_PATH:
+            return Path(self.uri).resolve()
+
+        if self.uri.type == URIType.RELATIVE:
+            path: Path = self.source_document.parent / self.uri.lstrip("/")
+            return path.resolve()
+
+        if self.uri.type == URIType.JSON_POINTER:
+            path: Path = self.source_document.parent / self.uri.lstrip("#/")
+            return path.resolve()
+
+        # Guard against future changes
+        raise ValueError(f"Unknown URI type: {self.uri.type}")  # pragma: no cover
+
+
+class URIRegistry:
+    """Registry for discovered URIs using the Singleton pattern.
+
+    This class maintains a central registry of all URI references discovered
+    during document validation. It tracks both the URIs themselves and which
+    documents have already been processed to avoid duplicate validation.
+
+    Attributes:
+        _instance: Class-level singleton instance.
+        _uris: List of all registered URI references.
+        _processed: Set of file paths that have been validated.
+    """
+
+    _instance = None
+
+    def __init__(self):
+        """Initialize a new URIRegistry instance.
+
+        Note:
+            This should not be called directly. Use get_instance() instead
+            to obtain the singleton instance.
+        """
+        self._uris: list[URIReference] = []
+        self._processed: set[Path] = set()
+
+    @classmethod
+    def get_instance(cls) -> URIRegistry:
+        """Get or create the singleton instance of URIRegistry.
+
+        Returns:
+            URIRegistry: The singleton instance of the registry.
+        """
+        if cls._instance is None:
+            cls._instance = cls()
+
+        return cls._instance
+
+    def register(self, ref: URIReference):
+        """Register a discovered URI reference.
+
+        Args:
+            ref (URIReference): The URI reference to register, including
+                source document, and target model.
+        """
+
+        if not isinstance(ref, URIReference):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError("ref must be an instance of URIReference")
+
+        self._uris.append(ref)
+
+    def mark_processed(self, path: Path):
+        """Mark a document as having been validated.
+
+        The path is resolved to an absolute path before storage to ensure
+        consistent tracking regardless of how the path was specified.
+
+        Args:
+            path (Path): The file path of the document that has been processed.
+        """
+        self._processed.add(path.resolve())
+
+    def is_processed(self, path: Path) -> bool:
+        """Check if a document has already been validated.
+
+        Args:
+            path (Path): The file path to check.
+
+        Returns:
+            bool: True if the document has been processed, False otherwise.
+        """
+        return path.resolve() in self._processed
+
+    def get_all_references(self) -> list[URIReference]:
+        """Get all discovered URI references.
+
+        Returns:
+            list[URIReference]: A copy of the list of all registered URI
+                references. Returns a copy to prevent external modification
+                of the internal registry.
+        """
+        return self._uris.copy()
+
+    def resolvable(self, path: Path) -> bool:
+        """Check if the file referenced by a URI exists.
+
+        Args:
+            path (Path): The file path to verify.
+
+        Returns:
+            bool: True if the path points to an existing file, False otherwise.
+        """
+        return path.is_file()
+
+    def reset(self):
+        """Reset the registry for a new validation run.
+
+        Clears all registered URIs and processed document records. This is
+        typically called at the beginning of a new validation session.
+        """
+        self._uris.clear()
+        self._processed.clear()
+
+
+class URICollectorMixin(BaseModel):
+    """Mixin for Pydantic models to automatically collect URIs during validation.
+
+    This mixin hooks into the Pydantic model lifecycle to automatically
+    discover and register URI fields during model instantiation. It inspects
+    all fields after validation and registers any URI-type fields with the
+    URIRegistry for subsequent processing.
+
+    The mixin expects a 'current_document' key in the validation context
+    to track the source document for each URI reference.
+    """
+
+    def model_post_init(self, __context: dict[str, Any]) -> None:
+        """Post-initialization hook to collect URI references from model fields.
+
+        This method is automatically called by Pydantic after model validation
+        is complete. It inspects all fields for URI types and registers them
+        with the singleton URIRegistry.
+
+        Args:
+            __context (dict[str, Any]): Validation context dictionary. Expected
+                to contain a 'current_document' key with the path to the source
+                document being validated.
+
+        Note:
+            This method calls super().model_post_init() to ensure compatibility
+            with other mixins and the base model's initialization process.
+
+        Example:
+            Context should be passed during model instantiation:
+            >>> class MyModel(URICollectorMixin, BaseModel):
+            ...     ref: URI
+            >>> model = MyModel.model_validate(
+            ...     {"ref": "http://example.com/resource"},
+            ...     context={"current_document": "/path/to/doc.json"}
+            ... )
+        """
+        super().model_post_init(__context)
+
+        if not __context:
+            return
+
+        current_doc = __context.get("current_document")
+        if not current_doc:
+            return
+
+        # Inspect all fields for URI types
+        for field_name, field_value in self.model_dump().items():
+            if field_value is None:
+                continue
+
+            # Check if this field contains a URI
+            # Adjust this check based on your URI type implementation
+            if isinstance(field_value, URI):
+                ref = URIReference(
+                    uri=field_value,
+                    source_document=Path(current_doc),
+                    source_model_name=self.__class__.__name__,
+                    source_field=field_name,
+                    # The linked document should be validated with the same model type
+                    target_model=self.__class__,
+                )
+                URIRegistry.get_instance().register(ref)

{amati-0.3.14 → amati-0.3.15}/amati/_resolve_forward_references.py

@@ -5,6 +5,7 @@ without all its dependencies. This module rebuilds all models in a module.
 
 import inspect
 import sys
+import typing
 from collections import defaultdict
 from types import ModuleType
 
@@ -26,20 +27,46 @@ class ModelDependencyResolver:
         """Register a Pydantic model for dependency analysis."""
         self.models[model.__name__] = model
 
-    def register_models(self, models: list[type[BaseModel]]) -> None:
-        """Register multiple Pydantic models."""
-        for model in models:
-            self.register_model(model)
+    @staticmethod
+    def extract_all_references(annotation: typing.Any, refs: set[str] | None = None):
+        """
+        Recursively extract all ForwardRef and type references from an annotation.
+
+        Args:
+            annotation: A type annotation (potentially deeply nested)
+            refs: Set to accumulate references (used internally for recursion)
+
+        Returns:
+            Set of either ForwardRef objects or actual type/class objects
+        """
+        if refs is None:
+            refs = set()
+
+        # Direct ForwardRef
+        if isinstance(annotation, typing.ForwardRef):
+            refs.add(annotation.__forward_arg__)
+            return refs
+
+        # Direct class reference
+        if isinstance(annotation, type):
+            refs.add(annotation.__name__)
+            return refs
+
+        for origin in typing.get_args(annotation):
+            ModelDependencyResolver.extract_all_references(origin, refs)
+
+        return refs
 
     def _analyze_model_dependencies(self, model: type[BaseModel]) -> set[str]:
         """Analyze a single model's dependencies from its annotations."""
         dependencies: set[str] = set()
 
         for field_info in model.model_fields.values():
-            # Use a magic value that's an invalid class name for getattr so if
-            # there is no __name__ attribute it won't appear in self.models
-            if (name := getattr(field_info.annotation, "__name__", "!")) in self.models:
-                dependencies.update(name)
+            references = ModelDependencyResolver.extract_all_references(
+                field_info.annotation
+            )
+
+            dependencies.update(ref for ref in references if ref in self.models)
 
         return dependencies
 
@@ -48,18 +75,10 @@ class ModelDependencyResolver:
         self.dependencies.clear()
         self.graph.clear()
 
-        # First pass: collect all dependencies
         for model_name, model in self.models.items():
             deps = self._analyze_model_dependencies(model)
             self.dependencies[model_name] = deps
 
-        # Second pass: build directed graph
-        for model_name, deps in self.dependencies.items():
-            for dep in deps:
-                if dep in self.models:
-                    # Build forward graph (dependency -> dependent)
-                    self.graph[dep].append(model_name)
-
     def _tarjan_scc(self) -> list[list[str]]:
         """Find strongly connected components using Tarjan's algorithm."""
         index_counter = [0]
@@ -76,13 +95,6 @@ class ModelDependencyResolver:
             stack.append(node)
             on_stack[node] = True
 
-            for successor in self.graph[node]:
-                if successor not in index:
-                    strongconnect(successor)
-                    lowlinks[node] = min(lowlinks[node], lowlinks[successor])
-                elif on_stack[successor]:
-                    lowlinks[node] = min(lowlinks[node], index[successor])
-
             if lowlinks[node] == index[node]:
                 component: list[str] = []
                 while True:
@@ -99,41 +111,6 @@ class ModelDependencyResolver:
 
         return sccs
 
-    def _topological_sort_sccs(self, sccs: list[list[str]]) -> list[list[str]]:
-        """Topologically sort the strongly connected components."""
-        # Map each node to its SCC index
-        node_to_scc = {node: i for i, scc in enumerate(sccs) for node in scc}
-
-        # Find dependencies between SCCs
-        dependencies: set[tuple[int, ...]] = set()
-        for node in self.models:
-            for neighbor in self.graph[node]:
-                src_scc, dst_scc = node_to_scc[node], node_to_scc[neighbor]
-                if src_scc != dst_scc:
-                    dependencies.add((src_scc, dst_scc))
-
-        # Count incoming edges for each SCC
-        in_degree = [0] * len(sccs)
-        for _, dst in dependencies:
-            in_degree[dst] += 1
-
-        # Process SCCs with no dependencies first
-        ready = [i for i, deg in enumerate(in_degree) if deg == 0]
-        result: list[list[str]] = []
-
-        while ready:
-            current = ready.pop()
-            result.append(sccs[current])
-
-            # Remove this SCC and update in-degrees
-            for src, dst in dependencies:
-                if src == current:
-                    in_degree[dst] -= 1
-                    if in_degree[dst] == 0:
-                        ready.append(dst)
-
-        return result
-
     def get_rebuild_order(self) -> list[list[str]]:
         """
         Get the order in which models should be rebuilt.
@@ -141,8 +118,7 @@ class ModelDependencyResolver:
         rebuilt together.
         """
         self.build_dependency_graph()
-        sccs = self._tarjan_scc()
-        return self._topological_sort_sccs(sccs)
+        return self._tarjan_scc()
 
     def rebuild_models(self) -> None:
         """Rebuild all registered models in the correct dependency order."""

{amati-0.3.14 → amati-0.3.15}/amati/amati.py

@@ -6,6 +6,7 @@ import importlib
 import json
 import sys
 from pathlib import Path
+from typing import Any
 
 from jinja2 import Environment, FileSystemLoader
 from loguru import logger
@@ -13,9 +14,11 @@ from pydantic import BaseModel, ValidationError
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 from amati._data.refresh import refresh
-from amati._error_handler import handle_errors
+from amati._error_handler import ErrorHandler
 from amati._logging import Log, Logger
+from amati._references import URIRegistry
 from amati._resolve_forward_references import resolve_forward_references
+from amati.fields import URIType
 from amati.file_handler import load_file
 
 type JSONPrimitive = str | int | float | bool | None
@@ -24,15 +27,15 @@ type JSONObject = dict[str, "JSONValue"]
 type JSONValue = JSONPrimitive | JSONArray | JSONObject
 
 
-def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[JSONObject] | None]:
+def _determine_version(data: JSONObject) -> str:
     """
-    Returns the correct model for the passed spec
+    Determines the OpenAPI specification version from the provided data.
 
     Args:
         data: A dictionary representing an OpenAPI specification
 
     Returns:
-        A pydantic model representing the API specification
+        The OpenAPI specification version as a string
     """
 
     version: JSONValue = data.get("openapi")
@@ -43,6 +46,28 @@ def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[JSONObject] | Non
     if not version:
         raise TypeError("An OpenAPI Specfication must contain a version.")
 
+    return version
+
+
+def dispatch(
+    data: JSONObject,
+    context: dict[str, Any],
+    version: str,
+    obj: str = "OpenAPIObject",
+) -> tuple[BaseModel | None, list[JSONObject] | None]:
+    """
+    Returns the correct model for the passed spec
+
+    Args:
+        data: A dictionary representing an OpenAPI specification
+        version: An optional Open API version string to override automatic detection.
+            The most common reason to provide the version is when validating references
+            outside of the context of a full specification document.
+
+    Returns:
+        A pydantic model representing the API specification
+    """
+
     version_map: dict[str, str] = {
         "3.1.1": "311",
         "3.1.0": "311",
@@ -53,18 +78,91 @@ def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[JSONObject] | Non
         "3.0.0": "304",
     }
 
-    module = importlib.import_module(f"amati.validators.oas{version_map[version]}")
+    module_name: str = f"amati.validators.oas{version_map[version]}"
 
+    module = importlib.import_module(module_name)
     resolve_forward_references(module)
 
     try:
-        model = module.OpenAPIObject(**data)
+        model = getattr(module, obj).model_validate(data, context=context)
     except ValidationError as e:
         return None, json.loads(e.json())
 
     return model, None
 
 
+def dispatch_all(spec: Path) -> tuple[BaseModel | None, ErrorHandler]:
+    """ """
+
+    registry = URIRegistry.get_instance()
+    registry.reset()
+
+    error_handler = ErrorHandler()
+    result: BaseModel | None = None
+    version: str | None = None
+
+    to_process: list[tuple[Path, str]] = [(spec, "OpenAPIObject")]
+
+    while to_process:
+        doc_path, obj = to_process.pop(0)
+
+        # Skip if already validated (handles circular references)
+        if registry.is_processed(doc_path):
+            continue
+
+        logger.info(f"Validating: {doc_path}")
+
+        data: JSONObject = load_file(spec)
+
+        # Create validation context with current document path
+        context = {"current_document": str(doc_path)}
+
+        if obj == "OpenAPIObject":
+            version = _determine_version(data)
+        elif version is None:
+            raise ValueError("Version must be set in the OpenAPI object")
+
+        with Logger.context():
+            result, errors = dispatch(data, context, version, obj)
+
+            if errors:
+                error_handler.register_errors(errors)
+
+            error_handler.register_logs(Logger.logs)
+
+        registry.mark_processed(doc_path)
+
+        references = registry.get_all_references()
+
+        # Find references that originated from the document we just validated
+        # and haven't been processed yet
+        for ref in references:
+            if ref.source_document != doc_path:
+                continue
+
+            resolved_path = ref.resolve()
+
+            if registry.is_processed(resolved_path):
+                continue
+
+            if resolved_path.exists() and ref.uri.type != URIType.ABSOLUTE:
+                to_process.append((resolved_path, ref.target_model.__name__))
+            else:
+                # File doesn't exist - record error
+                error_handler.register_log(
+                    Log(
+                        type="missing_reference",
+                        loc=(ref.source_document.name,),
+                        msg=f"Could not locate {ref.uri.type.value} URI",
+                        input=ref.uri,
+                    )
+                )
+
+        references = registry.get_all_references()
+
+    return result, error_handler
+
+
 def check(original: JSONObject, validated: BaseModel) -> bool:
     """
     Runs a consistency check on the output of amati.
@@ -113,15 +211,10 @@ def run(
 
     data = load_file(spec)
 
-    logs: list[Log] = []
-
-    with Logger.context():
-        result, errors = dispatch(data)
-        logs.extend(Logger.logs)
-
-    if errors or logs:
-        handled_errors: list[JSONObject] = handle_errors(errors, logs)
+    result, handled_errors = dispatch_all(spec)
+    handled_errors.deduplicate()
 
+    if handled_errors.errors:
         file_name = Path(Path(file_path).parts[-1])
         error_file = file_name.with_suffix(file_name.suffix + ".errors")
         error_path = spec.parent
@@ -137,7 +230,7 @@ def run(
         )
 
         with json_error_file.open("w", encoding="utf-8") as f:
-            f.write(json.dumps(handled_errors))
+            f.write(json.dumps(handled_errors.errors))
 
         if html_report:
             env = Environment(
@@ -147,7 +240,7 @@ def run(
             template = env.get_template("TEMPLATE.html")
 
             # Render the template with your data
-            html_output = template.render(errors=handled_errors)
+            html_output = template.render(errors=handled_errors.errors)
 
             # Save the output to a file
 

{amati-0.3.14 → amati-0.3.15}/amati/exceptions.py

@@ -10,7 +10,7 @@ class AmatiValueError(ValueError):
 
     Attributes:
         message (str): The explanation of why the exception was raised
-        authority (Optional[ReferenceModel]): The reference to the standard that
+        reference_uri (str | None): The reference to the standard that
             explains why the exception was raised
 
     Inherits:

{amati-0.3.14 → amati-0.3.15}/amati/fields/email.py

@@ -5,7 +5,7 @@ Validates an email according to the RFC5322 ABNF grammar - §3:
 from abnf import ParseError
 from abnf.grammars import rfc5322
 
-from amati import AmatiValueError
+from amati.exceptions import AmatiValueError
 from amati.fields import Str as _Str
 
 reference_uri = "https://www.rfc-editor.org/rfc/rfc5322#section-3"

{amati-0.3.14 → amati-0.3.15}/amati/fields/http_status_codes.py

@@ -9,7 +9,8 @@ or the numeric codes can be accessed via HTTPStatusCodeN.
 import re
 from typing import Self, cast
 
-from amati import AmatiValueError, get
+from amati import get
+from amati.exceptions import AmatiValueError
 from amati.fields import Str as _Str
 
 reference_uri = (

{amati-0.3.14 → amati-0.3.15}/amati/fields/iso9110.py

@@ -8,7 +8,8 @@ and a class for scheme validation.
 
 from typing import cast
 
-from amati import AmatiValueError, get
+from amati import get
+from amati.exceptions import AmatiValueError
 from amati.fields import Str as _Str
 
 reference_uri = (