amati 0.1.0__py3-none-any.whl

amati/fields/uri.py

@@ -0,0 +1,342 @@
+"""
+Validates a URI according to the RFC3986 ABNF grammar
+"""
+
+import json
+import pathlib
+from enum import Enum
+from typing import Optional, Self
+
+import idna
+from abnf import Node, ParseError, Rule
+from abnf.grammars import rfc3986, rfc3987
+
+from amati import AmatiValueError, Reference
+from amati.fields import Str as _Str
+from amati.grammars import rfc6901
+
+DATA_DIRECTORY = pathlib.Path(__file__).parent.parent.resolve() / "data"
+
+with open(DATA_DIRECTORY / "schemes.json", "r", encoding="utf-8") as f:
+    SCHEMES = json.loads(f.read())
+
+
+class Scheme(_Str):
+    """Represents a URI scheme with validation and status tracking.
+
+    This class validates URI schemes according to RFC 3986 standards and
+    provides information about their registration status with IANA. It
+    inherits from _Str to provide string-like behavior while adding
+    scheme-specific functionality.
+
+    Attributes:
+        status: The IANA registration status of the scheme. Common values
+            include "Permanent", "Provisional", "Historical", or None for
+            unregistered schemes.
+
+    Example:
+        >>> Scheme("https").status
+        'Permanent'
+    """
+
+    status: Optional[str] = None
+
+    def __init__(self, value: str) -> None:
+        """Initialize a new Scheme instance with validation.
+
+        Args:
+            value: The scheme string
+
+        Raises:
+            AmatiValueError: If the provided value does not conform to RFC 3986
+                scheme syntax rules.
+        """
+
+        super().__init__()
+
+        # Validate the scheme against RFC 3986 syntax rules
+        # This will raise ParseError if the scheme is invalid
+        try:
+            rfc3986.Rule("scheme").parse_all(value)
+        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",
+                ),
+            ) from e
+
+        # Look up the scheme in the IANA registry to get status info
+        # Returns None if the scheme is not in the registry
+        self.status = SCHEMES.get(value, None)
+
+
+class URIType(str, Enum):
+
+    ABSOLUTE = "absolute"
+    RELATIVE = "relative"
+    NON_RELATIVE = "non-relative"
+    JSON_POINTER = "JSON pointer"
+
+
+class URI(_Str):
+    """
+    A class representing a Uniform Resource Identifier (URI) as defined in
+    RFC 3986/3987.
+
+    This class parses and validates URI strings, supporting standard URIs, IRIs
+    (Internationalized Resource Identifiers), and JSON pointers. It provides attributes
+    for accessing URI components and determining the URI type and validity.
+
+    The class attempts to parse URIs using multiple RFC specifications in order of
+    preference, falling back to less restrictive parsing when necessary.
+
+    Attributes:
+        scheme: The URI scheme component (e.g., "http", "https").
+        authority: The authority component.
+        path: The path component
+        query: The query string component
+        fragment: The fragment identifier
+        is_iri: Whether this is an Internationalized Resource Identifier.
+
+    Example:
+        >>> uri = URI("https://example.com/path?query#fragment")
+        >>> uri.scheme
+        'https'
+        >>> uri.authority
+        'example.com'
+        >>> uri.type
+        <URIType.ABSOLUTE: 'absolute'>
+    """
+
+    scheme: Optional[Scheme] = None
+    authority: Optional[str] = None
+    host: Optional[str] = None
+    path: Optional[str] = None
+    query: Optional[str] = None
+    fragment: Optional[str] = None
+    # RFC 3987 Internationalized Resource Identifier (IRI) flag
+    is_iri: bool = False
+
+    _attribute_map: dict[str, str] = {
+        "authority": "authority",
+        "iauthority": "authority",
+        "host": "host",
+        "ihost": "host",
+        "path-abempty": "path",
+        "path-absolute": "path",
+        "path-noscheme": "path",
+        "path-rootless": "path",
+        "path-empty": "path",
+        "ipath-abempty": "path",
+        "ipath-absolute": "path",
+        "ipath-noscheme": "path",
+        "ipath-rootless": "path",
+        "ipath-empty": "path",
+        "query": "query",
+        "iquery": "query",
+        "fragment": "fragment",
+        "ifragment": "fragment",
+    }
+
+    @property
+    def type(self) -> URIType:
+        """
+        Determine the type of the URI based on its components.
+
+        This property analyzes the URI components to classify the URI according to the
+        URIType enumeration. The classification follows a hierarchical approach:
+        absolute URIs take precedence over non-relative, which take precedence over
+        relative URIs.
+
+        Returns:
+            URIType: The classified type of the URI (ABSOLUTE, NON_RELATIVE, RELATIVE,
+                     or JSON_POINTER).
+
+        Raises:
+            TypeError: If the URI has no scheme, authority, or path components.
+        """
+
+        if self.scheme:
+            return URIType.ABSOLUTE
+        if self.authority:
+            return URIType.NON_RELATIVE
+        if self.path:
+            if str(self).startswith("#"):
+                return URIType.JSON_POINTER
+            return URIType.RELATIVE
+
+        # Should theoretically never be reached as if a URI does not have a scheme
+        # authority or path an AmatiValueError should be raised. However, without
+        # an additional return there is a code path in type() that doesn't return a
+        # value. It's better to deal with the potential error case than ignore the
+        # lack of a return value.
+        raise TypeError(f"{str(self)} does not have a URI type.")  # pragma: no cover
+
+    def __init__(self, value: str):
+        """
+        Initialize a URI object by parsing a URI string.
+
+        Parses the input string according to RFC 3986/3987 grammar rules for URIs/IRIs.
+        Handles special cases like JSON pointers (RFC 6901) and performs validation.
+        Attempts multiple parsing strategies in order of preference.
+
+        Args:
+            value: A string representing a URI.
+
+        Raises:
+            AmatiValueError: If the input string is None, not a valid URI according to
+                any supported RFC specification, is a JSON pointer with invalid syntax,
+                or contains only a fragment without other components.
+        """
+
+        super().__init__()
+
+        if value is None:  # type: ignore
+            raise AmatiValueError("None is not a valid URI; declare as Optional")
+
+        candidate = value
+
+        # Handle JSON pointers as per OpenAPI Specification (OAS) standard.
+        # OAS uses fragment identifiers to indicate JSON pointers per RFC 6901,
+        # e.g., "$ref": "#/components/schemas/pet".
+        # The hash symbol does not indicate a URI fragment in this context.
+
+        if value.startswith("#"):
+            candidate = value[1:]
+            try:
+                rfc6901.Rule("json-pointer").parse_all(candidate)
+            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",
+                    ),
+                ) from e
+
+        # Attempt parsing with multiple RFC specifications in order of preference.
+        # Start with most restrictive (RFC 3986 URI) and fall back to more permissive
+        # specifications as needed.
+        rules_to_attempt: tuple[Rule, ...] = (
+            rfc3986.Rule("URI"),
+            rfc3987.Rule("IRI"),
+            rfc3986.Rule("hier-part"),
+            rfc3987.Rule("ihier-part"),
+            rfc3986.Rule("relative-ref"),
+            rfc3987.Rule("irelative-ref"),
+        )
+
+        for rule in rules_to_attempt:
+            try:
+                result = rule.parse_all(candidate)
+            except ParseError:
+                # If the rule fails, continue to the next rule
+                continue
+
+            self._add_attributes(result)
+
+            # Mark as IRI if parsed using RFC 3987 rules
+            if rule.__module__ == rfc3987.__name__:
+                self.is_iri = True
+            elif self.host:
+                # If the host is IDNA encoded then the URI is an IRI.
+                # IDNA encoded URIs will successfully parse with RFC 3986
+                self.is_iri = idna.decode(self.host, uts46=True) != self.host.lower()
+
+            # Successfully parsed - stop attempting other rules
+            break
+
+        # A URI is invalid if it contains only a fragment without scheme, authority,
+        # or path.
+        if not self.scheme and not self.authority and not self.path:
+            raise AmatiValueError(
+                f"{value} does not contain a scheme, authority or path"
+            )
+
+    def _add_attributes(self: Self, node: Node):
+        """
+        Recursively extract and set attributes from the parsed ABNF grammar tree.
+
+        This method traverses the parsed grammar tree and assigns values to the
+        appropriate class attributes based on the node names and types encountered.
+        Special handling is provided for scheme nodes (converted to Scheme objects).
+
+        Args:
+            node: The current node from the parsed ABNF grammar tree.
+        """
+
+        for child in node.children:
+
+            # If the node name is in the URI annotations, set the attribute
+            if child.name == "scheme":
+                self.__dict__["scheme"] = Scheme(child.value)
+            elif child.name in self._attribute_map:
+                self.__dict__[self._attribute_map[child.name]] = child.value
+
+            # If the child is a node with children, recursively add attributes
+            # This is necessary for nodes that have nested structures, such as
+            # the hier-part that may contain subcomponents.
+            if child.children:
+                self._add_attributes(child)
+
+
+class URIWithVariables(URI):
+    """
+    Extends URI to cope with URIs with variable components, e.g.
+    https://{username}.example.com/api/v1/{resource}
+
+    Expected to be used where tooling is required to use string interpolation to
+    generate a valid URI. Will change `{username}` to `username` for validation,
+    but return the original string when called.
+
+    Attributes:
+        scheme: The URI scheme component (e.g., "http", "https").
+        authority: The authority component.
+        path: The path component
+        query: The query string component
+        fragment: The fragment identifier
+        is_iri: Whether this is an Internationalized Resource Identifier.
+        tld_registered: Whether the top-level domain is registered with IANA.
+
+    Inherits:
+        URI: Represents a Uniform Resource Identifier (URI) as defined in RFC 3986/3987.
+    """
+
+    def __init__(self, value: str):
+        """
+        Validate that the URI is a valid URI with variables.
+        e.g. of the form:
+
+        https://{username}.example.com/api/v1/{resource}
+
+        Args:
+            value: The URI to validate
+
+        Raises:
+            ValueError: If there are unbalanced or embedded braces in the URI
+            AmatiValueError: If the value is None
+        """
+
+        if value is None:  # type: ignore
+            raise AmatiValueError("None is not a valid URI; declare as Optional")
+
+        # `string.format()` takes a dict of the key, value pairs to
+        # replace to replace the keys inside braces. As we don't have the keys a dict
+        # that returns the keys that `string.format()` is expecting will have the
+        # effect of replacing '{a}b{c} with 'abc'.
+        class MissingKeyDict(dict[str, str]):
+            def __missing__(self, key: str) -> str:
+                return key
+
+        # Unbalanced or embedded braces, e.g. /example/{id{a}}/ or /example/{id
+        # will cause a ValueError in .format_map().
+        try:
+            candidate = value.format_map(MissingKeyDict())
+        except ValueError as e:
+            raise ValueError(f"Unbalanced or embedded braces in {value}") from e
+
+        super().__init__(candidate)

