stacklink 0.1.0__py3-none-any.whl

stacklink/__init__.py

@@ -0,0 +1,16 @@
+"""stacklink — health checks, config validation, and structured logging for FastAPI."""
+
+from stacklink.config import Config, ConfigError, Field, StacklinkError
+from stacklink.health import HealthError, health
+from stacklink.logger import LoggerError, logger
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "Field",
+    "HealthError",
+    "LoggerError",
+    "StacklinkError",
+    "health",
+    "logger",
+]

stacklink/config.py

@@ -0,0 +1,162 @@
+"""Configuration loading from environment variables and .env files."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, cast, get_type_hints
+
+from dotenv import find_dotenv, load_dotenv
+
+# Sentinel to distinguish "no default" from None/False/0
+_MISSING: Any = object()  # Any: sentinel needs to be assignable anywhere
+
+_BOOL_TRUE = frozenset({"true", "1", "yes"})
+_BOOL_FALSE = frozenset({"false", "0", "no"})
+_COERCIBLE_TYPES: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "float",
+    bool: "boolean",
+}
+
+
+class StacklinkError(Exception):
+    """Base exception for all stacklink errors."""
+
+
+class ConfigError(StacklinkError):
+    """Raised when configuration loading or validation fails."""
+
+
+@dataclass(frozen=True, slots=True)
+class _FieldMeta:
+    """Internal metadata for a config field."""
+
+    required: bool
+    default: Any  # Any: default can be any type matching the field
+    secret: bool
+
+
+def Field(
+    *,
+    required: bool = False,
+    default: Any = _MISSING,  # Any: default can be any type matching the field
+    secret: bool = False,
+) -> Any:  # Any: return is assigned as a class-level default annotation
+    """Declare metadata for a config field."""
+    return _FieldMeta(required=required, default=default, secret=secret)
+
+
+class Config:
+    """Base class for typed configuration loaded from environment variables."""
+
+    def __init__(self) -> None:
+        """Load .env file and populate fields from environment variables."""
+        load_dotenv(find_dotenv(usecwd=True), override=True)
+        hints = get_type_hints(type(self))
+        for name, field_type in hints.items():
+            meta = _extract_meta(type(self), name)
+            env_var = name.upper()
+            raw = os.environ.get(env_var)
+            value = _resolve_value(name, env_var, raw, meta, field_type)
+            object.__setattr__(self, name, value)
+
+    def secret_field_names(self) -> frozenset[str]:
+        """Return names of all fields marked as secret."""
+        hints = get_type_hints(type(self))
+        return frozenset(
+            name for name in hints if _extract_meta(type(self), name).secret
+        )
+
+    def as_dict(self) -> dict[str, Any]:  # Any: field values can be any coercible type
+        """Return all fields as a dictionary, redacting secret values."""
+        hints = get_type_hints(type(self))
+        result: dict[str, Any] = {}
+        for name in hints:
+            meta = _extract_meta(type(self), name)
+            value = getattr(self, name)
+            result[name] = "***" if meta.secret else value
+        return result
+
+
+def _extract_meta(cls: type, name: str) -> _FieldMeta:
+    """Extract field metadata from a class attribute."""
+    raw = cls.__dict__.get(name, _MISSING)
+    if isinstance(raw, _FieldMeta):
+        return raw
+    return _FieldMeta(
+        required=False, default=raw if raw is not _MISSING else _MISSING, secret=False
+    )
+
+
+def _resolve_value(
+    name: str,
+    env_var: str,
+    raw: str | None,
+    meta: _FieldMeta,
+    field_type: type,
+) -> Any:  # Any: return type varies by field_type
+    """Resolve a field's value from env, default, or raise on missing required."""
+    if raw is not None:
+        return _coerce(name, env_var, raw, field_type, meta.secret)
+    if meta.required:
+        _raise_missing(name, env_var)
+    if meta.default is not _MISSING:
+        return meta.default
+    return None
+
+
+def _coerce(
+    name: str, env_var: str, raw: str, field_type: type, secret: bool
+) -> Any:  # Any: varies by field_type
+    """Coerce a raw string to the target type."""
+    if field_type is str:
+        return raw
+    if field_type is bool:
+        return _coerce_bool(name, env_var, raw, secret)
+    return _coerce_numeric(name, env_var, raw, field_type, secret)
+
+
+def _coerce_bool(name: str, env_var: str, raw: str, secret: bool) -> bool:
+    """Coerce a raw string to a boolean value."""
+    lower = raw.lower()
+    if lower in _BOOL_TRUE:
+        return True
+    if lower in _BOOL_FALSE:
+        return False
+    display = "***" if secret else repr(raw)
+    raise ConfigError(
+        f"Invalid boolean value for '{name}'.\n"
+        f"{env_var}={display} is not a recognized boolean.\n"
+        f"Use one of: true, false, 1, 0, yes, no."
+    ) from None
+
+
+def _coerce_numeric(
+    name: str,
+    env_var: str,
+    raw: str,
+    field_type: type,
+    secret: bool,
+) -> int | float:
+    """Coerce a raw string to int or float."""
+    try:
+        return cast(int | float, field_type(raw))
+    except (ValueError, TypeError):
+        display = "***" if secret else repr(raw)
+        type_name = _COERCIBLE_TYPES.get(field_type, field_type.__name__)
+        raise ConfigError(
+            f"Invalid {type_name} value for '{name}'.\n"
+            f"{env_var}={display} cannot be converted to {type_name}.\n"
+            f"Set {env_var} to a valid {type_name}."
+        ) from None
+
+
+def _raise_missing(name: str, env_var: str) -> None:
+    """Raise ConfigError for a missing required field."""
+    raise ConfigError(
+        f"Required config field '{name}' is missing.\n"
+        f"Environment variable {env_var} is not set.\n"
+        f"Set {env_var} in your .env file or environment."
+    ) from None

