essentials-openapi 1.2.1__tar.gz → 1.3.0__tar.gz

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2025-11-19
+- Add support for passing custom Jinja2 templates as an argument, by @sindrehan.
+
 ## [1.2.1] - 2025-07-30
 
 - Added support for using the current working directory (CWD) as an option when

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: essentials-openapi
-Version: 1.2.1
+Version: 1.3.0
 Summary: Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.
 Project-URL: Homepage, https://github.com/Neoteroi/essentials-openapi
 Project-URL: Bug Tracker, https://github.com/Neoteroi/essentials-openapi/issues
@@ -11,12 +11,12 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
 Requires-Dist: essentials>=1.1.5
 Requires-Dist: markupsafe>=3.0.0
 Requires-Dist: pyyaml>=6
@@ -102,6 +102,34 @@ oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
 
 _Example of PlantUML diagram generated from path items._
 
+#### Using custom templates
+
+You can override the default templates by providing a custom templates directory:
+
+```bash
+oad gen-docs -s source-openapi.json -d output.md -T ./my-templates/
+```
+
+The custom templates directory should contain template files with the same names as the built-in templates. Any template file found in the custom directory will override the corresponding default template, while non-overridden templates will use the defaults. This follows the same pattern as [MkDocs template customization](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks).
+
+**Important:** The custom templates directory must match the output style being rendered. Each style (MKDOCS, MARKDOWN, PLANTUML_SCHEMAS, PLANTUML_API) has its own template structure. You need to provide templates appropriate for the `--style` parameter you're using.
+
+**Template structure:**
+- `layout.html` - Main layout template
+- `partial/` - Directory containing reusable template components
+
+**Example custom template directory structure:**
+```
+my-templates/
+├── layout.html          # Overrides main layout
+└── partial/
+    ├── info.html       # Overrides info section
+    └── path-items.html # Overrides path items section
+```
+
+All templates use [Jinja2](https://jinja.palletsprojects.com/) syntax and have access to the same filters, functions, and context variables as the built-in templates.
+
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/README.md

@@ -73,6 +73,34 @@ oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
 
 _Example of PlantUML diagram generated from path items._
 
+#### Using custom templates
+
+You can override the default templates by providing a custom templates directory:
+
+```bash
+oad gen-docs -s source-openapi.json -d output.md -T ./my-templates/
+```
+
+The custom templates directory should contain template files with the same names as the built-in templates. Any template file found in the custom directory will override the corresponding default template, while non-overridden templates will use the defaults. This follows the same pattern as [MkDocs template customization](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks).
+
+**Important:** The custom templates directory must match the output style being rendered. Each style (MKDOCS, MARKDOWN, PLANTUML_SCHEMAS, PLANTUML_API) has its own template structure. You need to provide templates appropriate for the `--style` parameter you're using.
+
+**Template structure:**
+- `layout.html` - Main layout template
+- `partial/` - Directory containing reusable template components
+
+**Example custom template directory structure:**
+```
+my-templates/
+├── layout.html          # Overrides main layout
+└── partial/
+    ├── info.html       # Overrides info section
+    └── path-items.html # Overrides path items section
+```
+
+All templates use [Jinja2](https://jinja.palletsprojects.com/) syntax and have access to the same filters, functions, and context variables as the built-in templates.
+
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 VERSION = __version__

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/commands/docs.py

@@ -31,7 +31,20 @@ from openapidocs.mk.jinja import OutputStyle
     default="MKDOCS",
     show_default=True,
 )
-def generate_documents_command(source: str, destination: str, style: Union[int, str]):
+@click.option(
+    "-T",
+    "--templates",
+    help=(
+        "Path to a custom templates directory. "
+        "Templates in this directory will override default templates with matching names. "
+        "Unspecified templates will use defaults."
+    ),
+    required=False,
+    default=None,
+)
+def generate_documents_command(
+    source: str, destination: str, style: Union[int, str], templates: Union[str, None]
+):
     """
     Generates other kinds of documents from source OpenAPI Documentation files.
 
@@ -48,7 +61,7 @@ def generate_documents_command(source: str, destination: str, style: Union[int,
     https://github.com/Neoteroi/essentials-openapi
     """
     try:
-        generate_document(source, destination, style)
+        generate_document(source, destination, style, templates)
     except KeyboardInterrupt:  # pragma: nocover
         logger.info("User interrupted")
         exit(1)

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/common.py

@@ -1,10 +1,10 @@
 import base64
 import copy
 from abc import ABC, abstractmethod
-from dataclasses import asdict, fields, is_dataclass
+from dataclasses import asdict, dataclass, fields, is_dataclass
 from datetime import date, datetime, time
 from enum import Enum
-from typing import Any, List, Tuple
+from typing import Any, Callable, Iterable, cast
 from uuid import UUID
 
 import yaml
@@ -18,10 +18,12 @@ class Format(Enum):
     JSON = "JSON"
 
 
+@dataclass
 class OpenAPIElement:
     """Base class for all OpenAPI Elements"""
 
 
+@dataclass
 class OpenAPIRoot(OpenAPIElement):
     """Base class for a root OpenAPI Documentation"""
 
@@ -67,8 +69,8 @@ def normalize_key(key: Any) -> str:
     return "".join([first.lower(), *map(str.title, others)])
 
 
-def normalize_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
-    data = {}
+def normalize_dict_factory(items: list[tuple[Any, Any]]) -> dict[str, Any]:
+    data: dict[str, Any] = {}
     for key, value in items:
         if value is None:
             continue
@@ -87,8 +89,8 @@ def normalize_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
     return data
 
 
-def regular_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
-    data = {}
+def regular_dict_factory(items: list[tuple[Any, Any]]) -> dict[Any, Any]:
+    data: dict[Any, Any] = {}
     for key, value in items:
         for handler in TYPES_HANDLERS:
             value = handler.normalize(value)
@@ -100,11 +102,11 @@ def regular_dict_factory(items: List[Tuple[Any, Any]]) -> Any:
 # replicates the asdict method from dataclasses module, to support
 # bypassing "asdict" on child properties when they implement a `to_obj`
 # method: some entities require a specific shape when represented
-def _asdict_inner(obj, dict_factory):
+def _asdict_inner(obj: Any, dict_factory: Callable[[Any], Any]) -> Any:
     if hasattr(obj, "to_obj"):
         return obj.to_obj()
     if isinstance(obj, OpenAPIElement):
-        result = []
+        result: list[tuple[str, Any]] = []
         for f in fields(obj):
             value = _asdict_inner(getattr(obj, f.name), dict_factory)
             result.append((f.name, value))
@@ -115,11 +117,13 @@ def _asdict_inner(obj, dict_factory):
     if hasattr(obj, "dict") and callable(obj.dict):
         # For Pydantic 1
         return obj.dict()
-    if is_dataclass(obj):
+    if is_dataclass(obj) and not isinstance(obj, type):
         return asdict(obj, dict_factory=regular_dict_factory)
     elif isinstance(obj, (list, tuple)):
+        obj = cast(Iterable[Any], obj)
         return type(obj)(_asdict_inner(v, dict_factory) for v in obj)
     elif isinstance(obj, dict):
+        obj = cast(dict[Any, Any], obj)
         return type(obj)(
             (_asdict_inner(k, dict_factory), _asdict_inner(v, dict_factory))
             for k, v in obj.items()
@@ -128,7 +132,7 @@ def _asdict_inner(obj, dict_factory):
         return copy.deepcopy(obj)
 
 
-def normalize_dict(obj):
+def normalize_dict(obj: Any) -> Any:
     if hasattr(obj, "dict") and callable(obj.dict):
         return obj.dict()
     if hasattr(obj, "to_obj"):

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/logs.py

@@ -1,5 +1,4 @@
 import logging
-import logging.handlers
 
 from rich.logging import RichHandler
 

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/common.py

@@ -5,6 +5,7 @@ from source OAD files.
 """
 
 from abc import ABC, abstractmethod
+from typing import Any, cast
 
 
 class DocumentsWriter(ABC):
@@ -14,13 +15,13 @@ class DocumentsWriter(ABC):
     """
 
     @abstractmethod
-    def write(self, data, **kwargs) -> str:
+    def write(self, data: object, **kwargs: dict[str, Any]) -> str:
         """
         Writes markdown.
         """
 
 
-def is_reference(data) -> bool:
+def is_reference(data: object) -> bool:
     """
     Returns a value indicating whether the given dictionary represents
     a reference.
@@ -32,7 +33,7 @@ def is_reference(data) -> bool:
     return "$ref" in data
 
 
-def is_object_schema(data) -> bool:
+def is_object_schema(data: object) -> bool:
     """
     Returns a value indicating whether the given schema dictionary represents
     an object schema.
@@ -41,10 +42,11 @@ def is_object_schema(data) -> bool:
     """
     if not isinstance(data, dict):
         return False
+    data = cast(dict[str, object], data)
     return data.get("type") == "object" and isinstance(data.get("properties"), dict)
 
 
-def is_array_schema(data) -> bool:
+def is_array_schema(data: object) -> bool:
     """
     Returns a value indicating whether the given schema dictionary represents
     an array schema.
@@ -53,10 +55,11 @@ def is_array_schema(data) -> bool:
     """
     if not isinstance(data, dict):
         return False
+    data = cast(dict[str, object], data)
     return data.get("type") == "array" and isinstance(data.get("items"), dict)
 
 
-def get_ref_type_name(reference) -> str:
+def get_ref_type_name(reference: dict[str, str] | str) -> str:
     """
     Returns the type name of a reference.
 

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/contents.py

@@ -1,27 +1,29 @@
 """
 This module contains classes to generate representations of content types by mime type.
 """
+
 import os
 from abc import ABC, abstractmethod
 from datetime import datetime
 from json import JSONEncoder
+from typing import Any, Mapping, Sequence
 from urllib.parse import urlencode
 
 from essentials.json import FriendlyEncoder, dumps
 
 
 class OADJSONEncoder(JSONEncoder):
-    def default(self, obj):
+    def default(self, o: object) -> Any:
         try:
-            return JSONEncoder.default(self, obj)
+            return JSONEncoder.default(self, o)
         except TypeError:
-            if isinstance(obj, datetime):
+            if isinstance(o, datetime):
                 datetime_format = os.environ.get("OPENAPI_DATETIME_FORMAT")
                 if datetime_format:
-                    return obj.strftime(datetime_format)
+                    return o.strftime(datetime_format)
                 else:
-                    return obj.isoformat()
-            return FriendlyEncoder.default(self, obj)  # type: ignore
+                    return o.isoformat()
+            return FriendlyEncoder.default(self, o)  # type: ignore
 
 
 class ContentWriter(ABC):
@@ -37,7 +39,7 @@ class ContentWriter(ABC):
         """
 
     @abstractmethod
-    def write(self, value) -> str:
+    def write(self, value: Any) -> str:
         """
         Writes markdown to represent a value in a certain type of content.
         """
@@ -47,7 +49,7 @@ class JSONContentWriter(ContentWriter):
     def handle_content_type(self, content_type: str) -> bool:
         return "json" in content_type.lower()
 
-    def write(self, value) -> str:
+    def write(self, value: object) -> str:
         return dumps(value, indent=4, cls=OADJSONEncoder)
 
 
@@ -56,5 +58,5 @@ class FormContentWriter(ContentWriter):
         # multipart/form-data. Otherwise, use application/x-www-form-urlencoded.
         return "x-www-form-urlencoded" == content_type.lower()
 
-    def write(self, value) -> str:
+    def write(self, value: Mapping[Any, Any] | Sequence[tuple[Any, Any]]) -> str:
         return urlencode(value)

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/generate.py

@@ -1,15 +1,22 @@
-from typing import Union
+from typing import Optional
 
 from openapidocs.mk.v3 import OpenAPIV3DocumentationHandler
 from openapidocs.utils.source import read_from_source
 
 
-def generate_document(source: str, destination: str, style: Union[int, str]):
+def generate_document(
+    source: str,
+    destination: str,
+    style: int | str,
+    templates_path: Optional[str] = None,
+):
     # Note: if support for more kinds of OAD versions will be added, handle a version
     # parameter in this function
 
     data = read_from_source(source)
-    handler = OpenAPIV3DocumentationHandler(data, style=style, source=source)
+    handler = OpenAPIV3DocumentationHandler(
+        data, style=style, source=source, templates_path=templates_path
+    )
 
     html = handler.write()
 

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/jinja.py

@@ -1,10 +1,20 @@
 """
 This module provides a Jinja2 environment.
 """
+
 import os
 from enum import Enum
-
-from jinja2 import Environment, PackageLoader, Template, select_autoescape
+from pathlib import Path
+from typing import Optional
+
+from jinja2 import (
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    Template,
+    select_autoescape,
+)
 
 from . import get_http_status_phrase, highlight_params, read_dict, sort_dict
 from .common import DocumentsWriter, is_reference
@@ -62,29 +72,50 @@ class PackageLoadingError(ValueError):
 
 
 def get_environment(
-    package_name: str, views_style: OutputStyle = OutputStyle.MKDOCS
+    package_name: str,
+    views_style: OutputStyle = OutputStyle.MKDOCS,
+    custom_templates_path: Optional[str] = None,
 ) -> Environment:
     templates_folder = f"views_{views_style.name}".lower()
 
+    loaders = []
+
+    # If custom templates path is provided, validate and add FileSystemLoader first
+    if custom_templates_path:
+        custom_path = Path(custom_templates_path)
+        if not custom_path.exists():
+            raise ValueError(
+                f"Custom templates path does not exist: {custom_templates_path}"
+            )
+        if not custom_path.is_dir():
+            raise ValueError(
+                f"Custom templates path is not a directory: {custom_templates_path}"
+            )
+        loaders.append(FileSystemLoader(str(custom_path)))
+
+    # Always add the package loader as fallback
     try:
-        loader = PackageLoader(package_name, templates_folder)
+        loaders.append(PackageLoader(package_name, templates_folder))
     except ValueError as package_loading_error:  # pragma: no cover
-        raise PackageLoadingError(
-            views_style, templates_folder
-        ) from package_loading_error
-    else:
-        env = Environment(
-            loader=loader,
-            autoescape=select_autoescape(["html", "xml"])
-            if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
-            else False,
-            auto_reload=True,
-            enable_async=False,
-        )
-        configure_filters(env)
-        configure_functions(env)
+        if not custom_templates_path:
+            raise PackageLoadingError(
+                views_style, templates_folder
+            ) from package_loading_error
+
+    loader = ChoiceLoader(loaders)
+
+    env = Environment(
+        loader=loader,
+        autoescape=select_autoescape(["html", "xml"])
+        if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
+        else False,
+        auto_reload=True,
+        enable_async=False,
+    )
+    configure_filters(env)
+    configure_functions(env)
 
-        return env
+    return env
 
 
 class Jinja2DocumentsWriter(DocumentsWriter):
@@ -97,8 +128,9 @@ class Jinja2DocumentsWriter(DocumentsWriter):
         self,
         package_name: str,
         views_style: OutputStyle = OutputStyle.MKDOCS,
+        custom_templates_path: Optional[str] = None,
     ) -> None:
-        self._env = get_environment(package_name, views_style)
+        self._env = get_environment(package_name, views_style, custom_templates_path)
 
     @property
     def env(self) -> Environment:

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/md.py

@@ -2,12 +2,13 @@
 This module provides common functions to handle Markdown.
 These functions apply to any kind of Markdown work.
 """
-from typing import Dict, Iterable
+
+from typing import Iterable
 
 
 def write_row(
     row: Iterable[str],
-    columns_widths: Dict[int, int],
+    columns_widths: dict[int, int],
     padding: int = 1,
     indent: int = 0,
 ) -> str:

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/mk/v3/__init__.py

@@ -1,6 +1,7 @@
 """
 This module provides functions to generate Markdown for OpenAPI Version 3.
 """
+
 import copy
 import os
 import warnings
@@ -95,11 +96,14 @@ class OpenAPIV3DocumentationHandler:
         writer: Optional[DocumentsWriter] = None,
         style: Union[int, str] = 1,
         source: str = "",
+        templates_path: Optional[str] = None,
     ) -> None:
         self._source = source
         self.texts = texts or EnglishTexts()
         self._writer = writer or Jinja2DocumentsWriter(
-            __name__, views_style=style_from_value(style)
+            __name__,
+            views_style=style_from_value(style),
+            custom_templates_path=templates_path,
         )
         self.doc = self.normalize_data(copy.deepcopy(doc))
 

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/utils/source.py

@@ -1,8 +1,10 @@
 """
 This module provides methods to obtain OpenAPI Documentation from file or web sources.
 """
+
 import json
 from pathlib import Path
+from typing import Any
 
 import yaml
 
@@ -11,7 +13,7 @@ from openapidocs.logs import logger
 from .web import ensure_success, http_get
 
 
-def read_from_json_file(file_path: Path):
+def read_from_json_file(file_path: Path) -> dict[Any, Any] | list[Any]:
     """
     Reads JSON from a given file by path.
     """
@@ -19,7 +21,7 @@ def read_from_json_file(file_path: Path):
         return json.loads(source_file.read())
 
 
-def read_from_yaml_file(file_path: Path):
+def read_from_yaml_file(file_path: Path) -> dict[Any, Any] | list[Any]:
     """
     Reads YAML from a given file by path.
     """
@@ -32,7 +34,7 @@ class SourceError(Exception):
         super().__init__(message)
 
 
-def read_from_url(url: str):
+def read_from_url(url: str) -> dict[Any, Any] | list[Any]:
     """
     Tries to read OpenAPI Documentation from the given source URL.
     This method will try to fetch JSON or YAML from the given source, in case of
@@ -63,7 +65,10 @@ def read_from_url(url: str):
             )
 
 
-def read_from_source(source: str, cwd: Path = None):
+def read_from_source(
+    source: str,
+    cwd: Path | None = None,
+) -> dict[Any, Any] | list[Any]:
     """
     Tries to read a JSON or YAML file from a given source.
     The source can be a path to a file, or a URL.

{essentials_openapi-1.2.1 → essentials_openapi-1.3.0}/openapidocs/utils/web.py

@@ -6,7 +6,7 @@ http_client = httpx.Client(verify=False, timeout=20)
 
 
 class FailedRequestError(Exception):
-    def __init__(self, message) -> None:
+    def __init__(self, message: str) -> None:
         super().__init__(
             f"Failed request: {message}. "
             "Inspect the inner exception (__context__) for more information."