stoplight-fastapi 0.1.0__tar.gz

stoplight_fastapi-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 Tho Nguyen
+
+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.

stoplight_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: stoplight-fastapi
+Version: 0.1.0
+Summary: Seamlessly integrate Stoplight Elements for beautiful, interactive API documentation in FastAPI.
+Keywords: fastapi,api,documentation,stoplight,openapi,interactive-docs,api-docs,rest-api,swagger
+Author: Tho Nguyen
+Author-email: Tho Nguyen <contact@naiwaaa.simplelogin.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: fastapi>=0.115.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://codeberg.org/naiwaaa/stoplight-fastapi
+Project-URL: Documentation, https://codeberg.org/naiwaaa/stoplight-fastapi
+Project-URL: Repository, https://codeberg.org/naiwaaa/stoplight-fastapi
+Project-URL: Issues, https://codeberg.org/naiwaaa/stoplight-fastapi/issues
+Description-Content-Type: text/markdown
+
+# Stoplight Elements API Documentation Plugin for FastAPI
+
+[![Package - Version](https://img.shields.io/pypi/v/stoplight-fastapi)](https://pypi.python.org/pypi/stoplight-fastapi)
+[![Package - Supported Python Versions](https://img.shields.io/pypi/pyversions/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi)
+[![Package - License](https://img.shields.io/pypi/l/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi/src/branch/main/LICENSE)
+
+## Installation
+
+Install `stoplight-fastapi` using your preferred package manager:
+
+### Using uv (recommended)
+
+```bash
+uv add stoplight-fastapi
+```
+
+### Using pip
+
+```bash
+pip install stoplight-fastapi
+```
+
+### Requirements
+
+- Python 3.10 or higher
+- FastAPI 0.115.0 or higher
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from stoplight_fastapi import get_stoplight_api_reference
+
+app = FastAPI(
+  title="My API",
+  description="Welcome to My Awesome API.",
+  version="1.0.0",
+)
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: str = None):
+  """Get an item by ID."""
+  return {"item_id": item_id, "q": q}
+
+@app.get("/stoplight", include_in_schema=False)
+def get_stoplight_html():
+  """Render API documentation with Stoplight Elements."""
+  return get_stoplight_api_reference(
+    openapi_url=app.openapi_url,
+    title=app.title,
+  )
+
+if __name__ == "__main__":
+  import uvicorn
+  uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+Then visit `http://localhost:8000/stoplight` to view your API documentation.
+
+### Advanced Configuration
+
+Customize the Stoplight Elements UI with
+[advanced options](https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options):
+
+```python
+from stoplight_fastapi import get_stoplight_api_reference, StoplightConfig
+
+@app.get("/docs", include_in_schema=False)
+def get_stoplight_html():
+  """Advanced Stoplight Elements configuration."""
+  return get_stoplight_api_reference(
+    openapi_url=app.openapi_url,
+    stoplight_config=StoplightConfig(
+      router="hash",  # Enable hash-based routing for shareable links
+      layout="stacked",  # Choose between 'sidebar', 'responsive', and 'stacked' layouts
+      # Additional Stoplight configuration options available
+    ),
+  )
+```
+
+## Live Example
+
+![demo](https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/assets/screenshot.png)
+
+```bash
+uv run https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/scripts/playground.py
+```
+
+Visit `http://localhost:8000/stoplight` to see Stoplight Elements in action.
+
+## Resources
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com)
+- [Stoplight Elements Documentation](https://docs.stoplight.io/docs/elements/d6a8ba3f3c186-stoplight-elements)

stoplight_fastapi-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Stoplight Elements API Documentation Plugin for FastAPI
+
+[![Package - Version](https://img.shields.io/pypi/v/stoplight-fastapi)](https://pypi.python.org/pypi/stoplight-fastapi)
+[![Package - Supported Python Versions](https://img.shields.io/pypi/pyversions/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi)
+[![Package - License](https://img.shields.io/pypi/l/stoplight-fastapi)](https://codeberg.org/naiwaaa/stoplight-fastapi/src/branch/main/LICENSE)
+
+## Installation
+
+Install `stoplight-fastapi` using your preferred package manager:
+
+### Using uv (recommended)
+
+```bash
+uv add stoplight-fastapi
+```
+
+### Using pip
+
+```bash
+pip install stoplight-fastapi
+```
+
+### Requirements
+
+- Python 3.10 or higher
+- FastAPI 0.115.0 or higher
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from stoplight_fastapi import get_stoplight_api_reference
+
+app = FastAPI(
+  title="My API",
+  description="Welcome to My Awesome API.",
+  version="1.0.0",
+)
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: str = None):
+  """Get an item by ID."""
+  return {"item_id": item_id, "q": q}
+
+@app.get("/stoplight", include_in_schema=False)
+def get_stoplight_html():
+  """Render API documentation with Stoplight Elements."""
+  return get_stoplight_api_reference(
+    openapi_url=app.openapi_url,
+    title=app.title,
+  )
+
+if __name__ == "__main__":
+  import uvicorn
+  uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+Then visit `http://localhost:8000/stoplight` to view your API documentation.
+
+### Advanced Configuration
+
+Customize the Stoplight Elements UI with
+[advanced options](https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options):
+
+```python
+from stoplight_fastapi import get_stoplight_api_reference, StoplightConfig
+
+@app.get("/docs", include_in_schema=False)
+def get_stoplight_html():
+  """Advanced Stoplight Elements configuration."""
+  return get_stoplight_api_reference(
+    openapi_url=app.openapi_url,
+    stoplight_config=StoplightConfig(
+      router="hash",  # Enable hash-based routing for shareable links
+      layout="stacked",  # Choose between 'sidebar', 'responsive', and 'stacked' layouts
+      # Additional Stoplight configuration options available
+    ),
+  )
+```
+
+## Live Example
+
+![demo](https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/assets/screenshot.png)
+
+```bash
+uv run https://codeberg.org/naiwaaa/stoplight-fastapi/raw/branch/main/scripts/playground.py
+```
+
+Visit `http://localhost:8000/stoplight` to see Stoplight Elements in action.
+
+## Resources
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com)
+- [Stoplight Elements Documentation](https://docs.stoplight.io/docs/elements/d6a8ba3f3c186-stoplight-elements)

stoplight_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,204 @@
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "stoplight-fastapi"
+version = "0.1.0"
+description = "Seamlessly integrate Stoplight Elements for beautiful, interactive API documentation in FastAPI."
+readme = "README.md"
+keywords = [
+  "fastapi",
+  "api",
+  "documentation",
+  "stoplight",
+  "openapi",
+  "interactive-docs",
+  "api-docs",
+  "rest-api",
+  "swagger",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Tho Nguyen", email = "contact@naiwaaa.simplelogin.com" },
+]
+classifiers = [
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = [
+  "fastapi>=0.115.0",
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/naiwaaa/stoplight-fastapi"
+Documentation = "https://codeberg.org/naiwaaa/stoplight-fastapi"
+Repository = "https://codeberg.org/naiwaaa/stoplight-fastapi"
+Issues = "https://codeberg.org/naiwaaa/stoplight-fastapi/issues"
+
+[dependency-groups]
+dev = [
+  "ipykernel>=7.2.0",
+  "uvicorn>=0.41.0",
+  # code quality
+  "ruff>=0.15.1",
+  "mypy[dmypy,faster-cache]>=1.19.1",
+  # tests
+  "hypothesis>=6.151.6",
+  "inline-snapshot>=0.31.1",
+  "pytest>=9.0.2",
+  "pytest-asyncio>=1.3.0",
+  "pytest-benchmark>=5.2.3",
+  "pytest-cov>=7.0.0",
+  "pytest-instafail>=0.5.0",
+  "pytest-memray>=1.8.0",
+  "pytest-mock>=3.15.1",
+  "pytest-randomly>=4.0.1",
+  "pytest-sugar>=1.1.1",
+  "pytest-timeout>=2.4.0",
+  "pytest-xdist>=3.8.0",
+  "respx>=0.22.0",
+]
+
+[tool.mypy]
+exclude = [".cache/", ".venv/"]
+# disallow dynamic typing
+disallow_any_unimported = true
+disallow_any_expr = false
+disallow_any_decorated = true
+disallow_any_explicit = false
+disallow_any_generics = true
+disallow_subclassing_any = true
+# untyped definitions and calls
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+# none and optional handling
+implicit_optional = false
+strict_optional = true
+# configuring warnings
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_return_any = true
+warn_unreachable = true
+# miscellaneous strictness flags
+allow_redefinition = false
+enable_error_code = [
+  "redundant-self",
+  "redundant-expr",
+  "possibly-undefined",
+  "truthy-bool",
+  "truthy-iterable",
+  "ignore-without-code",
+  "unused-awaitable",
+  "unused-ignore",
+  "explicit-override",
+  "mutable-override",
+  "unimported-reveal",
+  "exhaustive-match",
+]
+implicit_reexport = false
+strict_concatenate = true
+strict_equality = true
+strict_equality_for_none = true
+strict = true
+# configuring error messages
+show_error_context = true
+show_column_numbers = true
+# incremental mode
+cache_dir = ".cache/mypy"
+# advanced options
+plugins = []
+
+[tool.pytest.ini_options]
+addopts = [
+  # general
+  "--exitfirst",
+  "--strict",
+  "--failed-first",
+  # reporting
+  "--durations=5",
+  "-vv",
+  "--no-header",
+  "-ra",
+  "--showlocals",
+  "--junitxml=.cache/pytest/report.xml",
+  # collection
+  "--ignore-glob=**/fixtures/*",
+  "--import-mode=importlib",
+  "--doctest-modules",
+  "--doctest-continue-on-failure",
+  # pytest-benchmark
+  "--benchmark-warmup=on",
+  "--benchmark-disable-gc",
+  "--benchmark-storage=file://./.cache/benchmarks",
+  "--benchmark-sort=mean",
+  "--benchmark-columns=min,mean,stddev,outliers,rounds,iterations",
+  "--benchmark-disable",
+  # pytest-cov
+  "--cov",
+  "--cov-report=term-missing:skip-covered",
+  "--cov-report=xml:.cache/pytest/coverage.xml",
+  "--cov-config=pyproject.toml",
+  # pytest-instafail
+  "--instafail",
+  # pytest-memray
+  "--memray",
+  "--most-allocations=5",
+  # pytest-timeout
+  "--timeout=15",
+  # pytest-xdist
+  "-n=auto",
+  # hypothesis
+  "--hypothesis-show-statistics",
+  "--hypothesis-explain",
+]
+cache_dir = ".cache/pytest"
+doctest_optionflags = "NUMBER IGNORE_EXCEPTION_DETAIL"
+pythonpath = ["."]
+markers = [
+  "slow: marks tests as slow",
+  "network: marks tests that require network access",
+]
+testpaths = ["tests"]
+# pytest-asyncio
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+source = ["src/", "tests/"]
+branch = true
+data_file = ".cache/pytest/coverage"
+relative_files = true
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true
+skip_covered = true
+exclude_also = [
+  "raise NotImplementedError",
+  "if __name__ == .__main__.:",
+]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_scheme = "pep440"
+version_provider = "uv"

stoplight_fastapi-0.1.0/src/stoplight_fastapi/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from stoplight_fastapi.__version__ import __version__
+from stoplight_fastapi.stoplight import StoplightConfig, get_stoplight_api_reference
+
+
+__all__ = ["StoplightConfig", "__version__", "get_stoplight_api_reference"]

stoplight_fastapi-0.1.0/src/stoplight_fastapi/__version__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from importlib.metadata import version as _metadata_version
+
+
+__version__ = _metadata_version("stoplight-fastapi")

stoplight_fastapi-0.1.0/src/stoplight_fastapi/stoplight.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Literal
+
+from annotated_doc import Doc
+from fastapi.responses import HTMLResponse
+
+
+_default_style = "<style>body { margin: 0; padding: 0; height: 100vh; }</style>"
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class StoplightConfig:
+    """Stoplight Elements configuration options.
+
+    Read more about it in the
+    [Stoplight Elements Configuration Options document](https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options)
+    """
+
+    base_path: str | None = None
+    hide_internal: bool = False
+    hide_try_it: bool = False
+    hide_try_it_panel: bool = False
+    hide_schemas: bool = False
+    hide_export: bool = False
+    try_it_cors_proxy: str | None = None
+    try_it_credentials_policy: Literal["omit", "include", "same-origin"] = "omit"
+    layout: Literal["sidebar", "responsive", "stacked"] = "sidebar"
+    logo: str | None = None
+    router: Literal["history", "hash", "memory", "static"] = "hash"
+
+    def to_html_attributes(self) -> list[str]:
+        attributes: list[str] = []
+
+        for field in self.__annotations__:
+            value = getattr(self, field)
+            if value:
+                attributes.append(f'{field.replace("_", "")}="{value}"')
+
+        return attributes
+
+
+def get_stoplight_api_reference(
+    *,
+    openapi_url: Annotated[
+        str | None,
+        Doc(
+            """
+            The OpenAPI URL that Stoplight Elements should load and use.
+            """
+        ),
+    ],
+    title: Annotated[
+        str,
+        Doc(
+            """
+            The HTML `<title>` content, normally shown in the browser tab.
+
+            Defaults to "Stoplight Elements" if not provided.
+            """
+        ),
+    ] = "Stoplight Elements",
+    stoplight_js_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL to use to load the Stoplight Elements JavaScript.
+            """
+        ),
+    ] = "https://unpkg.com/@stoplight/elements/web-components.min.js",
+    stoplight_css_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL to use to load the Stoplight Elements CSS.
+            """
+        ),
+    ] = "https://unpkg.com/@stoplight/elements/styles.min.css",
+    stoplight_favicon_url: Annotated[
+        str,
+        Doc(
+            """
+            The URL of the favicon to use. It is normally shown in the browser tab.
+            """
+        ),
+    ] = "https://fastapi.tiangolo.com/img/favicon.png",
+    stoplight_config: Annotated[
+        StoplightConfig | None,
+        Doc(
+            """
+            Configuration options for Stoplight Elements.
+
+            Read more about it in the
+            [Stoplight Elements Configuration Options document](https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options)
+            """
+        ),
+    ] = None,
+    style: Annotated[
+        str,
+        Doc(
+            """
+            Additional CSS styles to apply to the page.
+
+            By default, it sets the body to have no margin or padding and a height of
+            100vh.
+            """
+        ),
+    ] = _default_style,
+) -> HTMLResponse:
+    config = stoplight_config or StoplightConfig()
+
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/>
+        <title>{title or "Stoplight Elements"}</title>
+        <link rel="shortcut icon" href="{stoplight_favicon_url}">
+        <link rel="stylesheet" href="{stoplight_css_url}">
+        <script src="{stoplight_js_url}" crossorigin></script>
+
+        {style}
+    </head>
+    <body>
+        <elements-api apiDescriptionUrl="{openapi_url}" {" ".join(config.to_html_attributes())}/>
+    </body>
+    </html>
+    """  # noqa: E501
+
+    return HTMLResponse(html)