chore: improved type and test coverage

Author: manchenkoff

.github/workflows/build.yml

@@ -4,10 +4,10 @@ on:
   pull_request:
     branches: [master]
 jobs:
-  build:
+  lint:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout Git
+      - name: Checkout
         uses: actions/checkout@v6
       - name: Install UV
         uses: astral-sh/setup-uv@v6
@@ -16,11 +16,27 @@ jobs:
           enable-cache: true
       - name: Install dependencies
         run: uv sync --locked --dev
-      - name: Run linters
-        run: |
-          uv run ruff check .
-          uv run mypy .
-          uv run ty check .
+      - name: Run ruff
+        run: uv run ruff check .
+      - name: Run mypy
+        run: uv run mypy .
+      - name: Run ty
+        run: uv run ty check .
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked --dev
       - name: Run tests
         run: uv run pytest
-

pyproject.toml

@@ -25,7 +25,6 @@ classifiers = [
 dependencies = [
     "openapi-spec-validator>=0.8.5",
     "prance>=25.4.8.0",
-    "ty>=0.0.37",
 ]
 
 [project.urls]
@@ -56,6 +55,10 @@ mypy_path = ["src"]
 [[tool.mypy.overrides]]
 module = "tests.*"
 
+[[tool.mypy.overrides]]
+module = "prance"
+ignore_missing_imports = true
+
 [tool.ruff.lint]
 extend-select = [
   "D",      # pydocstyle
@@ -65,6 +68,7 @@ extend-select = [
   "I",      # isort
   "ARG",    # unused arguments
   "RUF100", # unused noqa
+  "TID252", # ban relative imports
 ]
 
 [tool.ruff.lint.pydocstyle]

src/openapi_parser/__init__.py

@@ -1,3 +1,5 @@
-from .parser import parse
+"""OpenAPI v3 specification parser."""
+
+from openapi_parser.parser import parse
 
 __all__ = ["parse"]

src/openapi_parser/builders/__init__.py

@@ -0,0 +1 @@
+"""Builders for converting raw OpenAPI dicts into typed specification objects."""

src/openapi_parser/builders/common.py

@@ -1,13 +1,25 @@
-from collections import namedtuple
-from typing import Any, Callable, Dict, Optional
+"""Shared builder utilities and type helpers."""
 
-from ..errors import ParserError
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
 
-PropertyMeta = namedtuple('PropertyMeta', ['cast', 'name'])
+from openapi_parser.errors import ParserError
 
 
-def extract_typed_props(data: dict, attrs_map: Dict[str, PropertyMeta]) -> Dict[str, Any]:
-    """Extract properties from the dictionary with type-casting using passed mapping
+@dataclass
+class PropertyMeta:
+    """Property metadata for type-casting extraction."""
+
+    name: str
+    cast: Callable[..., Any] | None = None
+
+
+def extract_typed_props(
+    data: dict[str, Any],
+    attrs_map: dict[str, PropertyMeta],
+) -> dict[str, Any]:
+    """Extract properties from the dictionary with type-casting using passed mapping.
 
     Args:
         data (dict): Original dictionary to process
@@ -17,13 +29,17 @@ def extract_typed_props(data: dict, attrs_map: Dict[str, PropertyMeta]) -> Dict[
          Dict[str, Any]: Dictionary with type-casted values
     """
 
-    def cast_value(name: str, value: Any, type_cast_func: Optional[Callable]) -> Any:
+    def cast_value(
+        name: str,
+        value: Any,
+        type_cast_func: Callable[..., Any] | None,
+    ) -> Any:
         try:
-            return type_cast_func(value) \
-                if type_cast_func is not None \
-                else value
+            return type_cast_func(value) if type_cast_func is not None else value
         except ValueError:
-            raise ParserError(f"Invalid value for '{name}' property, got '{value}'")
+            raise ParserError(
+                f"Invalid value for '{name}' property, got '{value}'"
+            ) from None
 
     custom_attrs = {
         attr_name: cast_value(attr_info.name, data[attr_info.name], attr_info.cast)
@@ -34,8 +50,8 @@ def cast_value(name: str, value: Any, type_cast_func: Optional[Callable]) -> Any
     return custom_attrs
 
 
-def merge_schema(original: dict, other: dict) -> dict:
-    """Merge two schema dictionaries into single dict
+def merge_schema(original: dict[str, Any], other: dict[str, Any]) -> dict[str, Any]:
+    """Merge two schema dictionaries into single dict.
 
     Args:
         original (dict): Source schema dictionary
@@ -49,30 +65,35 @@ def merge_schema(original: dict, other: dict) -> dict:
     for key, value in other.items():
         if key not in source:
             source[key] = value
-        else:
-            if isinstance(value, list):
+        elif isinstance(value, list):
+            if isinstance(source[key], list):
                 source[key].extend(value)
-            elif isinstance(value, dict):
+            else:
+                source[key] = value
+        elif isinstance(value, dict):
+            if isinstance(source[key], dict):
                 source[key] = merge_schema(source[key], value)
             else:
                 source[key] = value
+        else:
+            source[key] = value
 
     return source
 
 
-def extract_extension_attributes(schema: dict) -> dict:
-    """Extract custom 'x-*' attributes from schema dictionary
+def extract_extension_attributes(schema: dict[str, Any]) -> dict[str, Any]:
+    """Extract custom 'x-*' attributes from schema dictionary.
 
     Args:
         schema (dict): Schema dictionary
 
     Returns:
         dict: Dictionary with parsed attributes w/o 'x-' prefix
     """
-    extension_key_format = 'x-'
+    extension_key_format = "x-"
 
-    extensions_dict: dict = {
-        key.replace(extension_key_format, '').replace('-', '_'): value
+    extensions_dict: dict[str, Any] = {
+        key.replace(extension_key_format, "").replace("-", "_"): value
         for key, value in schema.items()
         if key.startswith(extension_key_format)
     }

src/openapi_parser/builders/content.py

@@ -1,39 +1,62 @@
+"""Content builder for OpenAPI request/response bodies."""
+
 import logging
-from typing import Type, Union, Any
+from typing import Any
 
-from .schema import SchemaFactory
-from ..enumeration import ContentType
-from ..loose_types import LooseContentType
-from ..specification import Content
+from openapi_parser.builders.schema import SchemaFactory
+from openapi_parser.enumeration import ContentType
+from openapi_parser.loose_types import LooseContentType
+from openapi_parser.specification import Content
 
 logger = logging.getLogger(__name__)
 
-ContentTypeType = Union[Type[ContentType], Type[LooseContentType]]
+ContentTypeType = type[ContentType] | type[LooseContentType]
 
 
 class ContentBuilder:
-    schema_factory: SchemaFactory
-    strict_enum: bool
+    """Builds content objects for request/response bodies."""
+
+    _schema_factory: SchemaFactory
+    _strict_enum: bool
 
     def __init__(self, schema_factory: SchemaFactory, strict_enum: bool = True) -> None:
-        self.schema_factory = schema_factory
-        self.strict_enum = strict_enum
+        """Initialize content builder.
+
+        Args:
+            schema_factory: Factory for creating schema objects
+            strict_enum: Whether to validate enums strictly
+        """
+        self._schema_factory = schema_factory
+        self._strict_enum = strict_enum
 
-    def build_list(self, data: dict) -> list[Content]:
+    def build_list(self, data: dict[str, Any]) -> list[Content]:
+        """Build a list of content objects from a dict of media types."""
         return [
-            self._create_content(content_type, content_value.get('schema', {}),
-                                 content_value.get('example', None),
-                                 content_value.get('examples', {}))
-            for content_type, content_value
-            in data.items()
+            self._create_content(
+                content_type,
+                content_value.get("schema", {}),
+                content_value.get("example", None),
+                content_value.get("examples", {}),
+            )
+            for content_type, content_value in data.items()
         ]
 
-    def _create_content(self, content_type: str, schema: dict, example: Any, examples: dict) -> Content:
+    def _create_content(
+        self,
+        content_type: str,
+        schema: dict[str, Any],
+        example: Any,
+        examples: dict[str, Any],
+    ) -> Content:
         logger.debug(f"Content building [type={content_type}]")
-        ContentTypeCls: ContentTypeType = ContentType if self.strict_enum else LooseContentType
+
+        ContentTypeCls: ContentTypeType = (
+            ContentType if self._strict_enum else LooseContentType
+        )
+
         return Content(
             type=ContentTypeCls(content_type),
-            schema=self.schema_factory.create(schema),
+            schema=self._schema_factory.create(schema),
             example=example,
-            examples=examples
+            examples=examples,
         )

src/openapi_parser/builders/external_doc.py

@@ -1,23 +1,37 @@
+"""External documentation builder."""
+
 import logging
+from typing import Any
 
-from .common import extract_extension_attributes
-from ..specification import ExternalDoc
+from openapi_parser.builders.common import extract_extension_attributes
+from openapi_parser.errors import ParserError
+from openapi_parser.specification import ExternalDoc
 
 logger = logging.getLogger(__name__)
 
 
 class ExternalDocBuilder:
+    """Builds external documentation objects."""
+
     @staticmethod
-    def build(data: dict) -> ExternalDoc:
-        logger.debug(f"External doc parsing: {data['url']}")
+    def build(data: dict[str, Any]) -> ExternalDoc:
+        """Build an ExternalDoc from a raw dict."""
+        url = data.get("url")
+
+        if url is None:
+            raise ParserError(
+                "External documentation is missing required 'url' property"
+            )
+
+        logger.debug(f"External doc parsing: {url}")
 
         attrs = {
-            "url": data['url'],
-            "description": data.get('description'),
+            "url": url,
+            "description": data.get("description"),
             "extensions": extract_extension_attributes(data),
         }
 
-        if attrs['extensions']:
+        if attrs["extensions"]:
             logger.debug(f"Extracted custom properties [{attrs['extensions'].keys()}]")
 
         return ExternalDoc(**attrs)

src/openapi_parser/builders/header.py

@@ -1,41 +1,55 @@
+"""Header builder for response headers."""
+
 import logging
+from typing import Any
 
-from .common import extract_typed_props, PropertyMeta, extract_extension_attributes
-from .schema import SchemaFactory
-from ..specification import Header
+from openapi_parser.builders.common import (
+    PropertyMeta,
+    extract_extension_attributes,
+    extract_typed_props,
+)
+from openapi_parser.builders.schema import SchemaFactory
+from openapi_parser.specification import Header
 
 logger = logging.getLogger(__name__)
 
 
 class HeaderBuilder:
-    schema_factory: SchemaFactory
+    """Builds header objects from raw specification data."""
+
+    _schema_factory: SchemaFactory
 
     def __init__(self, schema_factory: SchemaFactory) -> None:
-        self.schema_factory = schema_factory
+        """Initialize header builder.
+
+        Args:
+            schema_factory: Factory for creating schema objects
+        """
+        self._schema_factory = schema_factory
 
-    def build_list(self, data: dict) -> list[Header]:
+    def build_list(self, data: dict[str, Any]) -> list[Header]:
+        """Build a list of headers from a dict of header definitions."""
         return [
             self._build(header_name, header_value)
-            for header_name, header_value
-            in data.items()
+            for header_name, header_value in data.items()
         ]
 
-    def _build(self, name: str, data: dict) -> Header:
+    def _build(self, name: str, data: dict[str, Any]) -> Header:
         logger.debug(f"Header parsing: {name}")
 
         attrs_map = {
-            "schema": PropertyMeta(name="schema", cast=self.schema_factory.create),
+            "schema": PropertyMeta(name="schema", cast=self._schema_factory.create),
             "description": PropertyMeta(name="description", cast=str),
-            "deprecated": PropertyMeta(name="deprecated", cast=None),
-            "required": PropertyMeta(name="required", cast=None),
+            "deprecated": PropertyMeta(name="deprecated", cast=bool),
+            "required": PropertyMeta(name="required", cast=bool),
         }
 
         attrs = extract_typed_props(data, attrs_map)
 
-        attrs['name'] = name
+        attrs["name"] = name
         attrs["extensions"] = extract_extension_attributes(data)
 
-        if attrs['extensions']:
+        if attrs["extensions"]:
             logger.debug(f"Extracted custom properties [{attrs['extensions'].keys()}]")
 
         return Header(**attrs)