amati 0.2.29__py3-none-any.whl → 0.3.1__py3-none-any.whl

amati/_logging.py

@@ -10,7 +10,7 @@ from typing import Any, ClassVar, NotRequired, TypedDict
 type LogType = Exception | Warning
 
 
-@dataclass
+@dataclass(frozen=True)
 class Log(TypedDict):
     type: str
     loc: NotRequired[tuple[int | str, ...]]
@@ -20,11 +20,10 @@ class Log(TypedDict):
 
 
 class Logger:
-    """
-    A mixin class that provides logging functionality.
+    """A simple class-level logger for collecting Log objects.
 
-    This class maintains a list of Log messages that are added.
-    It is NOT thread-safe. State is maintained at a global level.
+    This class provides methods for appending logs and managing
+    a logging context that automatically clears the logs.
     """
 
     logs: ClassVar[list[Log]] = []

amati/amati.py

@@ -163,86 +163,39 @@ def run(
     return True
 
 
-def discover(spec: str, discover_dir: str = ".") -> list[Path]:
-    """
-    Finds OpenAPI Specification files to validate
-
-    Args:
-        spec: The path to a specific OpenAPI specification file.
-        discover_dir: The directory to search through.
-    Returns:
-        A list of specifications to validate.
-    """
-
-    specs: list[Path] = []
-
-    # If a spec is provided, check if it exists and erorr if not
-    if spec:
-        spec_path = Path(spec)
-
-        if not spec_path.exists():
-            raise FileNotFoundError(f"File {spec} does not exist.")
-
-        if not spec_path.is_file():
-            raise IsADirectoryError(f"{spec} is a directory, not a file.")
-
-        specs.append(spec_path)
-
-        # End early if we're not also trying to find files
-        if not discover_dir:
-            return specs
-
-    if Path("openapi.json").exists():
-        specs.append(Path("openapi.json"))
-
-    if Path("openapi.yaml").exists():
-        specs.append(Path("openapi.yaml"))
-
-    if specs:
-        return specs
-
-    if discover_dir == ".":
-        raise FileNotFoundError(
-            "openapi.json or openapi.yaml can't be found, use --discover or --spec."
-        )
-
-    specs = specs + list(Path(discover_dir).glob("**/openapi.json"))
-    specs = specs + list(Path(discover_dir).glob("**/openapi.yaml"))
-
-    if not specs:
-        raise FileNotFoundError(
-            "openapi.json or openapi.yaml can't be found, use --spec."
-        )
-
-    return specs
-
-
 if __name__ == "__main__":
+    logger.remove()  # Remove the default logger
+    # Add a new logger that outputs to stderr with a specific format
+    logger.add(sys.stderr, format="{time} | {level} | {message}")
+
     import argparse
 
     parser: argparse.ArgumentParser = argparse.ArgumentParser(
         prog="amati",
         description="""