amati/file_handler.py

@@ -0,0 +1,155 @@
+"""
+File Loader Module with Gzip Support
+
+A file loading system that provides automatic format detection and gzip decompression
+for JSON and YAML files. The module uses the Strategy pattern to allow easy extension
+for additional file formats while maintaining type safety and comprehensive error
+handling.
+
+Features:
+    - Automatic gzip detection using magic byte inspection
+    - Safe loading of JSON and YAML files using json.loads() and yaml.safe_load()
+    - Extensible architecture for adding new file format support
+    - Comprehensive type hints for Python 3.13+
+    - Detailed error handling with descriptive messages
+    - Support for both regular and compressed files
+
+Supported File Types:
+    - JSON: .json, .js (optionally gzip compressed)
+    - YAML: .yaml, .yml (optionally gzip compressed)
+"""
+
+import gzip
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import yaml
+
+type JSONPrimitive = str | int | float | bool | None
+type JSONArray = list["JSONValue"]
+type JSONObject = dict[str, "JSONValue"]
+type JSONValue = JSONPrimitive | JSONArray | JSONObject
+
+
+class FileLoader(ABC):
+    """Abstract base class for file loaders."""
+
+    @abstractmethod
+    def can_handle(self, file_path: Path) -> bool:
+        """Check if this loader can handle the given file."""
+        pass
+
+    @abstractmethod
+    def load(self, content: str) -> JSONObject:
+        """Load and parse the file content."""
+        pass
+
+
+class JSONLoader(FileLoader):
+    """Loader for JSON files."""
+
+    def can_handle(self, file_path: Path) -> bool:
+        return file_path.suffix.lower() in {".json", ".js"}
+
+    def load(self, content: str) -> JSONObject:
+        return json.loads(content)
+
+
+class YAMLLoader(FileLoader):
+    """Loader for YAML files."""
+
+    def can_handle(self, file_path: Path) -> bool:
+        return file_path.suffix.lower() in {".yaml", ".yml"}
+
+    def load(self, content: str) -> JSONObject:
+        return yaml.safe_load(content)
+
+
+class FileProcessor:
+    """Main processor for handling gzipped and regular files."""
+
+    def __init__(self) -> None:
+        self.loaders: list[FileLoader] = [JSONLoader(), YAMLLoader()]
+
+    def _is_gzip_file(self, file_path: Path) -> bool:
+        """Check if file is gzipped by reading magic bytes."""
+        try:
+            with open(file_path, "rb") as f:
+                magic = f.read(2)
+                return magic == b"\x1f\x8b"
+        except (IOError, OSError):
+            return False
+
+    def _get_decompressed_path(self, file_path: Path) -> Path:
+        """Get the path without .gz extension for determining file type."""
+        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."""
+        if self._is_gzip_file(file_path):
+            with gzip.open(file_path, "rt", encoding="utf-8") as f:
+                return f.read()
+        else:
+            with open(file_path, "r", encoding="utf-8") as f:
+                return f.read()
+
+    def _get_appropriate_loader(self, file_path: Path) -> FileLoader:
+        """Get the appropriate loader for the file type."""
+        # Use the decompressed path to determine file type
+        target_path = self._get_decompressed_path(file_path)
+
+        for loader in self.loaders:
+            if loader.can_handle(target_path):
+                return loader
+
+        raise ValueError(f"No suitable loader found for file: {file_path}")
+
+    def load_file(self, file_path: str | Path) -> JSONObject:
+        """
+        Load a file, handling gzip decompression and format detection.
+
+        Args:
+            file_path: Path to the file to load
+
+        Returns:
+            Parsed content as dict, list, or other appropriate type
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            ValueError: If no suitable loader is found
+            json.JSONDecodeError: If JSON parsing fails
+            yaml.YAMLError: If YAML parsing fails
+            OSError: If file reading fails
+        """
+        path = Path(file_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        try:
+            content = self._read_file_content(path)
+            loader = self._get_appropriate_loader(path)
+            return loader.load(content)
+        except (json.JSONDecodeError, yaml.YAMLError) as e:
+            raise TypeError(f"Failed to parse {path}: {e}") from e
+        except (IOError, OSError) as e:
+            raise OSError(f"Failed to read file {path}: {e}") from e
+
+
+def load_file(file_path: str | Path) -> JSONObject:
+    """
+    Convenience function to load a file with automatic format detection and gzip
+    support.
+
+    Args:
+        file_path: Path to the file to load (.json, .yaml, .yml, optionally .gz
+        compressed)
+
+    Returns:
+        Parsed content as dict, list, or other appropriate type
+    """
+    processor = FileProcessor()
+    return processor.load_file(file_path)

amati/grammars/oas.py

@@ -0,0 +1,45 @@
+"""
+Collected rules from the OpenAPI Specification Runtime Expression
+grammar - Section 4.8.20.4
+
+https://spec.openapis.org/oas/latest.html#runtime-expressions
+
+"""
+
+from typing import ClassVar
+
+from abnf.grammars import rfc7230
+from abnf.grammars.misc import load_grammar_rules
+from abnf.parser import Rule as _Rule
+
+from amati.grammars import rfc6901, rfc7159
+
+
+@load_grammar_rules(
+    [
+        ("json-pointer", rfc6901.Rule("json-pointer")),
+        ("char", rfc7159.Rule("char")),
+        ("token", rfc7230.Rule("token")),
+    ]
+)
+class Rule(_Rule):
+    """Parser rules for grammar from OpenAPI Specification"""
+
+    grammar: ClassVar[list[str] | str] = [
+        'expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source',  # pylint: disable=line-too-long
+        "source     = header-reference / query-reference / path-reference / body-reference",  # pylint: disable=line-too-long
+        'header-reference = "header." token',
+        'query-reference  = "query." name',
+        'path-reference   = "path." name',
+        'body-reference   = "body" ["#" json-pointer ]',
+        # json-pointer = *( "/" reference-token )
+        # reference-token = *( unescaped / escaped )
+        # unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
+        #               ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+        # escaped         = "~" ( "0" / "1" )
+        #               ; representing '~' and '/', respectively
+        "name = *( CHAR )",
+        # token = 1*tchar,
+        # tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "."
+        #     / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+    ]

amati/grammars/rfc6901.py

@@ -0,0 +1,26 @@
+"""
+Collected rules from RFC 6901, Section 3.
+https://www.rfc-editor.org/rfc/rfc6901#section-3
+
+"""
+
+from typing import ClassVar
+
+from abnf.grammars.misc import load_grammar_rulelist
+from abnf.parser import Rule as _Rule
+
+
+@load_grammar_rulelist()
+class Rule(_Rule):
+    """Parser rules for grammar from RFC 6901"""
+
+    grammar: ClassVar[
+        list[str] | str
+    ] = r"""
+json-pointer    = *( "/" reference-token )
+reference-token = *( unescaped / escaped )
+unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
+    ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+escaped         = "~" ( "0" / "1" )
+; representing '~' and '/', respectively
+"""

amati/grammars/rfc7159.py

@@ -0,0 +1,65 @@
+"""
+Collected rules from RFC 7159, Sections 2 to 7.
+https://www.rfc-editor.org/rfc/rfc7159#section-2
+
+"""
+
+from typing import ClassVar
+
+from abnf.grammars.misc import load_grammar_rulelist
+from abnf.parser import Rule as _Rule
+
+
+@load_grammar_rulelist()
+class Rule(_Rule):
+    """Parser rules for grammar from RFC 7159"""
+
+    grammar: ClassVar[
+        list[str] | str
+    ] = r"""
+JSON-text = ws value ws
+begin-array     = ws %x5B ws  ; [ left square bracket
+begin-object    = ws %x7B ws  ; { left curly bracket
+end-array       = ws %x5D ws  ; ] right square bracket
+end-object      = ws %x7D ws  ; } right curly bracket
+name-separator  = ws %x3A ws  ; : colon
+value-separator = ws %x2C ws  ; , comma
+ws = *(
+    %x20 /              ; Space
+    %x09 /              ; Horizontal tab
+    %x0A /              ; Line feed or New line
+    %x0D )              ; Carriage return
+value = false / null / true / object / array / number / string
+false = %x66.61.6c.73.65   ; false
+null  = %x6e.75.6c.6c      ; null
+true  = %x74.72.75.65      ; true
+object = begin-object [ member *( value-separator member ) ]
+    end-object
+member = string name-separator value
+array = begin-array [ value *( value-separator value ) ] end-array
+number = [ minus ] int [ frac ] [ exp ]
+decimal-point = %x2E       ; .
+digit1-9 = %x31-39         ; 1-9
+e = %x65 / %x45            ; e E
+exp = e [ minus / plus ] 1*DIGIT
+frac = decimal-point 1*DIGIT
+int = zero / ( digit1-9 *DIGIT )
+minus = %x2D               ; -
+plus = %x2B                ; +
+zero = %x30                ; 0
+string = quotation-mark *char quotation-mark
+char = unescaped /
+    escape (
+        %x22 /          ; "    quotation mark  U+0022
+        %x5C /          ; \    reverse solidus U+005C
+        %x2F /          ; /    solidus         U+002F
+        %x62 /          ; b    backspace       U+0008
+        %x66 /          ; f    form feed       U+000C
+        %x6E /          ; n    line feed       U+000A
+        %x72 /          ; r    carriage return U+000D
+        %x74 /          ; t    tab             U+0009
+        %x75 4HEXDIG )  ; uXXXX                U+XXXX
+escape = %x5C              ; \
+quotation-mark = %x22      ; "
+unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
+"""

amati/logging.py

@@ -0,0 +1,57 @@
+"""
+Logging utilities for Amati.
+"""
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import ClassVar, Generator, Optional, Type
+
+from amati.references import References
+
+type LogType = Exception | Warning
+
+
+@dataclass
+class Log:
+    message: str
+    type: Type[LogType]
+    reference: Optional[References] = None
+
+
+class LogMixin(object):
+    """
+    A mixin class that provides logging functionality.
+
+    This class maintains a list of Log messages that are added.
+    It is NOT thread-safe. State is maintained at a global level.
+    """
+
+    logs: ClassVar[list[Log]] = []
+
+    @classmethod
+    def log(cls, message: Log) -> None:
+        """Add a new message to the logs list.
+
+        Args:
+            message: A Log object containing the message to be logged.
+
+        Returns:
+            The current list of logs after adding the new message.
+        """
+        cls.logs.append(message)
+
+    @classmethod
+    @contextmanager
+    def context(cls) -> Generator[list[Log], None, None]:
+        """Create a context manager for handling logs.
+
+        Yields:
+            The current list of logs.
+
+        Notes:
+            Automatically clears the logs when exiting the context.
+        """
+        try:
+            yield cls.logs
+        finally:
+            cls.logs.clear()