vdoc 0.1.0__py3-none-any.whl

vdoc/__init__.py

@@ -0,0 +1,33 @@
+"""Multi version documentation hosting."""
+
+from importlib_metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib_metadata import version as _version
+
+__module_name__ = "vdoc"
+
+try:  # pragma: no cover
+    __version__ = _version(__module_name__)
+except _PackageNotFoundError as error:  # pragma: no cover
+    raise ModuleNotFoundError(
+        f"Unable to determine version of package '{__module_name__}'. "
+        "If you are on a local development system, use 'pip install -e .[dev]' in order to install the package. "
+        "If you are on a productive system, this shouldn't happen. Please report a bug."
+    ) from error
+
+
+def get_app_name() -> str:
+    """Returns the human-readable and prettified name of the application.
+
+    Returns:
+        The name of the application.
+    """
+    return __module_name__.replace("_", "-")
+
+
+def get_app_version() -> str:
+    """Returns the version of the application.
+
+    Returns:
+        The version of the application.
+    """
+    return __version__

vdoc/api/__init__.py

@@ -0,0 +1,96 @@
+"""Contains the Rest API."""
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.routing import Mount
+from fastapi.staticfiles import StaticFiles
+from starlette.requests import Request
+from starlette.responses import FileResponse
+from starlette.routing import BaseRoute
+
+from vdoc.api.routes import projects as PROJECTS_MODULE
+from vdoc.exceptions import VDocException
+from vdoc.methods.api.projects import get_project_version_impl
+from vdoc.settings import VDocSettings
+
+_PACKAGE_PATH = Path(__file__).parent.parent
+
+webapp_path = _PACKAGE_PATH / "webapp"
+docs_path = _PACKAGE_PATH / "docs"
+
+routes: list[BaseRoute] = [
+    Mount(
+        "/static/docs",
+        app=StaticFiles(directory=str(docs_path), html=True, check_dir=False),
+        name="vdoc-docs",
+    ),
+    Mount(
+        "/static/projects",
+        app=StaticFiles(directory=VDocSettings().docs_dir.as_posix(), html=True, check_dir=False),
+        name="projects",
+    ),
+]
+
+app = FastAPI(docs_url="/apidoc")
+
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(PROJECTS_MODULE.router, prefix="/api")
+
+
+@app.exception_handler(VDocException)
+async def unicorn_exception_handler(_: Request, exc: VDocException) -> JSONResponse:
+    """Catches all ``VDocException`` exceptions and returns them as properly formatted JSONResponse.
+
+    Args:
+        exc: The catched exception.
+
+    Returns:
+        The exception as formatted JSONResponse.
+    """
+    return JSONResponse(status_code=exc.status_code, content={"message": exc.detail})
+
+
+@app.get("/{project_name}/{version}/objects.inv")
+def serve_sphinx_objects_inventory(project_name: str, version: str) -> FileResponse:  # pylint: disable=unused-argument
+    """Serves the objects.inv sphinx file for intersphinx mappings.
+
+    Args:
+        project_name: The requested project name.
+        version: The requested project version.
+
+    Returns:
+        FileResponse: The objects.inv file.
+    """
+    served_version = get_project_version_impl(name=project_name, version=version)
+
+    return FileResponse(path=VDocSettings().docs_dir / project_name / served_version / "objects.inv")
+
+
+for route in routes:
+    app.routes.append(route)
+
+
+@app.get("/{file_path:path}")
+def serve_ui_and_assets(file_path: str) -> FileResponse:  # pylint: disable=unused-argument
+    """Serves the web UI and the static assets (JS bundles, ...) as a last fallback for all non-matched requests.
+
+    Args:
+        file_path (str): The requested file path.
+
+    Returns:
+        FileResponse: The requested asset file if existing, otherwise the index.html.
+    """
+    if (full_path := webapp_path / file_path).is_file():
+        return FileResponse(path=full_path)
+    return FileResponse(path=webapp_path / "index.html")

vdoc/api/dependencies/__init__.py

@@ -0,0 +1 @@
+"""Contains all FastAPI dependencies."""

vdoc/api/dependencies/auth.py

@@ -0,0 +1,32 @@
+"""Contains all authentication dependencies."""
+
+import secrets
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi.security import HTTPBasic, HTTPBasicCredentials
+
+from vdoc.exceptions import InvalidCredentials
+from vdoc.settings import VDocSettings
+
+security = HTTPBasic()
+
+
+def require_authentication(credentials: Annotated[HTTPBasicCredentials, Depends(security)]) -> bool:
+    """FastAPI dependency that checks for HTTP Basic Auth credentials in the request header.
+
+    Args:
+        credentials: The HTTPBasicAuth credentials sent with the request heder.
+
+    Raises:
+        HTTPException: If the credentials are not valid.
+
+    Returns:
+        True if the request is authenticated.
+    """
+    settings = VDocSettings()
+    is_correct_username = secrets.compare_digest(credentials.username.encode("utf8"), settings.api_username)
+    is_correct_password = secrets.compare_digest(credentials.password.encode("utf8"), settings.api_password)
+    if not (is_correct_username and is_correct_password):
+        raise InvalidCredentials()
+    return True

vdoc/api/routes/__init__.py

@@ -0,0 +1 @@
+"""Contains all REST API routes."""

vdoc/api/routes/projects.py

