sapium-commons 0.1.0__tar.gz

sapium_commons-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  commons:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src/ && ruff format --check src/
+      - name: Test
+        run: pytest tests/

sapium_commons-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sapium_commons-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.pyc

sapium_commons-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: sapium-commons
+Version: 0.1.0
+Summary: Sapium Commons — shared utilities for sapium services
+Requires-Dist: structlog
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

sapium_commons-0.1.0/README.md

@@ -0,0 +1,74 @@
+# sapium-commons
+
+Shared utilities for Sapium services. Used by [conduit](https://github.com/sapiumai/conduit) and [augur](https://github.com/sapiumai/augur).
+
+## Installation
+
+```bash
+pip install sapium-commons
+```
+
+## Contents
+
+### `sapium_commons.core.log`
+
+Structured logging via [structlog](https://www.structlog.org/). Provides namespace filtering, transaction ID binding, and a consistent log format across services.
+
+```python
+from sapium_commons.core.log import setup_logging, bind_transaction_id, get_logger
+
+setup_logging(
+    name=__name__,
+    log_level="INFO",
+    log_output="stdout",
+    log_output_type="json",
+    namespace="sapium_myservice",
+)
+
+log = get_logger(__name__)
+bind_transaction_id()  # generates and binds a UUID4
+log.info("service started")
+```
+
+### `sapium_commons.core.custom_exceptions`
+
+Typed exception hierarchy for consistent error handling.
+
+```python
+from sapium_commons.core.custom_exceptions import (
+    NotFoundError,
+    ValidationError,
+    ServiceError,
+    DatabaseError,
+)
+```
+
+### `sapium_commons.core.types`
+
+Common type aliases.
+
+```python
+from sapium_commons.core.types import JsonDict  # dict[str, Any]
+```
+
+### `sapium_commons.utils.datetime_utils`
+
+```python
+from sapium_commons.utils.datetime_utils import utcnow  # timezone-aware datetime
+```
+
+### `sapium_commons.utils.db_helper`
+
+```python
+from sapium_commons.utils.db_helper import make_postgres_url
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src/ && ruff format src/
+pytest tests/
+```
+
+Releases are published to PyPI automatically on `v*` tags via GitHub Actions.

sapium_commons-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "sapium-commons"
+version = "0.1.0"
+description = "Sapium Commons — shared utilities for sapium services"
+
+dependencies = [
+    "structlog",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "ruff"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sapium_commons"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

sapium_commons-0.1.0/src/sapium_commons/__init__.py

@@ -0,0 +1 @@
+"""Sapium Commons — shared utilities for sapium services."""

sapium_commons-0.1.0/src/sapium_commons/core/__init__.py

@@ -0,0 +1 @@
+"""Core utilities for sapium_commons."""

sapium_commons-0.1.0/src/sapium_commons/core/custom_exceptions.py

@@ -0,0 +1,110 @@
+"""Custom exceptions for sapium services, providing specific error handling for
+various failure scenarios.
+"""
+
+from typing import Optional
+
+
+class BaseCustomException(Exception):
+    """Base exception class for all custom exceptions."""
+
+    def __init__(self, message: str, detail: Optional[str] = None):
+        self.message = message
+        self.detail = detail
+        super().__init__(self.message)
+
+
+class DatabaseError(BaseCustomException):
+    """Raised when database operations fail."""
+
+    pass
+
+
+class ValidationError(BaseCustomException):
+    """Raised when data validation fails."""
+
+    pass
+
+
+class NotFoundError(BaseCustomException):
+    """Raised when a requested resource is not found."""
+
+    pass
+
+
+class DuplicateError(BaseCustomException):
+    """Raised when trying to create a duplicate resource."""
+
+    pass
+
+
+class FileError(BaseCustomException):
+    """Raised when file operations fail."""
+
+    pass
+
+
+class ServiceError(BaseCustomException):
+    """Raised when service layer operations fail."""
+
+    pass
+
+
+class ExternalServiceError(BaseCustomException):
+    """Raised when external service calls fail."""
+
+    pass
+
+
+class ConfigurationError(BaseCustomException):
+    """Raised when configuration values are missing or invalid."""
+
+    pass
+
+
+class SchedulerError(BaseCustomException):
+    """Raised when scheduler operations fail."""
+
+    pass
+
+
+class StorageError(BaseCustomException):
+    """Raised when storage operations fail."""
+
+    pass
+
+
+class UnauthorizedError(BaseCustomException):
+    """Raised when a request lacks valid credentials."""
+
+    pass
+
+
+class ForbiddenError(BaseCustomException):
+    """Raised when a request is understood but not permitted."""
+
+    pass
+
+
+class TooManyRequestsError(BaseCustomException):
+    """Raised when a rate limit is exceeded."""
+
+    pass
+
+
+class ConflictError(BaseCustomException):
+    """Raised when a resource already exists with conflicting state."""
+
+    pass
+
+
+class ArtifactError(BaseCustomException):
+    """Raised when model artifact loading or execution fails."""
+
+    pass
+
+
+class ConnectorError(BaseCustomException):
+    """Raised when FeatureSourceConnector operations fail."""
+
+    pass

sapium_commons-0.1.0/src/sapium_commons/core/log.py

@@ -0,0 +1,141 @@
+"""Structured logging helpers for sapium services.
+
+Provides `setup_logging`, namespace filtering, transaction ID binding, and
+structlog logger access. Has no dependency on sapium_augur or
+sapium_augur_console — either service imports from here.
+"""
+
+import contextvars
+import logging
+import sys
+import uuid
+from pathlib import Path
+
+import structlog
+from structlog import contextvars as structlog_contextvars
+
+
+class _NamespaceFilter(logging.Filter):
+    """Allow only log records whose name matches a namespace prefix."""
+
+    def __init__(self, prefix: str) -> None:
+        """Initialise with the namespace prefix to allow."""
+        super().__init__()
+        self.prefix = prefix
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return True when the record originates from the allowed namespace."""
+        return record.name == self.prefix or record.name.startswith(f"{self.prefix}.")
+
+
+def setup_logging(
+    name: str,
+    log_level: str,
+    log_output: str,
+    log_output_type: str,
+    namespace: str,
+) -> None:
+    """Configure structlog for the given service namespace.
+
+    Args:
+        name: Logger name passed by the caller (e.g. __name__).
+        log_level: Logging level string, e.g. "INFO".
+        log_output: Destination — "stdout", "file", or "db".
+        log_output_type: Renderer — "json" or "text".
+        namespace: Namespace prefix used by _NamespaceFilter.
+    """
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level=log_level)
+
+    for h in list(root_logger.handlers):
+        root_logger.removeHandler(h)
+
+    match log_output:
+        case "file":
+            log_dir = Path("logs")
+            log_dir.mkdir(parents=True, exist_ok=True)
+            handler: logging.Handler = logging.FileHandler(log_dir / f"{namespace}.log")
+        case "stdout" | _:
+            if log_output not in ("stdout",):
+                logging.warning(
+                    "Unsupported log_output %r — falling back to stdout", log_output
+                )
+            handler = logging.StreamHandler(sys.stdout)
+
+    if log_output_type == "json":
+        formatter = logging.Formatter("%(message)s")
+    else:
+        formatter = logging.Formatter(
+            "[%(asctime)s] - [%(levelname)s]: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+    handler.setLevel(level=log_level)
+    handler.setFormatter(formatter)
+    handler.addFilter(_NamespaceFilter(prefix=namespace))
+    root_logger.addHandler(handler)
+
+    logging.getLogger(name).propagate = True
+
+    base_processors = [
+        structlog_contextvars.merge_contextvars,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+
+    if log_output_type == "text":
+
+        def _message_only_renderer(logger, method_name, event_dict):
+            """Return only the event message string, discarding structured fields."""
+            message = event_dict.get("event")
+            if message is None:
+                message = event_dict.get("msg", "")
+            return str(message)
+
+        processors = base_processors + [_message_only_renderer]
+    else:
+        processors = base_processors + [structlog.processors.JSONRenderer()]
+
+    structlog.configure(
+        processors=processors,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=False,
+    )
+
+
+def bind_transaction_id(transaction_id: str | None = None) -> str:
+    """Bind a transaction_id into structlog contextvars for the current context.
+
+    Generates a UUID4 if no id is provided. Returns the bound transaction id.
+    """
+    if transaction_id is None:
+        transaction_id = str(uuid.uuid4())
+    structlog_contextvars.bind_contextvars(transaction_id=transaction_id)
+    _tx_ctx.set(transaction_id)
+    return transaction_id
+
+
+def clear_transaction_context() -> None:
+    """Clear all structlog contextvars for the current context."""
+    structlog_contextvars.clear_contextvars()
+    try:
+        _tx_ctx.set(None)
+    except Exception:
+        pass
+
+
+def get_current_transaction_id() -> str | None:
+    """Return the currently bound transaction id, or None."""
+    return _tx_ctx.get(None)
+
+
+def get_logger(name: str) -> structlog.BoundLogger:
+    """Return a structlog logger instance for the given name."""
+    return structlog.get_logger(name)
+
+
+_tx_ctx: contextvars.ContextVar = contextvars.ContextVar("transaction_id", default=None)

sapium_commons-0.1.0/src/sapium_commons/core/types.py

@@ -0,0 +1,5 @@
+"""Common type aliases shared across sapium_augur services."""
+
+from typing import Any
+
+JsonDict = dict[str, Any]

sapium_commons-0.1.0/src/sapium_commons/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers for sapium_commons."""

sapium_commons-0.1.0/src/sapium_commons/utils/datetime_utils.py

@@ -0,0 +1,8 @@
+"""UTC datetime utilities."""
+
+from datetime import datetime, timezone
+
+
+def utcnow() -> datetime:
+    """Return the current UTC datetime (timezone-aware)."""
+    return datetime.now(timezone.utc)

sapium_commons-0.1.0/src/sapium_commons/utils/db_helper.py

@@ -0,0 +1,8 @@
+"""Connection string builders for PostgreSQL."""
+
+from urllib.parse import quote_plus
+
+
+def make_postgres_url(host: str, port: int, user: str, password: str, db: str) -> str:
+    """Return a psycopg2-compatible PostgreSQL connection string."""
+    return f"postgresql+psycopg2://{quote_plus(user)}:{quote_plus(password)}@{host}:{port}/{db}"

sapium_commons-0.1.0/tests/unit/test_smoke.py

@@ -0,0 +1,31 @@
+"""Smoke tests for sapium_commons."""
+
+from sapium_commons.core.custom_exceptions import BaseCustomException
+from sapium_commons.core.types import JsonDict
+from sapium_commons.utils.datetime_utils import utcnow
+from sapium_commons.utils.db_helper import make_postgres_url
+
+
+def test_utcnow_is_aware() -> None:
+    """utcnow() returns a timezone-aware datetime."""
+    dt = utcnow()
+    assert dt.tzinfo is not None
+
+
+def test_make_postgres_url() -> None:
+    """make_postgres_url returns a valid psycopg2 connection string."""
+    url = make_postgres_url("localhost", 5432, "user", "pass", "db")
+    assert url == "postgresql+psycopg2://user:pass@localhost:5432/db"
+
+
+def test_json_dict_alias() -> None:
+    """JsonDict is a valid type alias for dict[str, Any]."""
+    d: JsonDict = {"key": "value"}
+    assert d["key"] == "value"
+
+
+def test_base_custom_exception() -> None:
+    """BaseCustomException stores message and detail."""
+    exc = BaseCustomException(message="test", detail="extra")
+    assert exc.message == "test"
+    assert exc.detail == "extra"