amati 0.2.20__tar.gz → 0.2.22__tar.gz

{amati-0.2.20 → amati-0.2.22}/.github/workflows/checks.yaml

@@ -13,6 +13,7 @@ jobs:
     permissions:
       pull-requests: write
       contents: write
+      actions: read
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
@@ -85,6 +86,7 @@ jobs:
         uses: py-cov-action/python-coverage-comment-action@d3db80fe08c357443fa62f4ce5ce4c753d61eba8 # v3
         with:
           GITHUB_TOKEN: ${{ secrets.BOT_COMMENT_TOKEN }}
+        continue-on-error: true
 
       - name: Store Pull Request comment to be posted
         if: steps.check_changes.outputs.relevant == 'true'

{amati-0.2.20 → amati-0.2.22}/.github/workflows/scorecards.yml

@@ -13,6 +13,10 @@ on:
     - cron: '20 7 * * 2'
   push:
     branches: ["main"]
+    paths-ignore:
+      - 'pyproject.toml'
+      - 'uv.lock'
+
 
 # Declare default permissions as read only.
 permissions: read-all

{amati-0.2.20 → amati-0.2.22}/.gitignore

@@ -136,4 +136,7 @@ cython_debug/
 .amati/*
 
 # ruff
-.ruff_cache/
+.ruff_cache/
+
+# sonar
+.sonar/

{amati-0.2.20 → amati-0.2.22}/.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.13.2
+  rev: v0.14.0
   hooks:
     # Run the linter.
     - id: ruff-check
@@ -9,10 +9,11 @@ repos:
     # Run the formatter.
     - id: ruff-format
 - repo: https://github.com/gitleaks/gitleaks
-  rev: v8.16.3
+  rev: v8.28.0
   hooks:
     - id: gitleaks
-- repo: https://github.com/jumanjihouse/pre-commit-hooks
-  rev: 3.0.0
+- repo: https://github.com/koalaman/shellcheck-precommit
+  rev: v0.7.2
   hooks:
     - id: shellcheck
+      args: [-x]

{amati-0.2.20 → amati-0.2.22}/Dockerfile

@@ -10,7 +10,8 @@ COPY amati/ amati/
 
 RUN uv lock \
 && uv sync --locked --no-dev \
-&& adduser --disabled-password --gecos '' appuser && chown -R appuser /app
+&& adduser --disabled-password --gecos '' appuser \
+&& chown -R appuser /app
 
 USER appuser
 

{amati-0.2.20 → amati-0.2.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amati
-Version: 0.2.20
+Version: 0.2.22
 Summary: Validates that a .yaml or .json file conforms to the OpenAPI Specifications 3.x.
 Project-URL: Homepage, https://github.com/ben-alexander/amati
 Project-URL: Issues, https://github.com/ben-alexander/amati/issues
@@ -118,6 +118,7 @@ This project uses:
 * [Ruff](https://docs.astral.sh/ruff/) as a linter and formatter
 * [Hypothesis](https://hypothesis.readthedocs.io/en/latest/index.html) for test data generation
 * [Coverage](https://coverage.readthedocs.io/en/7.6.8/) on both the tests and code for test coverage
+* [Shellcheck](https://github.com/koalaman/shellcheck/wiki) for as SAST for shell scripts
 
 It's expected that there are no errors and 100% of the code is reached and executed. The strategy for test coverage is based on parsing test specifications and not unit tests.
 amati runs tests on the external specifications, detailed in `tests/data/.amati.tests.yaml`. To be able to run these tests the GitHub repos containing the specifications need to be available locally. Specific revisions of the repos can be downloaded by running the following, which will clone the repos into `.amati/amati-tests-specs/<repo-name>`.

{amati-0.2.20 → amati-0.2.22}/README.md

@@ -91,6 +91,7 @@ This project uses:
 * [Ruff](https://docs.astral.sh/ruff/) as a linter and formatter
 * [Hypothesis](https://hypothesis.readthedocs.io/en/latest/index.html) for test data generation
 * [Coverage](https://coverage.readthedocs.io/en/7.6.8/) on both the tests and code for test coverage
+* [Shellcheck](https://github.com/koalaman/shellcheck/wiki) for as SAST for shell scripts
 
 It's expected that there are no errors and 100% of the code is reached and executed. The strategy for test coverage is based on parsing test specifications and not unit tests.
 amati runs tests on the external specifications, detailed in `tests/data/.amati.tests.yaml`. To be able to run these tests the GitHub repos containing the specifications need to be available locally. Specific revisions of the repos can be downloaded by running the following, which will clone the repos into `.amati/amati-tests-specs/<repo-name>`.

{amati-0.2.20 → amati-0.2.22}/amati/amati.py

@@ -92,7 +92,7 @@ def run(
     consistency_check: bool = False,
     local: bool = False,
     html_report: bool = False,
-):
+) -> bool:
     """
     Runs the full amati process on a specific specification file.
 
@@ -220,7 +220,7 @@ def discover(spec: str, discover_dir: str = ".") -> list[Path]:
 if __name__ == "__main__":
     import argparse
 
-    parser = argparse.ArgumentParser(
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
         prog="amati",
         description="""
         Tests whether a OpenAPI specification is valid. Will look an openapi.json
@@ -282,7 +282,7 @@ if __name__ == "__main__":
         "or , media types from IANA",
     )
 
-    args = parser.parse_args()
+    args: argparse.Namespace = parser.parse_args()
 
     logger.remove()  # Remove the default logger
     # Add a new logger that outputs to stderr with a specific format
@@ -301,15 +301,19 @@ if __name__ == "__main__":
             sys.exit(1)
 
     try:
-        specifications = discover(args.spec, args.discover)
+        specifications: list[Path] = discover(args.spec, args.discover)
     except Exception as e:
         logger.error(str(e))
         sys.exit(1)
 
+    specification: Path
     for specification in specifications:
-        successful_check = False
+        successful_check: bool = False
         logger.info(f"Processing specification {specification}")
 
+        # Top-level try/except to ensure one failed spec doesn't stop the rest
+        # from being processed.
+        e: Exception
         try:
             successful_check = run(
                 specification, args.consistency_check, args.local, args.html_report

amati-0.2.22/amati/fields/email.py

@@ -0,0 +1,40 @@
+"""
+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.fields import Str as _Str
+
+reference_uri = "https://www.rfc-editor.org/rfc/rfc5322#section-3"
+
+
+class Email(_Str):
+    """A string subclass representing a validated RFC 5322 email address.
+
+    This class ensures that email addresses conform to the RFC 5322 specification
+    by validating the input during initialization. Invalid addresses raise an
+    AmatiValueError.
+
+    Args:
+        value: The email address string to validate.
+
+    Raises:
+        AmatiValueError: If the value is not a valid RFC 5322 email address.
+
+    Example:
+        >>> email = Email("user@example.com")
+        >>> invalid = Email("not-an-email")
+        Traceback (most recent call last):
+        amati.exceptions.AmatiValueError: message
+    """
+
+    def __init__(self, value: str):
+        try:
+            rfc5322.Rule("address").parse_all(value)
+        except ParseError as e:
+            raise AmatiValueError(
+                f"{value} is not a valid email address", reference_uri
+            ) from e

{amati-0.2.20 → amati-0.2.22}/amati/fields/iso9110.py

@@ -16,7 +16,7 @@ reference_uri = (
 )
 
 
-data = cast(list[dict[str, str]], get("iso9110"))
+data: list[dict[str, str]] = cast(list[dict[str, str]], get("iso9110"))
 
 
 HTTP_AUTHENTICATION_SCHEMES: set[str] = {

{amati-0.2.20 → amati-0.2.22}/amati/fields/spdx_licences.py

@@ -11,7 +11,7 @@ from amati.fields.uri import URI
 
 reference_uri = "https://spdx.org/licenses/"
 
-data = cast(list[dict[str, Any]], get("spdx_licences"))
+data: list[dict[str, Any]] = cast(list[dict[str, Any]], get("spdx_licences"))
 
 # `seeAlso` is the list of URLs associated with each licence
 VALID_LICENCES: dict[str, list[str]] = {

{amati-0.2.20 → amati-0.2.22}/amati/fields/uri.py

@@ -65,9 +65,22 @@ class Scheme(_Str):
 
 
 class URIType(str, Enum):
+    """Enumeration of URI reference types.
+
+    Categorizes different types of URI references as defined in RFC 3986,
+    along with JSON Pointer references from RFC 6901.
+
+    Attributes:
+        ABSOLUTE: A URI with a scheme component (e.g., "https://example.com/path").
+        RELATIVE: A relative reference without a scheme (e.g., "../path/file.json").
+        NETWORK_PATH: A network path reference starting with "//"
+            (e.g., "//example.com").
+        JSON_POINTER: A JSON Pointer as defined in RFC 6901 (e.g., "#/foo/bar/0").
+    """
+
     ABSOLUTE = "absolute"
     RELATIVE = "relative"
-    NON_RELATIVE = "non-relative"
+    NETWORK_PATH = "network-path"
     JSON_POINTER = "JSON pointer"
 
 
@@ -152,7 +165,7 @@ class URI(_Str):
         if self.scheme:
             return URIType.ABSOLUTE
         if self.authority:
-            return URIType.NON_RELATIVE
+            return URIType.NETWORK_PATH
         if self.path:
             if str(self).startswith("#"):
                 return URIType.JSON_POINTER

{amati-0.2.20 → amati-0.2.22}/amati/file_handler.py

@@ -33,16 +33,37 @@ type JSONValue = JSONPrimitive | JSONArray | JSONObject
 
 
 class FileLoader(ABC):
-    """Abstract base class for file loaders."""
+    """Abstract base class for file loaders.
+
+    Defines the interface for loading and parsing files of different formats.
+    Implementations should provide format-specific handling logic.
+    """
 
     @abstractmethod
     def can_handle(self, file_path: Path) -> bool:
-        """Check if this loader can handle the given file."""
+        """Check if this loader can handle the given file.
+
+        Args:
+            file_path: Path to the file to check.
+
+        Returns:
+            True if this loader can handle the file, False otherwise.
+        """
         pass
 
     @abstractmethod
     def load(self, content: str) -> JSONObject:
-        """Load and parse the file content."""
+        """Load and parse the file content.
+
+        Args:
+            content: The raw file content as a string.
+
+        Returns:
+            The parsed content as a JSONObject.
+
+        Raises:
+            May raise implementation-specific exceptions for parsing errors.
+        """
         pass
 
 
@@ -50,9 +71,28 @@ class JSONLoader(FileLoader):
     """Loader for JSON files."""
 
     def can_handle(self, file_path: Path) -> bool:
+        """Check if this loader can handle the given file.
+
+        Args:
+            file_path: Path to the file to check.
+
+        Returns:
+            True if this loader can handle the file, False otherwise.
+        """
         return file_path.suffix.lower() in {".json", ".js"}
 
     def load(self, content: str) -> JSONObject:
+        """Load and parse the file content.
+
+        Args:
+            content: The raw file content as a string.
+
+        Returns:
+            The parsed content as a JSONObject.
+
+        Raises:
+            May raise implementation-specific exceptions for parsing errors.
+        """
         return json.loads(content)
 
 
@@ -60,21 +100,56 @@ class YAMLLoader(FileLoader):
     """Loader for YAML files."""
 
     def can_handle(self, file_path: Path) -> bool:
+        """Check if this loader can handle the given file.
+
+        Args:
+            file_path: Path to the file to check.
+
+        Returns:
+            True if this loader can handle the file, False otherwise.
+        """
         return file_path.suffix.lower() in {".yaml", ".yml"}
 
     def load(self, content: str) -> JSONObject:
+        """Load and parse the file content.
+
+        Args:
+            content: The raw file content as a string.
+
+        Returns:
+            The parsed content as a JSONObject.
+
+        Raises:
+            May raise implementation-specific exceptions for parsing errors.
+        """
         return yaml.safe_load(content)
 
 
 class FileProcessor:
-    """Main processor for handling gzipped and regular files."""
+    """Main processor for handling gzipped and regular files.
+
+    Processes files in various formats (JSON, YAML) with optional gzip compression.
+    Automatically detects compression and selects the appropriate loader based on
+    file extension.
+
+    Attributes:
+        loaders: List of available file loaders for different formats.
+    """
 
     def __init__(self) -> None:
+        """Initialize the FileProcessor with default loaders."""
         self.loaders: list[FileLoader] = [JSONLoader(), YAMLLoader()]
 
     @staticmethod
     def _is_gzip_file(file_path: Path) -> bool:
-        """Check if file is gzipped by reading magic bytes."""
+        """Check if file is gzipped by reading magic bytes.
+
+        Args:
+            file_path: Path to the file to check.
+
+        Returns:
+            True if the file is gzip-compressed, False otherwise.
+        """
         try:
             with open(file_path, "rb") as f:
                 magic = f.read(2)
@@ -84,13 +159,32 @@ class FileProcessor:
 
     @staticmethod
     def _get_decompressed_path(file_path: Path) -> Path:
-        """Get the path without .gz extension for determining file type."""
+        """Get the path without .gz extension for determining file type.
+
+        Args:
+            file_path: Path to the potentially compressed file.
+
+        Returns:
+            The file path with .gz extension removed if present, otherwise
+            the original path unchanged.
+        """
         if file_path.suffix.lower() == ".gz":
             return file_path.with_suffix("")
         return file_path
 
     def _read_file_content(self, file_path: Path) -> str:
-        """Read file content, decompressing if necessary."""
+        """Read file content, decompressing if necessary.
+
+        Args:
+            file_path: Path to the file to read.
+
+        Returns:
+            The file content as a UTF-8 encoded string.
+
+        Raises:
+            OSError: If the file cannot be read.
+            gzip.BadGzipFile: If the file appears to be gzipped but is corrupted.
+        """
         if self._is_gzip_file(file_path):
             with gzip.open(file_path, "rt", encoding="utf-8") as f:
                 return f.read()
@@ -99,7 +193,20 @@ class FileProcessor:
                 return f.read()
 
     def _get_appropriate_loader(self, file_path: Path) -> FileLoader:
-        """Get the appropriate loader for the file type."""
+        """Get the appropriate loader for the file type.
+
+        Determines the correct loader based on the file extension, ignoring
+        any .gz compression extension.
+
+        Args:
+            file_path: Path to the file needing a loader.
+
+        Returns:
+            The appropriate FileLoader instance for the file type.
+
+        Raises:
+            ValueError: If no suitable loader is found for the file type.
+        """
         # Use the decompressed path to determine file type
         target_path = self._get_decompressed_path(file_path)
 

{amati-0.2.20 → amati-0.2.22}/amati/model_validators.py

@@ -21,15 +21,15 @@ class UnknownValue:
 
     _instance = None
 
-    def __new__(cls):
+    def __new__(cls) -> "UnknownValue":
         if cls._instance is None:
             cls._instance = super().__new__(cls)
         return cls._instance
 
-    def __repr__(self):  # pragma: no cover
+    def __repr__(self) -> str:  # pragma: no cover
         return "UNKNOWN"
 
-    def __str__(self):  # pragma: no cover
+    def __str__(self) -> str:  # pragma: no cover
         return "UNKNOWN"
 
 

{amati-0.2.20 → amati-0.2.22}/amati/validators/generic.py

@@ -20,15 +20,30 @@ from amati._logging import Logger
 
 
 class GenericObject(BaseModel):
-    """
-    A generic model to overwrite provide extra functionality
-    to pydantic.BaseModel.
+    """A generic model extending Pydantic BaseModel with enhanced validation.
+
+    Provides additional functionality for handling extra fields, including pattern
+    matching validation and detailed logging of invalid fields. This class validates
+    extra fields against optional regex patterns and logs violations without raising
+    exceptions.
+
+    Attributes:
+        _reference_uri: URI reference for error reporting and documentation.
+        _extra_field_pattern: Optional regex pattern to validate extra field names.
     """
 
     _reference_uri: ClassVar[str] = PrivateAttr()
     _extra_field_pattern: re.Pattern[str] | None = PrivateAttr()
 
     def __init__(self, **data: Any) -> None:
+        """Initialize the model and validate extra fields.
+
+        Logs any fields that are not recognized as valid model fields or aliases
+        when extra fields are not allowed by the model configuration.
+
+        Args:
+            **data: Arbitrary keyword arguments representing model data.
+        """
         super().__init__(**data)
 
         if self.model_config.get("extra") == "allow":
@@ -53,6 +68,15 @@ class GenericObject(BaseModel):
                 )
 
     def model_post_init(self, __context: Any) -> None:
+        """Validate extra fields against the configured pattern after initialization.
+
+        If an extra field pattern is configured, checks all extra fields against
+        the pattern and logs any fields that don't match. This allows for flexible
+        validation of dynamically named fields.
+
+        Args:
+            __context: Pydantic context object passed during initialization.
+        """
         if not self.model_extra:
             return
 
@@ -85,12 +109,14 @@ class GenericObject(BaseModel):
             )
 
     def get_field_aliases(self) -> list[str]:
-        """
-        Gets a list of aliases for confirming whether extra
-        fields are allowed.
+        """Get all field aliases defined for the model.
+
+        Collects aliases from all model fields to help validate whether provided
+        field names are valid, even if they use alias names instead of field names.
 
         Returns:
-            A list of field aliases for the class.
+            A list of all field aliases defined in the model. Empty list if no
+            aliases are defined.
         """
 
         aliases: list[str] = []

{amati-0.2.20 → amati-0.2.22}/amati/validators/oas304.py

@@ -94,7 +94,9 @@ class ReferenceObject(GenericObject):
     as per RFC6901.
     """
 
-    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        extra="forbid", populate_by_name=True
+    )
 
     ref: URI = Field(alias="$ref")
     _reference_uri: ClassVar[str] = (
@@ -225,7 +227,7 @@ class ExternalDocumentationObject(GenericObject):
 class PathsObject(GenericObject):
     """Validates the OpenAPI Specification paths object - §4.8.8"""
 
-    model_config = ConfigDict(extra="allow")
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
 
     @model_validator(mode="before")
     @classmethod
@@ -403,7 +405,7 @@ class ResponsesObject(GenericObject):
     Validates the OpenAPI Specification responses object - §4.8.16
     """
 
-    model_config = ConfigDict(
+    model_config: ClassVar[ConfigDict] = ConfigDict(
         extra="allow",
     )
 
@@ -498,7 +500,7 @@ class CallbackObject(GenericObject):
     Validates the OpenAPI Specification callback object - §4.8.18
     """
 
-    model_config = ConfigDict(extra="allow")
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
 
     # The keys are runtime expressions that resolve to a URL
     # The values are Response Objects or Reference Objects
@@ -664,7 +666,7 @@ class SchemaObject(GenericObject):
     and validated through jsonschema.
     """
 
-    model_config = ConfigDict(
+    model_config: ClassVar[ConfigDict] = ConfigDict(
         populate_by_name=True,
         extra="allow",  # Allow all standard JSON Schema fields
     )

{amati-0.2.20 → amati-0.2.22}/amati/validators/oas311.py

@@ -142,7 +142,9 @@ class ReferenceObject(GenericObject):
     as per RFC6901.
     """
 
-    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        extra="forbid", populate_by_name=True
+    )
 
     ref: URI = Field(alias="$ref")
     summary: str | None
@@ -336,7 +338,7 @@ class SchemaObject(GenericObject):
     and validated through jsonschema.
     """
 
-    model_config = ConfigDict(
+    model_config: ClassVar[ConfigDict] = ConfigDict(
         populate_by_name=True,
         extra="allow",  # Allow all standard JSON Schema fields
     )

{amati-0.2.20 → amati-0.2.22}/bin/checks.sh

@@ -1,9 +1,11 @@
+#!/bin/sh
 ruff check --fix
 ruff format
 python scripts/setup_test_specs.py
 pytest --cov-report term-missing --cov=amati tests
 pytest --doctest-modules amati/
+pyright --verifytypes amati --ignoreexternal
 docker build -t amati -f Dockerfile . 
-cd tests/
+cd tests/ || exit
 docker run -v "$(pwd):/data" amati -d /data --consistency-check
-cd ../
+cd ..

amati-0.2.22/bin/startup.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+uv python install
+. .venv/bin/activate
+uv sync
+pre-commit install

{amati-0.2.20 → amati-0.2.22}/bin/uv-upgrade-from-main.sh

@@ -1,11 +1,12 @@
+#!/bin/sh
 current_branch=$(git rev-parse --abbrev-ref HEAD)
 
 git checkout main
 git pull origin main
-git checkout $current_branch
+git checkout "$current_branch"
 git merge main
 git checkout --theirs uv.lock
 uv lock
 git add uv.lock
 git commit uv.lock -m "chore: upgrade dependencies"
-git push origin $current_branch
+git push origin "$current_branch"

{amati-0.2.20 → amati-0.2.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amati"
-version = "0.2.20"
+version = "0.2.22"
 description = "Validates that a .yaml or .json file conforms to the OpenAPI Specifications 3.x."
 readme = "README.md"
 authors = [
@@ -45,6 +45,7 @@ build-backend = "hatchling.build"
 dev = [
     "hypothesis>=6.131.28",
     "pre-commit>=4.2.0",
+    "pyright>=1.1.406",
     "pytest>=8.3.5",
     "pytest-cov>=6.1.1",
     "ruff>=0.12.1",

{amati-0.2.20 → amati-0.2.22}/tests/data/DigitalOcean-public.v2.errors.json

@@ -10,6 +10,6 @@
         "input": {
             "$ref": "description.yml#/introduction"
         },
-        "url": "https://errors.pydantic.dev/2.11/v/string_type"
+        "url": "https://errors.pydantic.dev/2.12/v/string_type"
     }
 ]

{amati-0.2.20 → amati-0.2.22}/tests/fields/test_uri.py

@@ -159,7 +159,7 @@ def test_uri_non_relative(value: str):
 
     result = URI(candidate)
     assert result == candidate
-    assert result.type == URIType.NON_RELATIVE
+    assert result.type == URIType.NETWORK_PATH
     assert result.is_iri == ("xn--" in candidate.lower())
 
 
@@ -170,7 +170,7 @@ def test_iri_non_relative(value: str):
 
     result = URI(candidate)
     assert result == candidate
-    assert result.type == URIType.NON_RELATIVE
+    assert result.type == URIType.NETWORK_PATH
     assert result.is_iri is True