perfact-api-base 0.6__tar.gz

perfact_api_base-0.6/.gitea/workflows/check.yml

@@ -0,0 +1,26 @@
+name: Tox tests
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install tox tox-gh-actions
+    - name: Test with tox
+      run: tox

perfact_api_base-0.6/.gitea/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "[0-9]*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

perfact_api_base-0.6/.gitignore

@@ -0,0 +1,7 @@
+tags*
+__pycache__
+*.egg-info
+.coverage
+.tox
+build
+.claude

perfact_api_base-0.6/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true
+    }
+}

perfact_api_base-0.6/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: perfact-api-base
+Version: 0.6
+Summary: PerFact API - base package for common infrastructure
+Author-email: Viktor Dick <viktor.dick@perfact.de>
+License: GPL-2.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psycopg[binary]
+Requires-Dist: sqlalchemy
+Requires-Dist: pydantic-settings
+
+# perfact-api-base
+
+Base package for PerFact API common infrastructure. Part of the `perfact.api.base` namespace.
+
+## What it provides
+
+### `Base`
+
+Declarative base for all ORM table mappings. Subclasses automatically get:
+
+- `id` — `BigInteger` primary key
+- `modtime` — `DateTime` with timezone, defaults to `now()`
+- `author` — set from the DB session user via `db_username()`
+- Column names are automatically prefixed with the table name (e.g. a field `name` on `AppUser` becomes the DB column `appuser_name`)
+- `__tablename__` is derived from the class name in lowercase if not set explicitly
+
+### `View`
+
+Separate declarative base for SQL view definitions. Views are not created as tables during schema generation. Columns must be declared with explicit names matching the view definition.
+
+### Re-exports
+
+`ForeignKey`, `relationship`, `Mapped`, `mapped_column` are re-exported so model packages only need to import from this module.
+
+## Usage
+
+```python
+from perfact.api.base.model import Base, ForeignKey, Mapped, mapped_column, relationship
+
+class MyEntity(Base):
+    name: Mapped[str]
+    parent_id: Mapped[int | None] = mapped_column(ForeignKey("myentity.myentity_id"))
+```
+
+## Dependencies
+
+- `sqlalchemy`
+- `psycopg[c]`
+- `pydantic-settings`
+
+## Maintainers
+
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_base-0.6/README.md

@@ -0,0 +1,44 @@
+# perfact-api-base
+
+Base package for PerFact API common infrastructure. Part of the `perfact.api.base` namespace.
+
+## What it provides
+
+### `Base`
+
+Declarative base for all ORM table mappings. Subclasses automatically get:
+
+- `id` — `BigInteger` primary key
+- `modtime` — `DateTime` with timezone, defaults to `now()`
+- `author` — set from the DB session user via `db_username()`
+- Column names are automatically prefixed with the table name (e.g. a field `name` on `AppUser` becomes the DB column `appuser_name`)
+- `__tablename__` is derived from the class name in lowercase if not set explicitly
+
+### `View`
+
+Separate declarative base for SQL view definitions. Views are not created as tables during schema generation. Columns must be declared with explicit names matching the view definition.
+
+### Re-exports
+
+`ForeignKey`, `relationship`, `Mapped`, `mapped_column` are re-exported so model packages only need to import from this module.
+
+## Usage
+
+```python
+from perfact.api.base.model import Base, ForeignKey, Mapped, mapped_column, relationship
+
+class MyEntity(Base):
+    name: Mapped[str]
+    parent_id: Mapped[int | None] = mapped_column(ForeignKey("myentity.myentity_id"))
+```
+
+## Dependencies
+
+- `sqlalchemy`
+- `psycopg[c]`
+- `pydantic-settings`
+
+## Maintainers
+
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_base-0.6/bandit.yml

@@ -0,0 +1,2 @@
+assert_used:
+  skips: ["*/test_*.py"]

perfact_api_base-0.6/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.2", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perfact-api-base"
+authors = [
+    {name="Viktor Dick", email="viktor.dick@perfact.de"},
+]
+description = "PerFact API - base package for common infrastructure"
+readme = "README.md"
+license = {text = "GPL-2.0-or-later"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: SQL",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "psycopg[binary]",
+    "sqlalchemy",
+    "pydantic-settings",
+]
+dynamic = ["version"]
+requires-python = ">=3.10"
+
+[project.scripts]
+
+[tool.distutils.bdist_wheel]
+universal = 1
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+
+[tool.ruff]
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

perfact_api_base-0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perfact_api_base-0.6/src/perfact/api/base/__init__.py

@@ -0,0 +1,17 @@
+from .authinfo import AuthInfo
+from .model import Base, PydanticBase, View
+from .visibility import (
+    VisibilityAwareModel,
+    VisibilityPolicy,
+    VisibilityPolicyRegistry,
+)
+
+__all__ = [
+    "AuthInfo",
+    "Base",
+    "PydanticBase",
+    "View",
+    "VisibilityAwareModel",
+    "VisibilityPolicy",
+    "VisibilityPolicyRegistry",
+]

