diff --git a/docs/_snippets/core_modules_list.rst b/docs/_snippets/core_modules_list.rst index 37b3513b..8739ac66 100644 --- a/docs/_snippets/core_modules_list.rst +++ b/docs/_snippets/core_modules_list.rst @@ -1,6 +1,3 @@ -.. SPDX-FileCopyrightText: 2026 PythonWoods -.. SPDX-License-Identifier: Apache-2.0 - - :doc:`modules/auth` - Authentication and authorization interfaces - :doc:`modules/configuration` - Multi-layer config with dot-notation - :doc:`modules/database` - Connection pooling, transactions, health checks diff --git a/docs/_snippets/plugins_list.rst b/docs/_snippets/plugins_list.rst index 0901efa0..5ac9b8a8 100644 --- a/docs/_snippets/plugins_list.rst +++ b/docs/_snippets/plugins_list.rst @@ -1,6 +1,3 @@ -.. SPDX-FileCopyrightText: 2026 PythonWoods -.. SPDX-License-Identifier: Apache-2.0 - - :doc:`plugins/auth` - Authentication implementations - :doc:`plugins/bootstrap` - Application lifecycle management - :doc:`plugins/cli-tools` - Advanced development tools diff --git a/docs/conf.py b/docs/conf.py index 27be4c67..6c2ec7a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -77,11 +77,36 @@ def token(varname: str, default: str) -> str: # Configura Furo con force dark options html_theme_options = { - "source_repository": "https://github.com/PythonWoods/structum/", - "source_branch": "main", - "source_directory": "docs/", - "top_of_page_button": "edit", - "navigation_with_keys": True, + "repo_url": "https://github.com/PythonWoods/structum", + "repo_name": "PythonWoods/structum", + "edit_uri": "edit/main/docs", + "font": {"text": "Roboto", "code": "Roboto Mono"}, + "icon": {"repo": "fontawesome/brands/github", "edit": "material/file-edit-outline"}, + "palette": [ + { + "media": "(prefers-color-scheme: light)", + "scheme": "default", + "primary": "indigo", + "accent": "indigo", + }, + { + "media": "(prefers-color-scheme: dark)", + "scheme": "slate", + "primary": "indigo", + "accent": "indigo", + }, + ], + "features": [ + "navigation.expand", + "navigation.tabs", + "navigation.top", + "navigation.sections", + "navigation.indexes", + "navigation.instant", # Improve navigation speed + "header.autohide", # Auto-hide header on scroll + "search.share", # Share search results + ], + "globaltoc_collapse": False, } # -- Autodoc/Napoleon/Exclude ----------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 05ac6f40..19f67acf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,108 +6,77 @@ Structum Framework .. raw:: html - - -
-
-

STRUCTUM

-

Protocol-Based · AI-Assisted · Human-Governed