@@ -0,0 +1,71 @@
+"""Contains all projects related REST API routes."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, UploadFile
+from fastapi.responses import JSONResponse
+
+from vdoc.api.dependencies.auth import require_authentication
+from vdoc.methods.api.projects import (
+    get_project_version_impl,
+    list_project_versions_impl,
+    list_projects_impl,
+    upload_project_version_impl,
+)
+from vdoc.models.project import Project
+
+router = APIRouter(prefix="/projects", tags=["Projects"])
+
+
+@router.get("/")
+def list_projects() -> list[Project]:
+    """Lists all available projects.
+
+    Returns:
+        A list of all available projects.
+    """
+    return list_projects_impl()
+
+
+@router.get("/{name}/versions/")
+def list_project_versions(name: str) -> list[str]:
+    """Lists all versions of a project.
+
+    Args:
+        name: The name of the project.
+
+    Returns:
+        A list of all versions of a project.
+    """
+    return list_project_versions_impl(name=name)
+
+
+@router.get("/{name}/versions/{version}")
+def get_project_versions(name: str, version: str) -> str:
+    """Returns the requested project version.
+
+    Args:
+        name: The name of the project.
+        version: The requested version.
+
+    Returns:
+        The requested project version.
+    """
+    return get_project_version_impl(name=name, version=version)
+
+
+@router.post("/{name}/versions/{version}")
+def upload_project_version(
+    name: str, version: str, file: UploadFile, _: Annotated[str, Depends(require_authentication)]
+) -> JSONResponse:
+    """Accepts and processes an uploaded project documentation.
+
+    Args:
+        name: The project name.
+        version: The project version.
+        file: The documentation zip file.
+
+    Returns:
+        A message that the documentation has been uploaded successfully.
+    """
+    return upload_project_version_impl(name=name, version=version, file=file)

vdoc/cli/__init__.py

@@ -0,0 +1 @@
+"""Contains the CLI."""

vdoc/cli/main.py

@@ -0,0 +1,84 @@
+"""Contains the main CLI entry point."""
+
+import logging
+from enum import Enum
+
+import typer
+from rich.logging import RichHandler
+
+from vdoc import get_app_name, get_app_version
+from vdoc.cli.run import _cli_run
+from vdoc.constants import DEFAULT_API_PASSWORD, DEFAULT_API_USERNAME
+from vdoc.settings import VDocSettings
+
+_logger = logging.getLogger(__name__)
+
+
+app = typer.Typer()
+app.command(name="run", help="Runs the application")(_cli_run)
+
+
+class LogLevel(str, Enum):
+    """Enum for log levels for typer."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+
+    def __str__(self) -> str:
+        """String representation of the log level.
+
+        Returns:
+            The log level as string.
+        """
+        return self.value
+
+
+def print_version(do_print: bool) -> None:
+    """Prints the version of the software.
+
+    Args:
+        do_print: If the version shall be printed.
+
+    Raises:
+        typer.Exit: After the version was printed.
+    """
+    if do_print:
+        print(get_app_version())
+        raise typer.Exit()
+
+
+def check_for_default_credentials() -> None:
+    """Checks the configured API credentials and warns if the default credentials are used."""
+    settings = VDocSettings()
+    if settings.api_password == DEFAULT_API_PASSWORD and settings.api_username == DEFAULT_API_USERNAME:
+        _logger.warning(
+            "The application is running using the default credentials. Update them according to the documentation!"
+        )
+
+
+@app.callback()
+def _common(
+    _: bool = typer.Option(
+        False,
+        "--version",
+        callback=print_version,
+        is_eager=True,
+        help="Print the installed version of the software.",
+    ),
+    log_level: LogLevel = typer.Option(LogLevel.INFO, help="The log level"),
+) -> None:
+    rich_handler = RichHandler()
+    rich_handler.setFormatter(logging.Formatter("%(message)s"))
+    logger = logging.getLogger()
+    logger.handlers = [rich_handler]
+    logger.setLevel(log_level)
+    _logger.info(f"Starting {get_app_name()}@{get_app_version()}")
+    check_for_default_credentials()
+
+
+typer_click_object = typer.main.get_command(app)
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

vdoc/cli/run.py

@@ -0,0 +1,30 @@
+"""This module defines the typer run method."""
+
+import logging
+from typing import Annotated
+
+import typer
+
+from vdoc.methods.cli.cli_run_method import run_impl
+from vdoc.settings import VDocSettings
+
+_logger = logging.getLogger(__name__)
+
+
+def _cli_run(
+    bind_address: Annotated[
+        str,
+        typer.Option(help="Application bind ip address."),
+    ] = VDocSettings().bind_address,
+    bind_port: Annotated[
+        int,
+        typer.Option(help="Application bind port."),
+    ] = VDocSettings().bind_port,
+) -> None:  # noqa: disable=D103
+    try:
+        run_impl(bind_address=bind_address, bind_port=bind_port)
+    except KeyboardInterrupt as error:
+        raise typer.Exit(0) from error
+    except Exception as error:
+        _logger.error(error)
+        raise typer.Exit(1) from error

vdoc/constants.py

@@ -0,0 +1,11 @@
+"""Contains all constant values."""
+
+from pathlib import Path
+
+CONFIG_ENV_PREFIX = "VDOC_"
+
+DEFAULT_DOCS_DIR = Path("/srv/vdoc/docs/")
+DEFAULT_API_USERNAME = b"admin"
+DEFAULT_API_PASSWORD = b"admin"
+DEFAULT_BIND_ADDRESS = "0.0.0.0"
+DEFAULT_BIND_PORT = 8080

vdoc/docs/_sources/index.rst.txt

@@ -0,0 +1,20 @@
+.. include:: ../README.rst
+
+########
+Contents
+########
+
+.. toctree::
+   :maxdepth: 2
+
+   vdoc
+
+
+##############################
+License Compliance Information
+##############################
+
+.. toctree::
+   :maxdepth: 1
+
+   license_compliance