amati 0.1.0__py3-none-any.whl → 0.2__py3-none-any.whl

amati/__init__.py

@@ -3,7 +3,9 @@ Amati is a specification validator, built to put a specification into
 a single datatype and validate on instantiation.
 """
 
-__version__ = "0.1.0"
+import importlib.metadata
+
+__version__ = importlib.metadata.version("amati")
 
 # Imports are here for convenience, they're not going to be used here
 # pylint: disable=unused-import
@@ -11,4 +13,3 @@ __version__ = "0.1.0"
 
 from amati.amati import dispatch, run
 from amati.exceptions import AmatiValueError
-from amati.references import AmatiReferenceException, Reference, References

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
+
+
+def remove_duplicates(data: list[JSONObject]) -> list[JSONObject]:
+    """
+    Remove duplicates by converting each dict to a JSON string for comparison.
+    """
+    seen: set[str] = set()
+    unique_data: list[JSONObject] = []
+
+    for item in data:
+        # 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)
+
+    return unique_data
+
+
+def handle_errors(errors: list[JSONObject] | None, logs: list[Log]) -> list[JSONObject]:
+    """
+    Makes errors and logs consistent for user consumption.
+    """
+
+    result: list[JSONObject] = []
+
+    if errors:
+        result.extend(errors)
+
+    if logs:
+        result.extend(cast(list[JSONObject], logs))
+
+    result = remove_duplicates(result)
+
+    return result

amati/amati.py

@@ -7,15 +7,16 @@ import json
 import sys
 from pathlib import Path
 
-import jsonpickle
+from jinja2 import Environment, FileSystemLoader
 from pydantic import BaseModel, ValidationError
-from pydantic_core import ErrorDetails
 
 # pylint: disable=wrong-import-position
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
+from amati._error_handler import handle_errors
 from amati._resolve_forward_references import resolve_forward_references
 from amati.file_handler import load_file
+from amati.logging import Log, LogMixin
 
 type JSONPrimitive = str | int | float | bool | None
 type JSONArray = list["JSONValue"]
@@ -23,7 +24,7 @@ type JSONObject = dict[str, "JSONValue"]
 type JSONValue = JSONPrimitive | JSONArray | JSONObject
 
 
-def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[ErrorDetails] | None]:
+def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[JSONObject] | None]:
     """
     Returns the correct model for the passed spec
 
@@ -37,10 +38,10 @@ def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[ErrorDetails] | N
     version: JSONValue = data.get("openapi")
 
     if not isinstance(version, str):
-        raise ValueError("A OpenAPI specification version must be a string.")
+        raise TypeError("A OpenAPI specification version must be a string.")
 
     if not version:
