rapidoc 0.1.0__tar.gz

rapidoc-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+# One rapidoc release, copied in by scripts/sync_assets.py (build output of packages/rapidoc)
+src/rapidoc/assets/

rapidoc-0.1.0/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Mrinmoy Majumdar
+
+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.

rapidoc-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: rapidoc
+Version: 0.1.0
+Summary: RapiDoc for Python web frameworks: serves an interactive OpenAPI reference (<rapi-doc>) from a FastAPI or Starlette app
+Project-URL: Homepage, https://rapidocui.com
+Project-URL: Repository, https://github.com/rapi-doc/RapiDoc
+Project-URL: Issues, https://github.com/rapi-doc/RapiDoc/issues
+Author-email: Mrinmoy Majumdar <mrin9@yahoo.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: api documentation,fastapi,openapi,rapidoc,rapidoc-integration,starlette,swagger ui
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: uvicorn>=0.23; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.27; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# rapidoc (Python)
+
+Serves a [RapiDoc](https://rapidocui.com) API reference from a [FastAPI](https://fastapi.tiangolo.com) or Starlette app: an interactive page for your OpenAPI document, with a console to try requests.
+
+```bash
+pip install rapidoc
+```
+
+```python
+from fastapi import FastAPI
+from rapidoc.fastapi import setup_rapidoc
+
+app = FastAPI(docs_url=None, redoc_url=None)
+
+setup_rapidoc(app)
+```
+
+Open `/docs`. The page reads the app's own `/openapi.json`, and nothing is loaded from another site: the package carries the RapiDoc bundle.
+
+FastAPI serves Swagger UI at `/docs` unless you create the app with `docs_url=None`. To keep Swagger UI, give RapiDoc another path: `setup_rapidoc(app, path="/reference")`.
+
+## Options
+
+| Option | Default | |
+| :--- | :--- | :--- |
+| `path` | `/docs` | Where the reference is served, within the app |
+| `spec_url` | the app's `openapi_url` | URL of the OpenAPI document. A path starting with `/` is a path of the app |
+| `spec` | | The OpenAPI document itself (a dict or JSON text), written into the page |
+| `title` | the app's title + "API Reference" | Page title |
+| `assets` | `"bundled"` | `"bundled"`: the app serves `rapidoc-min.js`. `"cdn"`: the browser loads the same version from jsDelivr, checked against its SRI hash. `{"script_url": ..., "integrity": ...}`: a URL of your own |
+| `options` | | [Attributes of `<rapi-doc>`](https://rapidocui.com/api/): `{"render_style": "focused", "allow_try": False}`. Names can be written with underscores, hyphens or in camelCase |
+| `head`, `css` | | Markup and CSS added to the page as given |
+| `lang` | `en` | Language of the page |
+| `nonce` | | Content-Security-Policy nonce, or a function that takes the request and returns it |
+| `enabled` | `True` | `False` adds nothing, for example outside development |
+
+These are the options of every RapiDoc integration, in Python naming.
+
+## Behind a proxy
+
+When a proxy strips a path prefix, run the app with that prefix as its `root_path` (`uvicorn app:app --root-path /api`, or `FastAPI(root_path="/api")`). The page then uses the prefix for the bundle, the OpenAPI document and the OAuth return page, as FastAPI's own docs do.
+
+## Starlette
+
+`from rapidoc.starlette import setup_rapidoc` is the same function, for any Starlette app. Starlette has no OpenAPI endpoint of its own, so pass `spec_url` or `spec`.
+
+## Notes
+
+- Each release ships one version of `rapidoc`: `rapidoc.rapidoc_version()`.
+- The routes are left out of the app's OpenAPI document.
+- OAuth sign-in returns to `{path}/oauth-receiver.html`, which the app serves on its own origin, also with `assets="cdn"`.
+- [`examples/app.py`](./examples/app.py) is a complete app.
+
+- The package itself requires no framework; `rapidoc.fastapi` uses the Starlette that FastAPI installs. `rapidoc.contract` is the RapiDoc integration contract in plain Python, for building an integration for another framework.
+
+Python 3.10 or later; Starlette 0.27 or later. MIT.

rapidoc-0.1.0/README.md

@@ -0,0 +1,56 @@
+# rapidoc (Python)
+
+Serves a [RapiDoc](https://rapidocui.com) API reference from a [FastAPI](https://fastapi.tiangolo.com) or Starlette app: an interactive page for your OpenAPI document, with a console to try requests.
+
+```bash
+pip install rapidoc
+```
+
+```python
+from fastapi import FastAPI
+from rapidoc.fastapi import setup_rapidoc
+
+app = FastAPI(docs_url=None, redoc_url=None)
+
+setup_rapidoc(app)
+```
+
+Open `/docs`. The page reads the app's own `/openapi.json`, and nothing is loaded from another site: the package carries the RapiDoc bundle.
+
+FastAPI serves Swagger UI at `/docs` unless you create the app with `docs_url=None`. To keep Swagger UI, give RapiDoc another path: `setup_rapidoc(app, path="/reference")`.
+
+## Options
+
+| Option | Default | |
+| :--- | :--- | :--- |
+| `path` | `/docs` | Where the reference is served, within the app |
+| `spec_url` | the app's `openapi_url` | URL of the OpenAPI document. A path starting with `/` is a path of the app |
+| `spec` | | The OpenAPI document itself (a dict or JSON text), written into the page |
+| `title` | the app's title + "API Reference" | Page title |
+| `assets` | `"bundled"` | `"bundled"`: the app serves `rapidoc-min.js`. `"cdn"`: the browser loads the same version from jsDelivr, checked against its SRI hash. `{"script_url": ..., "integrity": ...}`: a URL of your own |
+| `options` | | [Attributes of `<rapi-doc>`](https://rapidocui.com/api/): `{"render_style": "focused", "allow_try": False}`. Names can be written with underscores, hyphens or in camelCase |
+| `head`, `css` | | Markup and CSS added to the page as given |
+| `lang` | `en` | Language of the page |
+| `nonce` | | Content-Security-Policy nonce, or a function that takes the request and returns it |
+| `enabled` | `True` | `False` adds nothing, for example outside development |
+
+These are the options of every RapiDoc integration, in Python naming.
+
+## Behind a proxy
+
+When a proxy strips a path prefix, run the app with that prefix as its `root_path` (`uvicorn app:app --root-path /api`, or `FastAPI(root_path="/api")`). The page then uses the prefix for the bundle, the OpenAPI document and the OAuth return page, as FastAPI's own docs do.
+
+## Starlette
+
+`from rapidoc.starlette import setup_rapidoc` is the same function, for any Starlette app. Starlette has no OpenAPI endpoint of its own, so pass `spec_url` or `spec`.
+
+## Notes
+
+- Each release ships one version of `rapidoc`: `rapidoc.rapidoc_version()`.
+- The routes are left out of the app's OpenAPI document.
+- OAuth sign-in returns to `{path}/oauth-receiver.html`, which the app serves on its own origin, also with `assets="cdn"`.
+- [`examples/app.py`](./examples/app.py) is a complete app.
+
+- The package itself requires no framework; `rapidoc.fastapi` uses the Starlette that FastAPI installs. `rapidoc.contract` is the RapiDoc integration contract in plain Python, for building an integration for another framework.
+
+Python 3.10 or later; Starlette 0.27 or later. MIT.

rapidoc-0.1.0/examples/app.py

@@ -0,0 +1,15 @@
+"""uvicorn examples.app:app --port 4403  →  http://localhost:4403/docs"""
+
+from fastapi import FastAPI
+
+from rapidoc.fastapi import setup_rapidoc
+
+app = FastAPI(title="FastAPI example", version="1.0.0", docs_url=None, redoc_url=None)
+
+
+@app.get("/hello", tags=["Greetings"], summary="Say hello")
+def hello(name: str = "world") -> dict[str, str]:
+    return {"message": f"Hello, {name}!"}
+
+
+setup_rapidoc(app, options={"render_style": "focused", "color_scheme": "light", "show_header": False})

rapidoc-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rapidoc"
+version = "0.1.0"
+description = "RapiDoc for Python web frameworks: serves an interactive OpenAPI reference (<rapi-doc>) from a FastAPI or Starlette app"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+requires-python = ">=3.10"
+authors = [{ name = "Mrinmoy Majumdar", email = "mrin9@yahoo.com" }]
+keywords = ["fastapi", "starlette", "openapi", "rapidoc", "rapidoc-integration", "api documentation", "swagger ui"]
+classifiers = [
+  "Framework :: FastAPI",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Documentation",
+]
+# No framework is required to install: rapidoc.contract is plain Python, and rapidoc.fastapi uses the
+# Starlette that FastAPI already brings.
+dependencies = []
+
+[project.optional-dependencies]
+starlette = ["starlette>=0.27"]
+fastapi = ["fastapi>=0.100"]
+dev = ["fastapi>=0.100", "httpx>=0.24", "pytest>=7", "uvicorn>=0.23"]
+
+[project.urls]
+Homepage = "https://rapidocui.com"
+Repository = "https://github.com/rapi-doc/RapiDoc"
+Issues = "https://github.com/rapi-doc/RapiDoc/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rapidoc"]
+# The rapidoc bundle is copied in by scripts/sync_assets.py and is not in git
+artifacts = ["src/rapidoc/assets/*"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "scripts", "examples", "README.md", "LICENSE.txt"]
+artifacts = ["src/rapidoc/assets/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rapidoc-0.1.0/scripts/sync_assets.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Copies one rapidoc release into the package: the bundle, its license file and integration.json.
+
+    python scripts/sync_assets.py                 # from the monorepo's packages/rapidoc/dist
+    python scripts/sync_assets.py --from DIR      # from another dist folder
+    python scripts/sync_assets.py --npm           # from the npm registry, the version in RAPIDOC_VERSION
+    python scripts/sync_assets.py --npm 12.2.0    # from the npm registry, another version
+
+The three files must come from the same release: integration.json carries the SRI hash of the bundle.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import shutil
+import tarfile
+import urllib.request
+from pathlib import Path
+
+PROJECT = Path(__file__).resolve().parents[1]
+ASSETS = PROJECT / "src/rapidoc/assets"
+FILES = ["rapidoc-min.js", "rapidoc-min.js.LICENSE.txt", "integration.json"]
+
+
+def from_directory(source: Path) -> None:
+    missing = [name for name in FILES if not (source / name).exists()]
+    if missing:
+        raise SystemExit(f"{source} has no {', '.join(missing)}; build rapidoc first (npm run build:rapidoc)")
+    for name in FILES:
+        shutil.copyfile(source / name, ASSETS / name)
+
+
+def from_npm(version: str) -> None:
+    url = f"https://registry.npmjs.org/rapidoc/-/rapidoc-{version}.tgz"
+    with urllib.request.urlopen(url) as response:  # noqa: S310 (a fixed https registry URL)
+        archive = tarfile.open(fileobj=io.BytesIO(response.read()), mode="r:gz")
+    for name in FILES:
+        member = archive.extractfile(f"package/dist/{name}")
+        if member is None:
+            raise SystemExit(f"rapidoc {version} has no dist/{name}")
+        (ASSETS / name).write_bytes(member.read())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--from", dest="source", type=Path, default=PROJECT.parents[1] / "packages/rapidoc/dist")
+    parser.add_argument(
+        "--npm",
+        metavar="VERSION",
+        nargs="?",
+        const=(PROJECT / "RAPIDOC_VERSION").read_text(encoding="utf-8").strip(),
+        help="download this rapidoc release from npm (default: the version in RAPIDOC_VERSION)",
+    )
+    args = parser.parse_args()
+    ASSETS.mkdir(parents=True, exist_ok=True)
+    if args.npm:
+        from_npm(args.npm)
+    else:
+        from_directory(args.source)
+    version = json.loads((ASSETS / "integration.json").read_text(encoding="utf-8"))["version"]
+    print(f"rapidoc {version} in {ASSETS.relative_to(PROJECT)}:", ", ".join(FILES))
+
+
+if __name__ == "__main__":
+    main()

rapidoc-0.1.0/src/rapidoc/__init__.py

@@ -0,0 +1,41 @@
+"""RapiDoc for Python web frameworks.
+
+    from fastapi import FastAPI
+    from rapidoc.fastapi import setup_rapidoc
+
+    app = FastAPI(docs_url=None, redoc_url=None)
+    setup_rapidoc(app)          # the reference at /docs, reading the app's /openapi.json
+
+``rapidoc.contract`` is the RapiDoc integration contract in Python (a port of ``@rapidoc/embed``): the page,
+the routes and the attributes. A framework module (``rapidoc.fastapi``, ``rapidoc.starlette``) only maps
+them to that framework's routes. This module imports no framework.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import contract
+
+__all__ = ["rapidoc_version", "rapidoc_manifest", "contract", "ASSETS"]
+
+#: One rapidoc release: the bundle, its license file and integration.json
+ASSETS = Path(__file__).parent / "assets"
+
+
+def rapidoc_manifest() -> dict[str, Any]:
+    """``integration.json`` of the rapidoc release this package ships: version, files, SRI hashes."""
+    file = ASSETS / "integration.json"
+    if not file.exists():
+        raise RuntimeError(
+            "rapidoc: the rapidoc bundle is missing from this installation "
+            "(in a source checkout, run scripts/sync_assets.py)"
+        )
+    return json.loads(file.read_text(encoding="utf-8"))
+
+
+def rapidoc_version() -> str:
+    """The version of rapidoc this package serves."""
+    return rapidoc_manifest()["version"]

rapidoc-0.1.0/src/rapidoc/assets/integration.json

@@ -0,0 +1,43 @@
+{
+  "contract": 1,
+  "name": "rapidoc",
+  "version": "12.2.0",
+  "elements": [
+    "rapi-doc",
+    "rapi-doc-mini",
+    "oauth-receiver"
+  ],
+  "cdn": "https://cdn.jsdelivr.net/npm/rapidoc@12.2.0/dist/",
+  "files": {
+    "rapidoc-min.js": {
+      "role": "script",
+      "contentType": "text/javascript; charset=utf-8",
+      "bytes": 643136,
+      "integrity": "sha384-1JA7hsG9FwOzHQnEH+aOO9WV+k74Ft3W1rjU1P7E4RtAXHaVqDP8sa49oGLhuzHD"
+    },
+    "rapidoc-min.js.LICENSE.txt": {
+      "role": "license",
+      "contentType": "text/plain; charset=utf-8",
+      "bytes": 19073,
+      "integrity": "sha384-f2/nGiQja338BGgbRRM9Qb++auJfKpfflao4DEGOVuXc+Y2ORfDs1MugRjYeLXbu"
+    },
+    "oauth-receiver.html": {
+      "role": "oauth-receiver",
+      "contentType": "text/html; charset=utf-8",
+      "bytes": 236,
+      "integrity": "sha384-rfos5ZPmmjObE/xd+YkxUxo2Pj7jgdyLD4FaC9OiacqFZIh53ENId1EYcXyOCcLW"
+    },
+    "rapidoc-flow-min.js": {
+      "role": "flow-script",
+      "contentType": "text/javascript; charset=utf-8",
+      "bytes": 213829,
+      "integrity": "sha384-asDo0SV5f87CcYYk9KjQKpLggdr8OBXYrd/8TV2MvLF/YHGYG9K/9n0OYJUSn/5P"
+    },
+    "rapidoc-flow-min.js.LICENSE.txt": {
+      "role": "flow-license",
+      "contentType": "text/plain; charset=utf-8",
+      "bytes": 8286,
+      "integrity": "sha384-oaDE7s/9ktovzg47bUf0BY+Ksq+YFB84dQKb+WJbfNfk3E7Nd/PUx2RlQZwUS25W"
+    }
+  }
+}