-        Tests whether a OpenAPI specification is valid. Will look an openapi.json
-        or openapi.yaml file in the directory that amati is called from. If
-        --discover is set will search the directory tree. If the specification
-        does not follow the naming recommendation the --spec switch should be
-        used.
-
-        Creates a file <filename>.errors.json alongside the original specification
-        containing a JSON representation of all the errors.
+        Tests whether a OpenAPI specification is valid. Creates a file
+        <filename>.errors.json alongside the original specification containing
+        a JSON representation of all the errors.
+
+        Optionally creates an HTML report of the errors, and performs an internal
+        consistency check to verify that the output of the validation is identical
+        to the input.
         """,
         suggest_on_error=True,
     )
 
-    parser.add_argument(
+    subparsers: argparse.Action = parser.add_subparsers(required=True, dest="command")
+
+    validation: argparse.ArgumentParser = subparsers.add_parser("validate")
+
+    validation.add_argument(
         "-s",
         "--spec",
-        required=False,
-        help="The specification to be parsed",
+        required=True,
+        help="The specification to be validated",
     )
 
-    parser.add_argument(
+    validation.add_argument(
         "--consistency-check",
         required=False,
         action="store_true",
@@ -250,48 +203,44 @@ if __name__ == "__main__":
         " parsed specification",
     )
 
-    parser.add_argument(
-        "-d",
-        "--discover",
-        required=False,
-        default=".",
-        help="Searches the specified directory tree for openapi.yaml or openapi.json.",
-    )
-
-    parser.add_argument(
+    validation.add_argument(
         "--local",
         required=False,
         action="store_true",
-        help="Store errors local to the caller in a file called <file-name>.errors.json"
-        "; a .amati/ directory will be created.",
+        help="Store errors local to the caller in .amati/<file-name>.errors.json",
     )
 
-    parser.add_argument(
+    validation.add_argument(
         "--html-report",
         required=False,
         action="store_true",
         help="Creates an HTML report of the errors, called <file-name>.errors.html,"
-        " alongside the original file or in a .amati/ directory if the --local switch"
-        " is used",
+        " alongside <filename>.errors.json",
     )
 
-    parser.add_argument(
-        "--refresh-data",
+    refreshment: argparse.ArgumentParser = subparsers.add_parser("refresh")
+
+    refreshment.add_argument(
+        "--type",
         required=False,
-        action="store_true",
-        help="Refreshes the local data files used by amati, such as HTTP status codes "
-        "or , media types from IANA",
+        default="all",
+        choices=[
+            "all",
+            "http_status_code",
+            "iso9110",
+            "media_types",
+            "schemes",
+            "spdx_licences",
+            "tlds",
+        ],
+        help="The type of data to refresh. Defaults to all.",
     )
 
     args: argparse.Namespace = parser.parse_args()
 
-    logger.remove()  # Remove the default logger
-    # Add a new logger that outputs to stderr with a specific format
-    logger.add(sys.stderr, format="{time} | {level} | {message}")
-
     logger.info("Starting amati")
 
-    if args.refresh_data:
+    if args.command == "refresh":
         logger.info("Refreshing data.")
         try:
             refresh("all")
@@ -301,32 +250,24 @@ if __name__ == "__main__":
             logger.error(f"Error refreshing data: {str(e)}")
             sys.exit(1)
 
+    specification: Path = Path(args.spec)
+    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:
-        specifications: list[Path] = discover(args.spec, args.discover)
+        successful_check: bool = run(
+            specification, args.consistency_check, args.local, args.html_report
+        )
+        logger.info(f"Specification {specification} processed successfully.")
     except Exception as e:
-        logger.error(str(e))
+        logger.error(f"Error processing {specification}, {str(e)}")
         sys.exit(1)
 
-    specification: Path
-    for specification in specifications:
-        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
-            )
-            logger.info(f"Specification {specification} processed successfully.")
-        except Exception as e:
-            logger.error(f"Error processing {specification}, {str(e)}")
-            sys.exit(1)
-
-        if args.consistency_check and successful_check:
-            logger.info(f"Consistency check successful for {specification}")
-        elif args.consistency_check:
-            logger.info(f"Consistency check failed for {specification}")
+    if args.consistency_check and successful_check:
+        logger.info(f"Consistency check successful for {specification}")
+    elif args.consistency_check:
+        logger.info(f"Consistency check failed for {specification}")
 
     logger.info("Stopping amati.")

{amati-0.2.29.dist-info → amati-0.3.1.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: amati
-Version: 0.2.29
+Version: 0.3.1
 Summary: Validates that a .yaml or .json file conforms to the OpenAPI Specifications 3.x.
-Project-URL: Homepage, https://github.com/gwyil/amati
-Project-URL: Issues, https://github.com/gwyil/amati/issues
+Project-URL: Homepage, https://github.com/gwyli/amati
+Project-URL: Issues, https://github.com/gwyli/amati/issues
 Author-email: Ben <2551337+ben-alexander@users.noreply.github.com>
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
@@ -42,42 +42,33 @@ amati is designed to validate that a file conforms to the [OpenAPI Specification
 ## Usage
 
 ```sh
-python amati/amati.py --help
-usage: amati [-h] [-s SPEC] [--consistency-check] [-d DISCOVER] [--local] [--html-report]
-
-Tests whether a OpenAPI specification is valid. Will look an openapi.json or openapi.yaml file in the directory that
-amati is called from. If --discover is set will search the directory tree. If the specification does not follow the
-naming recommendation the --spec switch should be used. Creates a file <filename>.errors.json alongside the original
-specification containing a JSON representation of all the errors.
+python amati/amati.py validate --help
+usage: amati validate [-h] -s SPEC [--consistency-check] [--local] [--html-report]
 
 options:
   -h, --help            show this help message and exit
-  -s, --spec SPEC       The specification to be parsed
+  -s, --spec SPEC       The specification to be validated
   --consistency-check   Runs a consistency check between the input specification and the parsed specification
-  -d, --discover DISCOVER
-                        Searches the specified directory tree for openapi.yaml or openapi.json.
-  --local               Store errors local to the caller in a file called <file-name>.errors.json; a .amati/ directory
-                        will be created.
-  --html-report         Creates an HTML report of the errors, called <file-name>.errors.html, alongside the original
-                        file or in a .amati/ directory if the --local switch is used
+  --local               Store errors local to the caller in .amati/<file-name>.errors.json
+  --html-report         Creates an HTML report of the errors, called <file-name>.errors.html, alongside <filename>.errors.json
 ```
 
 ### Docker
 
 A Dockerfile is available on [DockerHub](https://hub.docker.com/r/benale/amati/tags) or `docker pull benale/amati:alpha`.
 
-Whilst an alpha build only the image tagged `alpha` will be maintained. If there are breaking API changes these will be detailed in releases going forward. Releases can be separately watched using the custom option when watching this repository.
+Whilst an alpha build, only the image tagged `alpha` will be maintained. If there are breaking API changes these will be detailed in releases. Releases can be separately watched using the custom option when watching this repository.
 
 To run against a specific specification the location of the specification needs to be mounted in the container.
 
 ```sh
-docker run -v "<path-to-specification>:/<mount-name> benale/amati:alpha <options>
+docker run -v "<path-to-specification>:/<mount-name> benale/amati:alpha validate --spec <path-to-spec> <options>
 ```
 
 e.g. where you have a specification located in `/Users/myuser/myrepo/myspec.yaml` and create a mount `/data`:
 
 ```sh
-docker run -v /Users/myuser/myrepo:/data benale/amati:alpha --spec /data/myspec.yaml --html-report
+docker run -v /Users/myuser/myrepo:/data benale/amati:alpha validate --spec /data/myspec.yaml --html-report
 ```
 
 ### PyPI
@@ -86,14 +77,13 @@ amati is [available on PyPI](https://pypi.org/project/amati/), to run everything
 
 ```py
 >>> from amati import amati
->>> check = amati.run('tests/data/openapi.yaml', consistency_check=True, local=True, html_report=True)
->>> check
+>>> amati.run('tests/data/openapi.yaml', consistency_check=True, local=True, html_report=True)
 True
 ```
 
 ## Architecture
 
-amati uses Pydantic, especially the validation, and Typing to construct the entire OAS as a single data type. Passing a dictionary to the top-level data type runs all the validation in the Pydantic models constructing a single set of inherited classes and datatypes that validate that the API specification is accurate. To the extent that Pydantic is functional, amati has a [functional core and an imperative shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell).
+amati uses [Pydantic](https://docs.pydantic.dev/latest/), especially the validation, and [typing](https://docs.python.org/3/library/typing.html) to construct the entire OAS as a single data type. Passing a dictionary to the top-level data type runs all the validation in the Pydantic models constructing a single set of inherited classes and datatypes that validate that the API specification is accurate. To the extent that Pydantic is functional, amati has a [functional core and an imperative shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell).
 
 Where the specification conforms, but relies on implementation-defined behavior (e.g. [data type formats](https://spec.openapis.org/oas/v3.1.1.html#data-type-format)), a warning will be raised.
 
@@ -130,7 +120,7 @@ It's expected that there are no errors and 100% of the code is reached and execu
 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>`.
 
 ```sh
-python scripts/tests/setup_test_specs.py
+python scripts/setup_test_specs.py
 ```
 
 If there are some issues with the specification a JSON file detailing those should be placed into `tests/data/` and the name of that file noted in `tests/data/.amati.tests.yaml` for the test suite to pick it up and check that the errors are expected. Any specifications that close the coverage gap are gratefully received.
@@ -152,18 +142,22 @@ docker build -t amati -f Dockerfile .
 to run against a specific specification the location of the specification needs to be mounted in the container.
 
 ```sh
-docker run -v "<path-to-specification>:/<mount-name> amati <options>
+docker run -v "<path-to-specification>:/<mount-name> amati validate -s <path-to-spec> <options>
 ```
 
 This can be tested against a provided specification, from the root directory
 
 ```sh
-docker run --detach -v "$(pwd):/data" amati <options>
+docker run --detach -v "$(pwd):/data" amati validate  -s <path-to-spec> <options>
 ```
 
 
 ### Data
 
-There are some scripts to create the data needed by the project, for example, all the registered TLDs. To refresh the data, run the contents of `/scripts/data`.
+There are some scripts to create the data needed by the project, for example, all the registered TLDs. To refresh the data, run:
+
+```py
+python amati/amati.py refresh
+```
 
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gwyli/amati/badge)](https://scorecard.dev/viewer/?uri=github.com/gwyli/amati)

{amati-0.2.29.dist-info → amati-0.3.1.dist-info}/RECORD

@@ -1,8 +1,8 @@
 amati/__init__.py,sha256=IXbWlVtFGTIdvxaafs8Qy8zeD3KjTDgK0omllFq8Jio,461
 amati/_error_handler.py,sha256=_zs0hWqNf6NlXPk9-2MWyk6t5QGttDxNqatZ5YnCm6U,1245
-amati/_logging.py,sha256=y7D0YwYleXx-8ainr-ydDHe4usykI9Fw_c0b90p7tqQ,1352
+amati/_logging.py,sha256=1q5mPlnZDSgAHl56lB20ZN6kV6OS-ew-8fvPeXF0uKI,1357
 amati/_resolve_forward_references.py,sha256=-9MORpUhgusGJdvnH502p8-dc9Q6zqaB5XkPZvp4o7E,6509
-amati/amati.py,sha256=Lj-cEBNqOHuxGIEegYSlUPH6UpkFUixJrfpTQAal86s,9911
+amati/amati.py,sha256=_oFo_Z9cuS7NdN7WZTynXlTDMzndXuT4ERznGWaNpdw,8155
 amati/exceptions.py,sha256=MUzW7FsE0_4BJC99hStokMItKk7OvNBiqO6Zr6d_8cY,577
 amati/file_handler.py,sha256=59kAsyVHE8mddRrNgyEowgZLEsgLcsZsFq6GtH7ZYBo,8065
 amati/model_validators.py,sha256=py9QWEa68bE_tv9JrfnB2nJz16f4_Z2gLQAhH4O-CCs,14887
@@ -38,8 +38,8 @@ amati/validators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,
 amati/validators/generic.py,sha256=NM6ZkuGdM8SDvSUBbMcVz2KIYBWFH2lYTFMVpS1I5QM,5270
 amati/validators/oas304.py,sha256=suDonNEMIzOmX_JfJFT1kYTT0dFFcSHsk8qOpf_x80A,31967
 amati/validators/oas311.py,sha256=ey_j-6YR0rkYd6arVkeK1fDLsGBBoyWjjYBUy7Wj2xM,17325
-amati-0.2.29.dist-info/METADATA,sha256=NdyMzfa9yYWIWEnTk6-2jzQ1pK6D_GPhKdhXKLasz0s,7444
-amati-0.2.29.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-amati-0.2.29.dist-info/entry_points.txt,sha256=sacBb6g0f0ZJtNjNYx93_Xe4y5xzawvklCFVXup9ru0,37
-amati-0.2.29.dist-info/licenses/LICENSE,sha256=WAA01ZXeNs1bwpNWKR6aVucjtYjYm_iQIUYkCAENjqM,1070
-amati-0.2.29.dist-info/RECORD,,
+amati-0.3.1.dist-info/METADATA,sha256=B5EM86jqsymAgnVDUMT-bPPrt6IKGeQbk75iQA1wxbI,6918
+amati-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+amati-0.3.1.dist-info/entry_points.txt,sha256=sacBb6g0f0ZJtNjNYx93_Xe4y5xzawvklCFVXup9ru0,37
+amati-0.3.1.dist-info/licenses/LICENSE,sha256=WAA01ZXeNs1bwpNWKR6aVucjtYjYm_iQIUYkCAENjqM,1070
+amati-0.3.1.dist-info/RECORD,,