-        raise ValueError("An OpenAPI Specfication must contain a version.")
+        raise TypeError("An OpenAPI Specfication must contain a version.")
 
     version_map: dict[str, str] = {
         "3.1.1": "311",
@@ -59,7 +60,7 @@ def dispatch(data: JSONObject) -> tuple[BaseModel | None, list[ErrorDetails] | N
     try:
         model = module.OpenAPIObject(**data)
     except ValidationError as e:
-        return None, e.errors()
+        return None, json.loads(e.json())
 
     return model, None
 
@@ -86,27 +87,113 @@ def check(original: JSONObject, validated: BaseModel) -> bool:
     return original_ == new_
 
 
-def run(file_path: str, consistency_check: bool = False, store_errors: bool = False):
+def run(
+    file_path: str | Path,
+    consistency_check: bool = False,
+    local: bool = False,
+    html_report: bool = False,
+):
     """
-    Runs the full amati process
+    Runs the full amati process on a specific specification file.
+
+     * Parses the YAML or JSON specification, gunzipping if necessary.
+     * Validates the specification.
+     * Runs a consistency check on the ouput of the validation to verify
+       that the output is identical to the input.
+     * Stores any errors found during validation.
+
+    Args:
+        file_path: The specification to be validated
+        consistency_check: Whether or not to verify the output against the input
     """
 
-    data = load_file(file_path)
+    spec = Path(file_path)
+
+    data = load_file(spec)
+
+    logs: list[Log] = []
+
+    with LogMixin.context():
+        result, errors = dispatch(data)
+        logs.extend(LogMixin.logs)
+
+    if errors or logs:
+
+        handled_errors: list[JSONObject] = handle_errors(errors, logs)
+
+        file_name = Path(Path(file_path).parts[-1])
+        error_file = file_name.with_suffix(file_name.suffix + ".errors")
+        error_path = spec.parent
+
+        if local:
+            error_path = Path(".amati")
 
-    result, errors = dispatch(data)
+            if not error_path.exists():
+                error_path.mkdir()
+
+        with open(
+            error_path / error_file.with_suffix(error_file.suffix + ".json"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(json.dumps(handled_errors))
+
+        if html_report:
+            env = Environment(
+                loader=FileSystemLoader(".")
+            )  # Assumes template is in the same directory
+            template = env.get_template("TEMPLATE.html")
+
+            # Render the template with your data
+            html_output = template.render(errors=handled_errors)
+
+            # Save the output to a file
+            with open(
+                error_path / error_file.with_suffix(error_file.suffix + ".html"),
+                "w",
+                encoding="utf-8",
+            ) as f:
+                f.write(html_output)
 
     if result and consistency_check:
-        if check(data, result):
-            print("Consistency check successful")
-        else:
-            print("Consistency check failed")
+        return check(data, result)
+
+
+def discover(discover_dir: str = ".") -> list[Path]:
+    """
+    Finds OpenAPI Specification files to validate
+
+    Args:
+        discover_dir: The directory to search through.
+    Returns:
+        A list of paths to validate.
+    """
+
+    specs: list[Path] = []
+
+    if Path("openapi.json").exists():
+        specs.append(Path("openapi.json"))
+
+    if Path("openapi.yaml").exists():
+        specs.append(Path("openapi.yaml"))
 
-    if errors and store_errors:
-        if not Path(".amati").exists():
-            Path(".amati").mkdir()
+    if specs:
+        return specs
 
-        with open(".amati/pydantic.json", "w", encoding="utf-8") as f:
-            f.write(jsonpickle.encode(errors, unpicklable=False))  # type: ignore
+    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__":
@@ -115,11 +202,23 @@ if __name__ == "__main__":
 
     parser = argparse.ArgumentParser(
         prog="amati",
-        description="Test whether a OpenAPI specification is valid.",
+        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.
+        """,
     )
 
     parser.add_argument(
-        "-s", "--spec", required=True, help="The specification to be parsed"
+        "-s",
+        "--spec",
+        required=False,
+        help="The specification to be parsed",
     )
 
     parser.add_argument(
@@ -127,17 +226,48 @@ if __name__ == "__main__":
         "--consistency-check",
         required=False,
         action="store_true",
-        help="Runs a consistency check between the input specification and amati",
+        help="Runs a consistency check between the input specification and the"
+        " 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(
+        "-l",
+        "--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.",
     )
 
     parser.add_argument(
-        "-se",
-        "--store-errors",
+        "-hr",
+        "--html-report",
         required=False,
         action="store_true",
-        help="Stores and errors in a file for visibility.",
+        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",
     )
 
     args = parser.parse_args()
 
-    run(args.spec, args.consistency_check, args.store_errors)
+    if args.spec:
+        specifications: list[Path] = [Path(args.spec)]
+    else:
+        specifications = discover(args.discover)
+
+    for specification in specifications:
+        if successful_check := run(
+            specification, args.consistency_check, args.local, args.html_report
+        ):
+            print("Consistency check successful for {specification}")
+        else:
+            print("Consistency check failed for {specification}")

amati/exceptions.py

@@ -4,8 +4,6 @@ Exceptions, declared here to not put in __init__
 
 from typing import Optional
 
-from amati.references import References
-
 
 class AmatiValueError(ValueError):
     """
@@ -21,6 +19,6 @@ class AmatiValueError(ValueError):
         ValueError
     """
 
-    def __init__(self, message: str, reference: Optional[References] = None):
+    def __init__(self, message: str, reference_uri: Optional[str] = None):
         self.message = message
-        self.reference = reference
+        self.reference_uri = reference_uri

amati/fields/email.py

@@ -5,14 +5,10 @@ Validates an email according to the RFC5322 ABNF grammar - §3:
 from abnf import ParseError
 from abnf.grammars import rfc5322
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 
-reference = Reference(
-    title="Internet Message Format",
-    url="https://www.rfc-editor.org/rfc/rfc5322#section-3",
-    section="Syntax",
-)
+reference_uri = "https://www.rfc-editor.org/rfc/rfc5322#section-3"
 
 
 class Email(_Str):
@@ -23,5 +19,5 @@ class Email(_Str):
             rfc5322.Rule("address").parse_all(value)
         except ParseError as e:
             raise AmatiValueError(
-                message=f"{value} is not a valid email address", reference=reference
+                f"{value} is not a valid email address", reference_uri
             ) from e

amati/fields/http_status_codes.py

@@ -11,12 +11,11 @@ import pathlib
 import re
 from typing import Optional, Self
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 
-reference = Reference(
-    title="Hypertext Transfer Protocol (HTTP) Status Code Registry",
-    url="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml",
+reference_uri = (
+    "https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml"
 )
 
 DATA_DIRECTORY = pathlib.Path(__file__).parent.parent.resolve() / "data"
@@ -88,7 +87,7 @@ class HTTPStatusCode(_Str):
             self.is_range = True
         else:
             raise AmatiValueError(
-                f"{value} is not a valid HTTP Status Code", reference=reference
+                f"{value} is not a valid HTTP Status Code", reference_uri
             )
 
         if self.description != "Unassigned":

amati/fields/iso9110.py

@@ -9,12 +9,11 @@ and a class for scheme validation.
 import json
 import pathlib
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 
-reference = Reference(
-    title="Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry (ISO9110)",
-    url="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml",
+reference_uri = (
+    "https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml"
 )
 
 
@@ -57,5 +56,5 @@ class HTTPAuthenticationScheme(_Str):
         if value.lower() not in HTTP_AUTHENTICATION_SCHEMES:
             raise AmatiValueError(
                 f"{value} is not a valid HTTP authentication schema.",
-                reference=reference,
+                reference_uri,
             )

amati/fields/media.py

@@ -9,14 +9,10 @@ from typing import Optional
 from abnf import ParseError
 from abnf.grammars import rfc7231
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 
-reference = Reference(
-    title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content",
-    url="https://datatracker.ietf.org/doc/html/rfc7231#appendix-D",
-    section="Appendix D",
-)
+reference_uri = "https://datatracker.ietf.org/doc/html/rfc7231#appendix-D"
 
 DATA_DIRECTORY = pathlib.Path(__file__).parent.parent.resolve() / "data"
 
@@ -69,7 +65,7 @@ class MediaType(_Str):
 
         except ParseError as e:
             raise AmatiValueError(
-                "Invalid media type or media type range", reference=reference
+                "Invalid media type or media type range", reference_uri
             ) from e
 
         if self.type in MEDIA_TYPES:

amati/fields/oas.py

@@ -6,7 +6,7 @@ from typing import ClassVar
 
 from abnf import ParseError
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 from amati.grammars import oas
 
@@ -31,10 +31,8 @@ class RuntimeExpression(_Str):
     It is validated against the ABNF grammar in the OpenAPI spec.
     """
 
-    _reference: ClassVar[Reference] = Reference(
-        title="OpenAPI Specification v3.1.1",
-        section="Runtime Expressions",
-        url="https://spec.openapis.org/oas/v3.1.1.html#runtime-expressions",
+    _reference_uri: ClassVar[str] = (
+        "https://spec.openapis.org/oas/v3.1.1.html#runtime-expressions"
     )
 
     def __init__(self, value: str):
@@ -50,7 +48,7 @@ class RuntimeExpression(_Str):
         except ParseError as e:
             raise AmatiValueError(
                 f"{value} is not a valid runtime expression",
-                reference=self._reference,
+                self._reference_uri,
             ) from e
 
 
@@ -59,11 +57,7 @@ class OpenAPI(_Str):
     Represents an OpenAPI version string.s
     """
 
-    _reference: ClassVar[Reference] = Reference(
-        title="OpenAPI Initiative Publications",
-        url="https://spec.openapis.org/#openapi-specification",
-        section="OpenAPI Specification ",
-    )
+    _reference_uri: ClassVar[str] = "https://spec.openapis.org/#openapi-specification"
 
     def __init__(self, value: str):
         """
@@ -75,5 +69,5 @@ class OpenAPI(_Str):
         if value not in OPENAPI_VERSIONS:
             raise AmatiValueError(
                 f"{value} is not a valid OpenAPI version",
-                reference=self._reference,
+                self._reference_uri,
             )

amati/fields/spdx_licences.py

@@ -6,14 +6,11 @@ Exchange (SPDX) licence list.
 import json
 import pathlib
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 from amati.fields.uri import URI
 
-reference = Reference(
-    title="SPDX License List",
-    url="https://spdx.org/licenses/",
-)
+reference_uri = "https://spdx.org/licenses/"
 
 
 DATA_DIRECTORY = pathlib.Path(__file__).parent.parent.resolve() / "data"
@@ -55,7 +52,7 @@ class SPDXIdentifier(_Str):
 
         if value not in VALID_LICENCES:
             raise AmatiValueError(
-                f"{value} is not a valid SPDX licence identifier", reference=reference
+                f"{value} is not a valid SPDX licence identifier", reference_uri
             )
 
 
@@ -88,5 +85,5 @@ class SPDXURL(URI):  # pylint: disable=invalid-name
 
         if value not in VALID_URLS:
             raise AmatiValueError(
-                f"{value} is not associated with any identifier.", reference=reference
+                f"{value} is not associated with any identifier.", reference_uri
             )

amati/fields/uri.py

@@ -11,7 +11,7 @@ import idna
 from abnf import Node, ParseError, Rule
 from abnf.grammars import rfc3986, rfc3987
 
-from amati import AmatiValueError, Reference
+from amati import AmatiValueError
 from amati.fields import Str as _Str
 from amati.grammars import rfc6901
 
@@ -61,11 +61,7 @@ class Scheme(_Str):
         except ParseError as e:
             raise AmatiValueError(
                 f"{value} is not a valid URI scheme",
-                reference=Reference(
-                    title="Uniform Resource Identifier (URI): Generic Syntax",
-                    section="3.1 - Scheme",
-                    url="https://www.rfc-editor.org/rfc/rfc3986#section-3.1",
-                ),
+                "https://www.rfc-editor.org/rfc/rfc3986#section-3.1",
             ) from e
 
         # Look up the scheme in the IANA registry to get status info
@@ -211,11 +207,7 @@ class URI(_Str):
             except ParseError as e:
                 raise AmatiValueError(
                     f"{value} is not a valid JSON pointer",
-                    reference=Reference(
-                        title="JavaScript Object Notation (JSON) Pointer",
-                        section="6 - URI Fragment Identifier Representation",
-                        url="https://www.rfc-editor.org/rfc/rfc6901#section-6",
-                    ),
+                    "https://www.rfc-editor.org/rfc/rfc6901#section-6",
                 ) from e
 
         # Attempt parsing with multiple RFC specifications in order of preference.

amati/logging.py

@@ -4,21 +4,21 @@ Logging utilities for Amati.
 
 from contextlib import contextmanager
 from dataclasses import dataclass
-from typing import ClassVar, Generator, Optional, Type
-
-from amati.references import References
+from typing import Any, ClassVar, Generator, NotRequired, TypedDict
 
 type LogType = Exception | Warning
 
 
 @dataclass
-class Log:
-    message: str
-    type: Type[LogType]
-    reference: Optional[References] = None
+class Log(TypedDict):
+    type: str
+    loc: NotRequired[tuple[int | str, ...]]
+    msg: str
+    input: NotRequired[Any]
+    url: NotRequired[str]
 
 
-class LogMixin(object):
+class LogMixin:
     """
     A mixin class that provides logging functionality.