perfact_api_base-0.6/src/perfact/api/base/authinfo.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AuthInfo:
+    name: Optional[str]
+    roles: list[str]
+    appstc: Optional[int]
+
+    @staticmethod
+    def get_unauthorized_authinfo() -> AuthInfo:
+        """
+        Returns a predefined AuthInfo for unauthorized requests.
+        """
+        return AuthInfo(None, [], None)

perfact_api_base-0.6/src/perfact/api/base/model.py

@@ -0,0 +1,65 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import BigInteger, DateTime, ForeignKey, String, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+# Re-export for easier use
+ForeignKey = ForeignKey
+relationship = relationship
+
+
+class Base(DeclarativeBase):
+    """
+    Base class for table mappings. Allows declaring fields without their table prefix,
+    the subclass hook will automatically rewrite them.
+    """
+
+    type_annotation_map = {str: String(), int: BigInteger()}
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    modtime: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    author: Mapped[str | None] = mapped_column(server_default=func.db_username())
+
+    def __init_subclass__(cls, **kw):
+        """
+        Automatically add __tablename__ and prefix mapped columns with table name
+        """
+        # 1. Ensure tablename exists before mapping
+        if "__tablename__" not in cls.__dict__:
+            cls.__tablename__ = cls.__name__.lower()
+
+        # 2. Let SQLAlchemy build the mapper, table, columns, etc.
+        super().__init_subclass__(**kw)
+
+        # 3. Now we have cls.__table__ and real Column objects. Adjust these so they
+        # map to the prefixed column names on the database
+        if hasattr(cls, "__table__"):
+            prefix = cls.__tablename__ + "_"
+
+            for col in cls.__table__.columns:
+                # Only touch columns that still use their key as name
+                # (i.e., no explicit name was given)
+                if col.name == col.key:
+                    new_name = prefix + col.key
+                    col.name = new_name
+                    col.key = new_name  # keep ORM key in sync
+
+
+class View(DeclarativeBase):
+    """
+    Separate base for view definitions, so they are not created as tables but
+    can be used like tables
+    """
+
+    type_annotation_map = {str: String(), int: BigInteger()}
+
+
+class PydanticBase(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    author: str | None
+    modtime: datetime

perfact_api_base-0.6/src/perfact/api/base/visibility.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from sqlalchemy.sql.elements import ColumnElement
+
+from .authinfo import AuthInfo
+
+
+class VisibilityAwareModel:
+    """Marker mixin; signals that a model has an associated VisibilityPolicy."""
+
+
+class VisibilityPolicy(ABC):
+    """Row-level visibility rule; subclasses must set model and implement filter()."""
+
+    model: ClassVar[type]
+
+    @abstractmethod
+    def filter(self, auth: AuthInfo) -> ColumnElement[bool]: ...
+
+
+class VisibilityPolicyRegistry:
+    """Model-to-policy map; register() skips if already set, override() always wins."""
+
+    def __init__(self) -> None:
+        self._policies: dict[type, VisibilityPolicy] = {}
+
+    def register(self, model: type, policy_cls: type[VisibilityPolicy]) -> None:
+        if model not in self._policies:
+            self._policies[model] = policy_cls()
+
+    def override(self, model: type, policy_cls: type[VisibilityPolicy]) -> None:
+        self._policies[model] = policy_cls()
+
+    def get(self, model: type) -> VisibilityPolicy:
+        """Raises KeyError if no policy is registered for model."""
+        return self._policies[model]

perfact_api_base-0.6/src/perfact_api_base.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: perfact-api-base
+Version: 0.6
+Summary: PerFact API - base package for common infrastructure
+Author-email: Viktor Dick <viktor.dick@perfact.de>
+License: GPL-2.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psycopg[binary]
+Requires-Dist: sqlalchemy
+Requires-Dist: pydantic-settings
+
+# perfact-api-base
+
+Base package for PerFact API common infrastructure. Part of the `perfact.api.base` namespace.
+
+## What it provides
+
+### `Base`
+
+Declarative base for all ORM table mappings. Subclasses automatically get:
+
+- `id` — `BigInteger` primary key
+- `modtime` — `DateTime` with timezone, defaults to `now()`
+- `author` — set from the DB session user via `db_username()`
+- Column names are automatically prefixed with the table name (e.g. a field `name` on `AppUser` becomes the DB column `appuser_name`)
+- `__tablename__` is derived from the class name in lowercase if not set explicitly
+
+### `View`
+
+Separate declarative base for SQL view definitions. Views are not created as tables during schema generation. Columns must be declared with explicit names matching the view definition.
+
+### Re-exports
+
+`ForeignKey`, `relationship`, `Mapped`, `mapped_column` are re-exported so model packages only need to import from this module.
+
+## Usage
+
+```python
+from perfact.api.base.model import Base, ForeignKey, Mapped, mapped_column, relationship
+
+class MyEntity(Base):
+    name: Mapped[str]
+    parent_id: Mapped[int | None] = mapped_column(ForeignKey("myentity.myentity_id"))
+```
+
+## Dependencies
+
+- `sqlalchemy`
+- `psycopg[c]`
+- `pydantic-settings`
+
+## Maintainers
+
+- Viktor Dick <viktor.dick@perfact.de>
+- Alexander Rolfes <alexander.rolfes@perfact.de>

perfact_api_base-0.6/src/perfact_api_base.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+.gitignore
+README.md
+bandit.yml
+pyproject.toml
+tox.ini
+.gitea/workflows/check.yml
+.gitea/workflows/publish.yml
+.vscode/settings.json
+src/perfact/api/base/__init__.py
+src/perfact/api/base/authinfo.py
+src/perfact/api/base/model.py
+src/perfact/api/base/py.typed
+src/perfact/api/base/visibility.py
+src/perfact_api_base.egg-info/PKG-INFO
+src/perfact_api_base.egg-info/SOURCES.txt
+src/perfact_api_base.egg-info/dependency_links.txt
+src/perfact_api_base.egg-info/requires.txt
+src/perfact_api_base.egg-info/top_level.txt
+tests/test_visibility_policy.py

perfact_api_base-0.6/src/perfact_api_base.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

perfact_api_base-0.6/src/perfact_api_base.egg-info/requires.txt

@@ -0,0 +1,3 @@
+psycopg[binary]
+sqlalchemy
+pydantic-settings

perfact_api_base-0.6/src/perfact_api_base.egg-info/top_level.txt

@@ -0,0 +1 @@
+perfact

perfact_api_base-0.6/tests/test_visibility_policy.py

@@ -0,0 +1,86 @@
+import pytest
+from sqlalchemy.orm import Mapped
+from sqlalchemy.sql.elements import ColumnElement
+
+from perfact.api.base import (
+    AuthInfo,
+    VisibilityAwareModel,
+    VisibilityPolicy,
+    VisibilityPolicyRegistry,
+)
+from perfact.api.base.model import Base
+
+
+class ModelA(Base, VisibilityAwareModel):
+    __tablename__ = "model_a"
+    name: Mapped[str]
+
+
+class ModelB(Base, VisibilityAwareModel):
+    __tablename__ = "model_b"
+    name: Mapped[str]
+
+
+class PolicyForA(VisibilityPolicy):
+    model = ModelA
+
+    def filter(self, auth: AuthInfo) -> ColumnElement[bool]:
+        return ModelA.id > 0
+
+
+class PolicyForAOverride(VisibilityPolicy):
+    model = ModelA
+
+    def filter(self, auth: AuthInfo) -> ColumnElement[bool]:
+        return ModelA.id > 1
+
+
+def test_register_sets_policy() -> None:
+    registry = VisibilityPolicyRegistry()
+    registry.register(ModelA, PolicyForA)
+    assert isinstance(registry.get(ModelA), PolicyForA)
+
+
+def test_register_does_not_overwrite_existing() -> None:
+    registry = VisibilityPolicyRegistry()
+    registry.register(ModelA, PolicyForA)
+    registry.register(ModelA, PolicyForAOverride)
+    assert isinstance(registry.get(ModelA), PolicyForA)
+
+
+def test_override_sets_policy() -> None:
+    registry = VisibilityPolicyRegistry()
+    registry.override(ModelA, PolicyForA)
+    assert isinstance(registry.get(ModelA), PolicyForA)
+
+
+def test_override_replaces_existing() -> None:
+    registry = VisibilityPolicyRegistry()
+    registry.register(ModelA, PolicyForA)
+    registry.override(ModelA, PolicyForAOverride)
+    assert isinstance(registry.get(ModelA), PolicyForAOverride)
+
+
+def test_second_override_wins() -> None:
+    registry = VisibilityPolicyRegistry()
+    registry.override(ModelA, PolicyForA)
+    registry.override(ModelA, PolicyForAOverride)
+    assert isinstance(registry.get(ModelA), PolicyForAOverride)
+
+
+def test_registry_get_raises_for_unknown_model() -> None:
+    registry = VisibilityPolicyRegistry()
+    with pytest.raises(KeyError):
+        registry.get(ModelB)
+
+
+def test_auth_info_dataclass() -> None:
+    auth = AuthInfo(name="alice", roles=["Admin"], appstc=42)
+    assert auth.name == "alice"
+    assert auth.roles == ["Admin"]
+    assert auth.appstc == 42
+
+
+def test_auth_info_optional_appstc() -> None:
+    auth = AuthInfo(name="bob", roles=[], appstc=None)
+    assert auth.appstc is None

perfact_api_base-0.6/tox.ini

@@ -0,0 +1,24 @@
+[tox]
+envlist = py3
+isolated_build = true
+
+[pytest]
+
+[testenv]
+deps =
+    ruff
+    pytest
+    coverage
+    psycopg[binary]
+    pytest-postgresql
+    pytest-cov
+    pytest-typing
+    bandit
+    mypy
+
+commands =
+    ruff format --check
+    ruff check
+    bandit --configfile bandit.yml -r src
+    mypy src
+    # pytest --doctest-modules --cov-branch --cov=src --cov-report=term-missing {posargs:src}