stacklink/health.py

@@ -0,0 +1,103 @@
+"""Health check endpoints for FastAPI applications."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from stacklink.config import Config, StacklinkError
+
+CheckFn = Callable[[], Awaitable[bool]]
+
+
+class HealthError(StacklinkError):
+    """Raised when the health module encounters an error."""
+
+
+class HealthRegistry:
+    """Registry for health check endpoints and custom readiness checks."""
+
+    def __init__(self) -> None:
+        """Initialize an empty health registry."""
+        self._checks: dict[str, CheckFn] = {}
+        self._start_time: float | None = None
+        self._service: str | None = None
+        self._env: str | None = None
+
+    def register(self, app: FastAPI, config: Config | None = None) -> None:
+        """Attach /healthz and /readyz health check endpoints to a FastAPI app."""
+        self._start_time = time.monotonic()
+        self._extract_config(config)
+        app.add_api_route("/healthz", self._healthz, methods=["GET"])
+        app.add_api_route("/readyz", self._readyz, methods=["GET"])
+
+    def add_check(self, name: str, fn: CheckFn) -> None:
+        """Register a custom async check function for readiness."""
+        self._checks[name] = fn
+
+    def _extract_config(self, config: Config | None) -> None:
+        """Pull service and env from config if available."""
+        if config is None:
+            return
+        service = getattr(config, "service", None)
+        env = getattr(config, "env", None)
+        if isinstance(service, str):
+            self._service = service
+        if isinstance(env, str):
+            self._env = env
+
+    def _uptime(self) -> float:
+        """Calculate seconds since register() was called."""
+        if self._start_time is None:
+            return 0.0
+        return round(time.monotonic() - self._start_time, 1)
+
+    def _base_response(self) -> dict[str, object]:
+        """Build the common response fields."""
+        data: dict[str, object] = {}
+        if self._service is not None:
+            data["service"] = self._service
+        if self._env is not None:
+            data["env"] = self._env
+        data["uptime_seconds"] = self._uptime()
+        return data
+
+    async def _healthz(self) -> JSONResponse:
+        """Handle GET /healthz -- liveness check."""
+        data = self._base_response()
+        data["status"] = "ok"
+        return JSONResponse(content=data, status_code=200)
+
+    async def _readyz(self) -> JSONResponse:
+        """Handle GET /readyz -- readiness check."""
+        check_results = await self._run_checks()
+        all_ok = all(v == "ok" for v in check_results.values())
+        status = "ok" if all_ok else "degraded"
+        status_code = 200 if all_ok else 503
+
+        data = self._base_response()
+        data["status"] = status
+        data["checks"] = check_results
+        return JSONResponse(content=data, status_code=status_code)
+
+    async def _run_checks(self) -> dict[str, str]:
+        """Execute all registered checks and collect results."""
+        results: dict[str, str] = {}
+        for name, fn in self._checks.items():
+            results[name] = await _execute_check(fn)
+        return results
+
+
+async def _execute_check(fn: CheckFn) -> str:
+    """Run a single check function, returning 'ok' or 'failing'."""
+    try:
+        result = await fn()
+        return "ok" if result else "failing"
+    except Exception:
+        return "failing"
+
+
+health = HealthRegistry()

stacklink/logger.py

@@ -0,0 +1,168 @@
+"""Structured JSON logging with optional config-based tagging."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+from stacklink.config import Config, StacklinkError
+
+
+class LoggerError(StacklinkError):
+    """Raised when the logger encounters an error."""
+
+
+class _LoggerState:
+    """Mutable state shared between the logger and its formatter."""
+
+    def __init__(self) -> None:
+        """Initialize empty logger state."""
+        self.service: str | None = None
+        self.env: str | None = None
+        self.secret_names: frozenset[str] = frozenset()
+
+
+class _JsonFormatter(logging.Formatter):
+    """Formats log records as single-line JSON objects."""
+
+    def __init__(self, logger_state: _LoggerState) -> None:
+        """Bind formatter to shared logger state."""
+        super().__init__()
+        self._state = logger_state
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Serialize a log record to a JSON string."""
+        entry = _build_entry(record, self._state)
+        return json.dumps(entry, default=str)
+
+
+def _build_entry(
+    record: logging.LogRecord,
+    state: _LoggerState,
+) -> dict[str, Any]:  # Any: log values can be any JSON-serializable type
+    """Assemble the JSON dict for one log line."""
+    entry: dict[str, Any] = {  # Any: mixed value types in log output
+        "timestamp": _utc_timestamp(),
+        "level": record.levelname,
+    }
+    if state.service is not None:
+        entry["service"] = state.service
+    if state.env is not None:
+        entry["env"] = state.env
+    entry["message"] = record.getMessage()
+    extras: dict[str, Any] = getattr(
+        record, "_extra_kwargs", {}
+    )  # Any: user-supplied kwargs
+    entry.update(_filter_secrets(extras, state.secret_names))
+    return entry
+
+
+def _utc_timestamp() -> str:
+    """Return the current UTC time in ISO 8601 format."""
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def _filter_secrets(
+    data: dict[str, Any],  # Any: user-supplied kwargs
+    secret_names: frozenset[str],
+) -> dict[str, Any]:  # Any: filtered kwargs
+    """Remove any keys whose names match secret config fields."""
+    return {k: v for k, v in data.items() if k not in secret_names}
+
+
+def _get_log_level() -> int:
+    """Read LOG_LEVEL from env and map to a logging constant."""
+    level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    level_map: dict[str, int] = {
+        "DEBUG": logging.DEBUG,
+        "INFO": logging.INFO,
+        "WARNING": logging.WARNING,
+        "ERROR": logging.ERROR,
+    }
+    level = level_map.get(level_name)
+    if level is None:
+        raise LoggerError(
+            f"Invalid LOG_LEVEL '{level_name}'.\n"
+            f"LOG_LEVEL must be one of: DEBUG, INFO, WARNING, ERROR.\n"
+            f"Set LOG_LEVEL to a valid level or remove it to default to INFO."
+        ) from None
+    return level
+
+
+class StacklinkLogger:
+    """Singleton structured JSON logger for stacklink."""
+
+    def __init__(self) -> None:
+        """Set up the underlying Python logger with a JSON handler."""
+        self._state = _LoggerState()
+        self._logger = logging.getLogger("stacklink")
+        self._logger.handlers.clear()
+        self._logger.propagate = False
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(_JsonFormatter(self._state))
+        self._logger.addHandler(handler)
+        self._logger.setLevel(_get_log_level())
+
+    def configure(self, config: Config) -> None:
+        """Attach service and env from a Config instance to all future log lines."""
+        self._state.secret_names = config.secret_field_names()
+        service = getattr(config, "service", None)
+        env = getattr(config, "env", None)
+        if isinstance(service, str):
+            self._state.service = service
+        if isinstance(env, str):
+            self._state.env = env
+
+    def info(
+        self, message: str, **kwargs: Any
+    ) -> None:  # Any: arbitrary structured data
+        """Log a message at INFO level with optional structured fields."""
+        self._log(logging.INFO, message, kwargs)
+
+    def warning(
+        self, message: str, **kwargs: Any
+    ) -> None:  # Any: arbitrary structured data
+        """Log a message at WARNING level with optional structured fields."""
+        self._log(logging.WARNING, message, kwargs)
+
+    def error(
+        self, message: str, **kwargs: Any
+    ) -> None:  # Any: arbitrary structured data
+        """Log a message at ERROR level with optional structured fields."""
+        self._log(logging.ERROR, message, kwargs)
+
+    def debug(
+        self, message: str, **kwargs: Any
+    ) -> None:  # Any: arbitrary structured data
+        """Log a message at DEBUG level with optional structured fields."""
+        self._log(logging.DEBUG, message, kwargs)
+
+    def _log(
+        self,
+        level: int,
+        message: str,
+        extra_kwargs: dict[str, Any],  # Any: user-supplied structured data
+    ) -> None:
+        """Dispatch a log record with extra kwargs attached."""
+        self._logger.setLevel(_get_log_level())
+        if not self._logger.isEnabledFor(level):
+            return
+        record = self._logger.makeRecord(
+            name="stacklink",
+            level=level,
+            fn="",
+            lno=0,
+            msg=message,
+            args=(),
+            exc_info=None,
+        )
+        record._extra_kwargs = extra_kwargs  # dynamic attr for formatter
+        self._logger.handle(record)
+
+
+logger = StacklinkLogger()

stacklink-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: stacklink
+Version: 0.1.0
+Summary: Health checks, config validation, and structured logging for FastAPI
+Project-URL: Homepage, https://github.com/dressupdarling/stacklink
+Project-URL: Repository, https://github.com/dressupdarling/stacklink
+Project-URL: Issues, https://github.com/dressupdarling/stacklink/issues
+Author-email: Yevgeny <yevgenyokun2@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: config,fastapi,health-check,logging,structured-logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stacklink
+
+Health checks, config validation, and structured logging for FastAPI — in three lines of code.
+
+Built for solo devs and small teams who want production-grade infrastructure without the setup overhead.
+
+## Install
+
+```bash
+pip install stacklink
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from stacklink import Config, Field, health, logger
+
+app = FastAPI()
+
+class AppConfig(Config):
+    env: str = Field(required=True)
+    service: str = Field(default="my-api")
+    port: int = Field(default=8080)
+    db_url: str = Field(required=True, secret=True)
+
+config = AppConfig()
+
+logger.configure(config)
+logger.info("server starting", port=config.port)
+
+health.register(app, config=config)
+```
+
+That's it. You now have:
+
+- Validated, typed config from `.env` and environment variables
+- Structured JSON logging to stdout
+- `/healthz` and `/readyz` endpoints on your FastAPI app
+
+## Modules
+
+### Config
+
+Reads `.env` files and environment variables. Validates types. Fails loudly at startup if anything is wrong. Redacts secrets from output.
+
+```python
+from stacklink import Config, Field
+
+class AppConfig(Config):
+    env: str = Field(required=True)
+    port: int = Field(default=8080)
+    db_url: str = Field(required=True, secret=True)
+
+config = AppConfig()
+config.as_dict()  # {"env": "production", "port": 8080, "db_url": "***"}
+```
+
+Supported types: `str`, `int`, `float`, `bool`. Bool coerces from `true/false/1/0/yes/no`.
+
+### Logger
+
+Structured JSON logging. Every line is machine-parseable. Auto-tags with service name and environment when configured.
+
+```python
+from stacklink import logger
+
+logger.info("request handled", method="GET", path="/users", status=200)
+# {"timestamp": "...", "level": "INFO", "message": "request handled", "method": "GET", "path": "/users", "status": 200}
+```
+
+Set `LOG_LEVEL` env var to control filtering (default: `INFO`).
+
+### Health
+
+Registers `/healthz` (liveness) and `/readyz` (readiness) endpoints on your FastAPI app.
+
+```python
+from stacklink import health
+
+health.register(app, config=config)
+
+async def check_database():
+    try:
+        await db.execute("SELECT 1")
+        return True
+    except Exception:
+        return False
+
+health.add_check("database", check_database)
+```
+
+`/healthz` always returns `200`. `/readyz` returns `200` when all checks pass, `503` when any check fails.
+
+## Documentation
+
+- [Config](docs/config.md)
+- [Logger](docs/logger.md)
+- [Health](docs/health.md)
+
+## Requirements
+
+- Python 3.10+
+- FastAPI 0.100+
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

stacklink-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+stacklink/__init__.py,sha256=tliqTCFN_2mB64vG3h9PF_0sHiqEeO6KtkTUGwoUxw4,410
+stacklink/config.py,sha256=EcyBvqftADYsCxoME-N5unAiMPtkRYDNoF4CiQDe_Vc,5272
+stacklink/health.py,sha256=KXkO6gnXMPCF4tdWLBuNmHWwK1A_gQrk7pFI2BNl6Fw,3532
+stacklink/logger.py,sha256=qIW91YGf7D9yjr5A2nnn7Pj3FNbFZ4Qdeq81mjx-W4c,5643
+stacklink-0.1.0.dist-info/METADATA,sha256=FDokkwrbnQ3lTqfbSeouLEIIQEaRDu5padXBJA6PpzM,3980
+stacklink-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stacklink-0.1.0.dist-info/licenses/LICENSE,sha256=6buXR5E8cfifGgwqI3PACDnT--AC0obp0c_VdsQ15ZI,1070
+stacklink-0.1.0.dist-info/RECORD,,

stacklink-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stacklink-0.1.0.dist-info/licenses/LICENSE

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