openapi3-parser 1.1.21__tar.gz → 1.2.0__tar.gz

openapi3_parser-1.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.3
+Name: openapi3-parser
+Version: 1.2.0
+Summary: OpenAPI v3 parser
+Keywords: swagger,python,swagger-parser,openapi3-parser,parser,openapi3,swagger-api
+Author: Artem Manchenkov
+Author-email: Artem Manchenkov <artem@manchenkoff.me>
+License: MIT License
+         
+         Copyright (c) 2020 Artem Manchenkov
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: openapi-spec-validator>=0.8.5
+Requires-Dist: prance>=25.4.8.0
+Requires-Python: >=3.10
+Project-URL: homepage, https://github.com/manchenkoff/openapi3-parser
+Project-URL: source, https://github.com/manchenkoff/openapi3-parser
+Description-Content-Type: text/markdown
+
+# OpenAPI Parser
+
+[![PyPI - Version](https://img.shields.io/pypi/v/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/openapi3-parser)](https://clickpy.clickhouse.com/dashboard/openapi3-parser)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - Format](https://img.shields.io/pypi/format/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - License](https://img.shields.io/pypi/l/openapi3-parser)](license.txt)
+
+Parse OpenAPI 3 documents into fully typed Python dataclass objects.
+Navigate your API specification programmatically — servers, paths,
+operations, parameters, schemas, security schemes, and more.
+
+| Version | Status         |
+| ------- | -------------- |
+| 2.0     | Deprecated     |
+| 3.0     | **Supported**  |
+| 3.1     | In development |
+
+## Installation
+
+```bash
+pip install openapi3-parser
+```
+
+## Quick Start
+
+```python
+from openapi_parser import parse
+
+specification = parse("swagger.yml")
+print(specification.info.title)  # e.g. "User example service"
+```
+
+## Use Cases
+
+### Parse from different sources
+
+```python
+# From file path
+spec = parse("specs/openapi.yml")
+
+# From URL
+spec = parse("https://example.com/openapi.json")
+
+# From raw string
+spec = parse(spec_string="""
+openapi: "3.0.0"
+info:
+  title: My API
+  version: "1.0.0"
+paths: {}
+""")
+```
+
+### Navigate servers, paths, and operations
+
+```python
+specification = parse("swagger.yml")
+
+# List all servers
+for server in specification.servers:
+    print(f"{server.description} - {server.url}")
+
+# List all paths and their HTTP methods
+for path in specification.paths:
+    methods = ", ".join(op.method.value for op in path.operations)
+    print(f"{path.url}: [{methods}]")
+
+# Inspect operation details
+for path in specification.paths:
+    for op in path.operations:
+        print(f"[{op.method.value}] {path.url}: {op.summary}")
+        if op.deprecated:
+            print("  (deprecated)")
+        if op.operation_id:
+            print(f"  operationId: {op.operation_id}")
+```
+
+### Enum strictness
+
+By default, content types, string formats, and other enum fields are validated
+against predefined enums. For specs that use custom values, pass
+`strict_enum=False`:
+
+```python
+# Accepts non-standard content types like "application/vnd.api+json"
+spec = parse("swagger.yml", strict_enum=False)
+```
+
+When strict mode is off, unrecognized values are wrapped in a `LooseEnum`
+object instead of raising an error.
+
+### Error Handling
+
+```python
+from openapi_parser.errors import ParserError
+
+try:
+    spec = parse("invalid.yml")
+except ParserError as e:
+    print(f"Parsing failed: {e}")
+```
+
+## Data Model
+
+Parsed documents return a `Specification` object composed of fully typed
+dataclasses:
+
+| Model           | Description |
+| --------------- | ----------- |
+| `Specification` | Root document — version, info, servers, paths, schemas, security |
+| `Info`          | API metadata — title, version, description, contact, license |
+| `Server`        | Server definition — url, description, variables |
+| `Path`          | URL path — operations, parameters |
+| `Operation`     | HTTP method — responses, parameters, request body, security |
+| `Parameter`     | Path/query/header/cookie param — schema, style, required |
+| `Response`      | Status code, description, content, headers |
+| `RequestBody`   | Content, description, required |
+| `Content`       | Media type, schema, example |
+| `Schema`        | Base type — Integer, Number, String, Boolean, Array, Object, Null |
+| `Property`      | Object property — name, schema |
+| `OneOf`/`AnyOf` | Composition schemas with discriminator support |
+| `Security`      | Security scheme — apiKey, http, oauth2, openIdConnect |
+| `OAuthFlow`     | OAuth flow — authorization, token, scopes |
+| `Header`        | Response header — name, schema, description |
+| `Tag`           | Tag with optional external docs |
+| `ExternalDoc`   | External documentation reference |
+| `Discriminator` | Polymorphism discriminator — property name, mapping |
+
+See the [specification module](src/openapi_parser/specification.py) for
+all available fields and types.
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync --dev
+
+# Lint
+uv run ruff check .
+uv run mypy .
+uv run ty check .
+
+# Test
+uv run pytest
+
+# Format
+uv run ruff format .
+```

{openapi3_parser-1.1.21 → openapi3_parser-1.2.0}/license.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Artyom Manchenkov
+Copyright (c) 2020 Artem Manchenkov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

openapi3_parser-1.2.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "openapi3-parser"
+version = "1.2.0"
+description = "OpenAPI v3 parser"
+readme = "readme.md"
+license = { file = "license.txt" }
+authors = [{ name = "Artem Manchenkov", email = "artem@manchenkoff.me" }]
+requires-python = ">=3.10"
+keywords = [
+  "swagger",
+  "python",
+  "swagger-parser",
+  "openapi3-parser",
+  "parser",
+  "openapi3",
+  "swagger-api",
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "openapi-spec-validator>=0.8.5",
+    "prance>=25.4.8.0",
+]
+
+[project.urls]
+homepage = "https://github.com/manchenkoff/openapi3-parser"
+source = "https://github.com/manchenkoff/openapi3-parser"
+
+[dependency-groups]
+dev = ["mypy>=2.1.0", "pytest>=9.0.3", "pytest-cov>=6.1.0", "ruff>=0.15.13", "ty>=0.0.37"]
+
+[build-system]
+requires = ["uv_build>=0.11.12,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "openapi_parser"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+mypy_path = ["src"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+
+[[tool.mypy.overrides]]
+module = "prance"
+ignore_missing_imports = true
+
+[tool.ruff.lint]
+extend-select = [
+  "D",      # pydocstyle
+  "UP",     # pyupgrade
+  "B",      # flake8-bugbear
+  "SIM",    # flake8-simplify
+  "I",      # isort
+  "ARG",    # unused arguments
+  "RUF100", # unused noqa
+  "TID252", # ban relative imports
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "ARG"]
+
+[tool.coverage.run]
+source = ["openapi_parser"]
+omit = ["tests/*"]

openapi3_parser-1.2.0/readme.md

@@ -0,0 +1,149 @@
+# OpenAPI Parser
+
+[![PyPI - Version](https://img.shields.io/pypi/v/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/openapi3-parser)](https://clickpy.clickhouse.com/dashboard/openapi3-parser)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - Format](https://img.shields.io/pypi/format/openapi3-parser)](https://pypi.org/project/openapi3-parser/)
+[![PyPI - License](https://img.shields.io/pypi/l/openapi3-parser)](license.txt)
+
+Parse OpenAPI 3 documents into fully typed Python dataclass objects.
+Navigate your API specification programmatically — servers, paths,
+operations, parameters, schemas, security schemes, and more.
+
+| Version | Status         |
+| ------- | -------------- |
+| 2.0     | Deprecated     |
+| 3.0     | **Supported**  |
+| 3.1     | In development |
+
+## Installation
+
+```bash
+pip install openapi3-parser
+```
+
+## Quick Start
+
+```python
+from openapi_parser import parse
+
+specification = parse("swagger.yml")
+print(specification.info.title)  # e.g. "User example service"
+```
+
+## Use Cases
+
+### Parse from different sources
+
+```python
+# From file path
+spec = parse("specs/openapi.yml")
+
+# From URL
+spec = parse("https://example.com/openapi.json")
+
+# From raw string
+spec = parse(spec_string="""
+openapi: "3.0.0"
+info:
+  title: My API
+  version: "1.0.0"
+paths: {}
+""")
+```
+
+### Navigate servers, paths, and operations
+
+```python
+specification = parse("swagger.yml")
+
+# List all servers
+for server in specification.servers:
+    print(f"{server.description} - {server.url}")
+
+# List all paths and their HTTP methods
+for path in specification.paths:
+    methods = ", ".join(op.method.value for op in path.operations)
+    print(f"{path.url}: [{methods}]")
+
+# Inspect operation details
+for path in specification.paths:
+    for op in path.operations:
+        print(f"[{op.method.value}] {path.url}: {op.summary}")
+        if op.deprecated:
+            print("  (deprecated)")
+        if op.operation_id:
+            print(f"  operationId: {op.operation_id}")
+```
+
+### Enum strictness
+
+By default, content types, string formats, and other enum fields are validated
+against predefined enums. For specs that use custom values, pass
+`strict_enum=False`:
+
+```python
+# Accepts non-standard content types like "application/vnd.api+json"
+spec = parse("swagger.yml", strict_enum=False)
+```
+
+When strict mode is off, unrecognized values are wrapped in a `LooseEnum`
+object instead of raising an error.
+
+### Error Handling
+
+```python
+from openapi_parser.errors import ParserError
+
+try:
+    spec = parse("invalid.yml")
+except ParserError as e:
+    print(f"Parsing failed: {e}")
+```
+
+## Data Model
+
+Parsed documents return a `Specification` object composed of fully typed
+dataclasses:
+
+| Model           | Description |
+| --------------- | ----------- |
+| `Specification` | Root document — version, info, servers, paths, schemas, security |
+| `Info`          | API metadata — title, version, description, contact, license |
+| `Server`        | Server definition — url, description, variables |
+| `Path`          | URL path — operations, parameters |
+| `Operation`     | HTTP method — responses, parameters, request body, security |
+| `Parameter`     | Path/query/header/cookie param — schema, style, required |
+| `Response`      | Status code, description, content, headers |
+| `RequestBody`   | Content, description, required |
+| `Content`       | Media type, schema, example |
+| `Schema`        | Base type — Integer, Number, String, Boolean, Array, Object, Null |
+| `Property`      | Object property — name, schema |
+| `OneOf`/`AnyOf` | Composition schemas with discriminator support |
+| `Security`      | Security scheme — apiKey, http, oauth2, openIdConnect |
+| `OAuthFlow`     | OAuth flow — authorization, token, scopes |
+| `Header`        | Response header — name, schema, description |
+| `Tag`           | Tag with optional external docs |
+| `ExternalDoc`   | External documentation reference |
+| `Discriminator` | Polymorphism discriminator — property name, mapping |
+
+See the [specification module](src/openapi_parser/specification.py) for
+all available fields and types.
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync --dev
+
+# Lint
+uv run ruff check .
+uv run mypy .
+uv run ty check .
+
+# Test
+uv run pytest
+
+# Format
+uv run ruff format .
+```

openapi3_parser-1.2.0/src/openapi_parser/__init__.py

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

openapi3_parser-1.2.0/src/openapi_parser/builders/__init__.py

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

openapi3_parser-1.2.0/src/openapi_parser/builders/common.py

@@ -0,0 +1,101 @@
+"""Shared builder utilities and type helpers."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from openapi_parser.errors import ParserError
+
+
+@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
+        attrs_map (Dict[str, PropertyMeta]): Type-casting mapping
+
+    Returns:
+         Dict[str, Any]: Dictionary with type-casted values
+    """
+
+    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
+        except ValueError:
+            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)
+        for attr_name, attr_info in attrs_map.items()
+        if data.get(attr_info.name) is not None
+    }
+
+    return custom_attrs
+
+
+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
+        other (dict): Schema dictionary to append to the source
+
+    Returns:
+        dict: Dictionary value of new merged schema
+    """
+    source = original.copy()
+
+    for key, value in other.items():
+        if key not in source:
+            source[key] = value
+        elif isinstance(value, list):
+            if isinstance(source[key], list):
+                source[key].extend(value)
+            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[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-"
+
+    extensions_dict: dict[str, Any] = {
+        key.replace(extension_key_format, "").replace("-", "_"): value
+        for key, value in schema.items()
+        if key.startswith(extension_key_format)
+    }
+
+    return extensions_dict

openapi3_parser-1.2.0/src/openapi_parser/builders/content.py

@@ -0,0 +1,74 @@
+"""Content builder for OpenAPI request/response bodies."""
+
+import logging
+from typing import Any
+
+from openapi_parser.builders.encoding import EncodingBuilder
+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 = type[ContentType] | type[LooseContentType]
+
+
+class ContentBuilder:
+    """Builds content objects for request/response bodies."""
+
+    _schema_factory: SchemaFactory
+    _encoding_builder: EncodingBuilder
+    _strict_enum: bool
+
+    def __init__(
+        self,
+        schema_factory: SchemaFactory,
+        encoding_builder: EncodingBuilder,
+        strict_enum: bool = True,
+    ) -> None:
+        """Initialize content builder.
+
+        Args:
+            schema_factory: Factory for creating schema objects
+            encoding_builder: Builder for encoding objects
+            strict_enum: Whether to validate enums strictly
+        """
+        self._schema_factory = schema_factory
+        self._encoding_builder = encoding_builder
+        self._strict_enum = strict_enum
+
+    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,
+            )
+            for content_type, content_value in data.items()
+        ]
+
+    def _create_content(
+        self,
+        content_type: str,
+        content_value: dict[str, Any],
+    ) -> Content:
+        logger.debug(f"Content building [type={content_type}]")
+
+        ContentTypeCls: ContentTypeType = (
+            ContentType if self._strict_enum else LooseContentType
+        )
+
+        encoding = (
+            self._encoding_builder.build_dict(content_value["encoding"])
+            if content_value.get("encoding")
+            else None
+        )
+
+        return Content(
+            type=ContentTypeCls(content_type),
+            schema=self._schema_factory.create(content_value.get("schema", {})),
+            example=content_value.get("example"),
+            examples=content_value.get("examples", {}),
+            encoding=encoding,
+        )

openapi3_parser-1.2.0/src/openapi_parser/builders/encoding.py

@@ -0,0 +1,57 @@
+"""Encoding builder for request body property encodings."""
+
+import logging
+from typing import Any
+
+from openapi_parser.builders.common import (
+    PropertyMeta,
+    extract_extension_attributes,
+    extract_typed_props,
+)
+from openapi_parser.builders.header import HeaderBuilder
+from openapi_parser.specification import Encoding
+
+logger = logging.getLogger(__name__)
+
+
+class EncodingBuilder:
+    """Builds encoding objects from raw specification data."""
+
+    _header_builder: HeaderBuilder
+
+    def __init__(self, header_builder: HeaderBuilder) -> None:
+        """Initialize encoding builder.
+
+        Args:
+            header_builder: Builder for header objects
+        """
+        self._header_builder = header_builder
+
+    def build_dict(self, data: dict[str, dict[str, Any]]) -> dict[str, Encoding]:
+        """Build a dict of encodings from a dict of raw encoding definitions."""
+        return {
+            property_name: self._build(encoding_data)
+            for property_name, encoding_data in data.items()
+        }
+
+    def _build(self, data: dict[str, Any]) -> Encoding:
+        logger.debug("Encoding building")
+
+        attrs_map = {
+            "content_type": PropertyMeta(name="contentType", cast=str),
+            "headers": PropertyMeta(
+                name="headers",
+                cast=self._header_builder.build_list,
+            ),
+            "style": PropertyMeta(name="style", cast=str),
+            "explode": PropertyMeta(name="explode", cast=bool),
+            "allow_reserved": PropertyMeta(name="allowReserved", cast=bool),
+        }
+
+        attrs = extract_typed_props(data, attrs_map)
+        attrs["extensions"] = extract_extension_attributes(data)
+
+        if attrs["extensions"]:
+            logger.debug(f"Extracted custom properties [{attrs['extensions'].keys()}]")
+
+        return Encoding(**attrs)