- Get Started -
-
- ----- - -Core Philosophy ---------------- - -.. grid:: 2 - :gutter: 3 - :padding: 0 - :class-container: features-grid - - .. grid-item-card:: - :class-card: feature-card - :text-align: left - :shadow: none - - **Protocol-First Architecture** - ^^^ - Built on ``typing.Protocol`` interfaces. Decoupled and testable. - - .. grid-item-card:: - :class-card: feature-card - :text-align: left - :shadow: none - - **Zero Dependency Core** - ^^^ - Pure Python Standard Library. Secure and lightweight. - - .. grid-item-card:: - :class-card: feature-card - :text-align: left - :shadow: none - - **Production-Hardened** - ^^^ - Health checks, metrics, and graceful shutdown included. - - .. grid-item-card:: - :class-card: feature-card - :text-align: left - :shadow: none - - **Modular by Design** - ^^^ - Install only what you need. No forced dependencies. - -.. tab-set:: - - .. tab-item:: New Project - - .. code-block:: bash - - # Pre-Alpha: Install from source - git clone https://github.com/PythonWoods/structum.git - cd structum - ./scripts/setup_dev.sh - - .. tip:: - - Generates: Config management, health endpoints, logging, CLI, tests - - .. tab-item:: Existing Project - - .. code-block:: bash - - # Pre-Alpha: Install as editable - pip install -e /path/to/structum - - .. code-block:: python - - from structum import Config, inject - - @inject - def my_function(config: Config): - db_url = config.database.url # Dot-notation access - - .. tab-item:: Docker - - .. code-block:: dockerfile - - # Build a lightweight image - FROM python:3.11-slim-bookworm - WORKDIR /app - COPY requirements.txt . - RUN pip install -r requirements.txt - COPY . . - CMD ["python", "main.py"] - ----- - -Plugin Ecosystem ----------------- + + +Installation +------------ + +.. include:: _snippets/warning_alpha.rst + +For detailed instructions and prerequisites (including **uv** setup), see the :doc:`installation` guide. + +Quick Install (From Source) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: _snippets/install_source.rst + +.. note:: + This installs all workspace packages in editable mode. See :doc:`installation` for details. + +Quick Start +----------- + +The configuration system works out-of-the-box without any setup using ``structum``: + +.. code-block:: python + + from structum.config import get_config + + # Get the singleton instance + config = get_config() + + # Write configuration (automatically persisted) + config.set("server.host", "0.0.0.0") + config.set("server.port", 8080) + + # Read configuration (with safe defaults) + host = config.get("server.host", default="localhost") + port = config.get("server.port", default=8000) + + print(f"Server starting on {host}:{port}") + +For a complete guide on building a production-ready application with plugins, see the :doc:`guides/user_tutorial`. + +Architecture Overview +--------------------- + +Protocol-Based Design +~~~~~~~~~~~~~~~~~~~~~ + +Structum separates **interfaces** (protocols) from **implementations** (plugins): + +.. code-block:: text + + ┌─────────────────────────────────────────┐ + │ Application Code │ + │ Uses: get_config(), get_logger() │ + └──────────────────┬──────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ Structum Core (structum) │ + │ • ConfigProviderInterface │ + │ • LoggerInterface │ + │ • AuthInterface │ + │ • DatabaseInterface │ + └──────────────────┬──────────────────────┘ + │ + ┌──────────────────▼──────────────────────┐ + │ Plugin Implementations │ + │ ┌──────────┬──────────┬──────────┐ │ + │ │ Dynaconf │Observable│ Auth │ │ + │ │ Provider │ Logger │ Provider │ │ + │ └──────────┴──────────┴──────────┘ │ + └─────────────────────────────────────────┘ Structum leverages a modular architecture where the **Core** provides stability and interfaces, while **Plugins** provide implementation details. @@ -148,7 +117,38 @@ Planned Official Plugins - **structum-celery**: Background task processing - **structum-sentry**: Error tracking ----- +Instead of manually wiring ``pydantic``, ``structlog``, ``prometheus_client``, Structum provides a unified API with consistent patterns. + +vs No Framework +~~~~~~~~~~~~~~~ + +As projects grow, you'll reinvent configuration management, logging setup, health checks. Structum provides these patterns from day one. + +Next Steps +---------- + +1. :doc:`guides/user_tutorial` - Build your first application +2. **Explore Core Modules**: + + - :doc:`modules/configuration` + - :doc:`modules/logging` + - :doc:`modules/auth` + - :doc:`modules/database` + - :doc:`modules/monitoring` + +3. :doc:`guides/enterprise_architecture` - Building production systems +4. :doc:`reference/core` - Complete API documentation + +Support +------- + +- **GitHub Issues**: `github.com/PythonWoods/structum/issues `_ +- **Discussions**: `github.com/PythonWoods/structum/discussions `_ + +License +------- + +Apache 2.0 - See `LICENSE `_ .. toctree:: :maxdepth: 2 diff --git a/docs/modules/index.rst b/docs/modules/index.rst index d7b935f7..53a60b2f 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -1,5 +1,4 @@ -.. SPDX-FileCopyrightText: 2026 PythonWoods -.. SPDX-License-Identifier: Apache-2.0 +Core Modules Core Modules ============ diff --git a/packages/structum/src/structum/auth/interfaces.py b/packages/structum/src/structum/auth/interfaces.py index 1ce12e06..8b89dacf 100644 --- a/packages/structum/src/structum/auth/interfaces.py +++ b/packages/structum/src/structum/auth/interfaces.py @@ -32,12 +32,6 @@ class TokenPair: """ Data class containing JWT access and refresh token pair. - Attributes: - access_token (str): Short-lived JWT access token for API requests. - refresh_token (str): Long-lived token for obtaining new access tokens. - token_type (str): Token type, typically "bearer" for JWT. Defaults to "bearer". - expires_at (datetime | None): Expiration timestamp for access token, if available. - Example: Creating and using token pair:: @@ -61,9 +55,16 @@ class TokenPair: """ access_token: str + """Short-lived JWT access token for API requests.""" + refresh_token: str + """Long-lived token for obtaining new access tokens.""" + token_type: str = "bearer" + """Token type, typically "bearer" for JWT. Defaults to "bearer".""" + expires_at: datetime | None = None + """Expiration timestamp for access token, if available.""" @runtime_checkable diff --git a/packages/structum/src/structum/database/interfaces.py b/packages/structum/src/structum/database/interfaces.py index aef1d14b..243e3d71 100644 --- a/packages/structum/src/structum/database/interfaces.py +++ b/packages/structum/src/structum/database/interfaces.py @@ -56,13 +56,6 @@ class HealthCheckResult: """ Data class representing database health check results. - Attributes: - status (HealthStatus): Overall health status (HEALTHY, DEGRADED, UNHEALTHY). - message (str): Human-readable status description. - latency_ms (float | None): Query latency in milliseconds, if available. - details (dict[str, Any] | None): Additional diagnostic information - (e.g., active connections, pool statistics). - Example: Creating and using a health check result:: @@ -83,9 +76,16 @@ class HealthCheckResult: """ status: HealthStatus + """Overall health status (HEALTHY, DEGRADED, UNHEALTHY).""" + message: str + """Human-readable status description.""" + latency_ms: float | None = None + """Query latency in milliseconds, if available.""" + details: dict[str, Any] | None = None + """Additional diagnostic information (e.g., active connections, pool statistics).""" @runtime_checkable