perfact-dbutils 1.7.0__tar.gz

perfact_dbutils-1.7.0/.gitea/workflows/check.yml

@@ -0,0 +1,53 @@
+name: Build Package
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request: {}
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        target: ['jammy', 'bookworm', 'trixie']
+    runs-on: perfact-build-${{ matrix.target }}
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v3
+    - name: Change owner of build output Folder
+      run: sudo chown build:build /workspace/DebianPackages/ && echo OK!
+
+    - name: Update NMU changelog
+      run: |
+        echo Setting environment Variables
+        export DEBFULLNAME=${{ github.actor }}
+        echo Debian Fullname: $DEBFULLNAME
+        export DEBEMAIL=${{ github.actor }}@perfact.de
+        echo Debian Email: $DEBEMAIL
+        debchange --nmu Automated build on commit: ${{ gitea.sha }}
+
+    - name: Update package sources
+      run: sudo apt update || true
+
+    - name: Install build dependencies
+      run: sudo apt build-dep -y .
+
+    - name: Build
+      run: dpkg-buildpackage
+
+    - name: Collect result files
+      run: |
+        rm -rf /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        mkdir -p /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}
+        cp /workspace/DebianPackages/*.buildinfo /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        cp /workspace/DebianPackages/*.changes /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        cp /workspace/DebianPackages/*.deb /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        cp /workspace/DebianPackages/*.dsc /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        cp /workspace/DebianPackages/*.tar.xz /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+
+    - name: Output the result as artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{ matrix.target }}
+        path: /workspace/outputs/${{ gitea.repository }}/${{ gitea.ref_name }}/${{ matrix.target }}/
+        overwrite: true

perfact_dbutils-1.7.0/.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_dbutils-1.7.0/.gitignore

@@ -0,0 +1,23 @@
+*.pyc
+*.swp
+perfact_dbutils.egg-info
+venv*
+doc/source/api
+.tox
+.coverage
+__pycache__
+build
+dist
+.temp-venv
+.wheels
+debian/python3-perfact-dbutils
+debian/*.debhelper
+debian/*.debhelper.log
+debian/debhelper-build-stamp
+debian/files
+debian/*.substvars
+tags
+tags.lock
+tags.temp
+.pybuild
+*.orig

perfact_dbutils-1.7.0/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Run all checks (lint, security, tests, types, docs)
+tox
+
+# Individual checks
+ruff check perfact              # Lint
+ruff format --check perfact     # Format check
+ruff format perfact             # Auto-format
+mypy perfact                    # Type check
+bandit --configfile bandit.yaml -r perfact  # Security scan
+
+# Tests (requires a running PostgreSQL instance)
+pytest --doctest-modules --cov-branch --cov=perfact --cov-fail-under=100 --cov-report=term-missing
+
+# Run a single test file
+pytest perfact/dbutils/tests/test_crud.py
+
+# Run a single test by name
+pytest -k "test_create"
+```
+
+**100% code coverage is enforced** — adding code without tests will fail the test run.
+
+## Architecture
+
+The library (`perfact/dbutils/`) provides PostgreSQL database utilities usable from both plain Python and Zope environments.
+
+### Module Overview
+
+- **`api.py`** — Core type definitions and context objects. `Context` is the central object passed through the library: it bundles a database connection (`conn`), a `User`, an `LCC` config, and optional hooks. `User` carries role/permission info. Protocol types (`CodedHook`, `MayHook`, `CodedHooksResolver`, `SelfilterGenerator`) define the hook interfaces used by `lcc.py`.
+
+- **`conn.py`** — Database connection wrappers. `Connection` wraps a psycopg2 connection; `ZRDBConnectionWrapper` wraps Zope ZRDB connections. Both implement the `Executor` protocol exposing a unified `execute()` method. Query results are returned as `Results` dataclass instances with `.dicts()` and `.rows()` helpers.
+
+- **`crud.py`** — CRUD operations (`create`, `read`, `update`, `delete`) built on parameterized SQL via psycopg2's `sql` module. `update()` has an optional audit mode that writes `author`/`modtime` fields. All query construction is internal; callers pass table names, column dicts, and filter conditions.
+
+- **`lcc.py`** — Lifecycle/state transition management. `perform_transition()` runs a state change with pre/post hooks resolved via `collect_hooks()`. Side effects are loaded from the database. Transitions are logged to `*lch` tables. `transition_with_hooks()` is the main entry point for callers.
+
+- **`schemainfo.py`** — Schema introspection. `get_columns()` queries `information_schema` to list columns for a given table.
+
+- **`conn.py` (`wrap_zrdbconn_sqasession`)** — Also exposes a SQLAlchemy `Session` wrapper. SQLAlchemy is an optional dependency; importing the module succeeds without it, but calling `wrap_zrdbconn_sqasession()` raises `ImportError` if SQLAlchemy is not installed.
+
+### Key Dependency Flow
+
+```
+Callers → Context (api.py)
+            ├── conn.py   (Executor / Connection / ZRDBConnectionWrapper)
+            ├── crud.py   (uses conn.execute internally)
+            └── lcc.py    (uses crud + conn, resolves hooks from api.py protocols)
+```
+
+### Testing
+
+Tests live in `perfact/dbutils/tests/`. Integration tests use `pytest-postgresql` to spin up a real PostgreSQL instance via fixtures in `conftest.py`. There are no mocked database tests — all DB tests run against a real Postgres connection.

perfact_dbutils-1.7.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: perfact-dbutils
+Version: 1.7.0
+Summary: Basic tools for interacting with the database
+Author: Viktor Dick
+Author-email: Viktor Dick <viktor.dick@perfact.de>, Alexander Rolfes <alexander.rolfes@perfact.de>, Ján Jockusch <jan.jockusch@perfact.de>
+License: GPL-2.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: psycopg2
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy; extra == "sqlalchemy"
+
+# Basic tools for interacting with the database
+
+This module provides tools for interacting with a database connection that are
+usable both from Zope and other modules.
+
+As a first step, it has a Connection class that provides a unified execute
+method as well as a wrapper that can be used to pass a ZRDBConnection from Zope
+to obtain a similar class. Future increments will include CRUD functions for
+DB-Utils compatible database interactions.
+
+# Implement and run tests
+
+If you add new functions place your tests below `perfact/dbutils/tests`.
+Implement your test using `pytest`.
+
+You may have to install postgres if not already installed:
+`sudo apt install postgresql-<version>`
+
+Now you can run your tests by running `tox`. All tests need to succeed and your
+tests need to cover 100% of the code. Tox will tell you which lines are
+missing.

perfact_dbutils-1.7.0/README.md

@@ -0,0 +1,21 @@
+# Basic tools for interacting with the database
+
+This module provides tools for interacting with a database connection that are
+usable both from Zope and other modules.
+
+As a first step, it has a Connection class that provides a unified execute
+method as well as a wrapper that can be used to pass a ZRDBConnection from Zope
+to obtain a similar class. Future increments will include CRUD functions for
+DB-Utils compatible database interactions.
+
+# Implement and run tests
+
+If you add new functions place your tests below `perfact/dbutils/tests`.
+Implement your test using `pytest`.
+
+You may have to install postgres if not already installed:
+`sudo apt install postgresql-<version>`
+
+Now you can run your tests by running `tox`. All tests need to succeed and your
+tests need to cover 100% of the code. Tox will tell you which lines are
+missing.

perfact_dbutils-1.7.0/bandit.yaml

@@ -0,0 +1,3 @@
+# FILE: bandit.yaml
+assert_used:
+  skips: ['*_test.py', '*test_*.py']

perfact_dbutils-1.7.0/debian/changelog

@@ -0,0 +1,89 @@
+python-perfact-dbutils (1.7.0) unstable; urgency=medium
+
+  [ Viktor Dick ]
+  * Add workflow to publish to pypi
+
+  [ Alexander Rolfes ]
+  * Add wrapper for sqlalchemy session
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Tue, 12 May 2026 08:39:41 +0200
+
+python-perfact-dbutils (1.6.0) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Add generic loader function load_records with advanced options like join, aliasing
+    and automatic addition of lookups for id cols if desired
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Mon, 23 Mar 2026 11:17:18 +0100
+
+python-perfact-dbutils (1.5.0) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Make selfilter_generator param optional for context object
+
+  [ Viktor Dick ]
+  * Use ruff
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Wed, 11 Mar 2026 11:17:59 +0100
+
+python-perfact-dbutils (1.4.0) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Extend Context class with selfilter_generator param
+
+  [ Alexander Rolfes ]
+  * Added marker py.typed to mark module dbutils as typed
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Fri, 06 Mar 2026 11:17:46 +0100
+
+python-perfact-dbutils (1.3.0) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Add lcc transitions functions and tests
+  * Add allowedclasses module
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Thu, 26 Feb 2026 14:17:30 +0100
+
+python-perfact-dbutils (1.2) unstable; urgency=medium
+
+  [ Alexander Rolfes ]
+  * Fix build for jammy not containing any files
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Wed, 18 Feb 2026 07:07:04 +0100
+
+python-perfact-dbutils (1.1) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Move generated documentation into filesystem. Docs will be found in
+    /usr/share/doc/python3-perfact-dbutils/
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Fri, 30 Jan 2026 14:36:03 +0100
+
+python-perfact-dbutils (1.0+nmu1) UNRELEASED; urgency=medium
+
+  [ Alexander Rolfes ]
+  * Typehints in signature is now used for the "type" documentation
+    parameters
+
+ -- Alexander Rolfes <alexander.rolfes@perfact.de>  Thu, 29 Jan 2026 15:50:39 +0100
+
+python-perfact-dbutils (1.0) unstable; urgency=medium
+
+  [ Kai Joshua Martin ]
+  * Add crud functions and tests.
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Mon, 26 Jan 2026 12:35:45 +0100
+
+python-perfact-dbutils (0.2) unstable; urgency=medium
+
+  [ Viktor Dick ]
+  * Cover with tests
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Wed, 07 Jan 2026 15:57:07 +0100
+
+python-perfact-dbutils (0.1) unstable; urgency=medium
+
+  [ Viktor Dick ]
+  Initial release
+
+ -- Viktor Dick <viktor.dick@perfact.de>  Mon, 05 Jan 2026 09:55:34 +0100

perfact_dbutils-1.7.0/debian/control

@@ -0,0 +1,19 @@
+Source: python-perfact-dbutils
+Section: unknown
+Priority: optional
+Maintainer: Viktor Dick <viktor.dick@perfact.de>
+Rules-Requires-Root: no
+Build-Depends:
+ debhelper-compat (= 13),
+ python3,
+ pybuild-plugin-pyproject,
+ python3-setuptools-scm,
+Standards-Version: 4.6.2
+
+Package: python3-perfact-dbutils
+Architecture: all
+Depends:
+ ${misc:Depends},
+ ${python3:Depends},
+ python3,
+Description: Basic tools for interacting with the database

perfact_dbutils-1.7.0/debian/copyright

@@ -0,0 +1,13 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+
+Files: *
+Copyright: 2002-2025, PerFact Innovation GmbH & Co. KG <info@perfact.de>
+License: GPL-2+
+
+License: GPL-2+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; version 2 dated June, 1991, or (at
+ your option) any later version.
+ On Debian systems, the complete text of version 2 of the GNU General
+ Public License can be found in '/usr/share/common-licenses/GPL-2'.

perfact_dbutils-1.7.0/debian/manpages

@@ -0,0 +1 @@
+doc/build/man/*

perfact_dbutils-1.7.0/debian/python3-perfact-dbutils.install

@@ -0,0 +1 @@
+doc/build/html /usr/share/doc/python3-perfact-dbutils/

perfact_dbutils-1.7.0/debian/rules

@@ -0,0 +1,16 @@
+#!/usr/bin/make -f
+
+# See debhelper(7) (uncomment to enable).
+# Output every command that modifies files on the build system.
+#export DH_VERBOSE = 1
+
+override_dh_auto_test:
+	tox
+
+%:
+	dh $@ --with python3 --buildsystem=pybuild
+
+override_dh_auto_build:
+	dh_auto_build
+	tox -e docs 
+

perfact_dbutils-1.7.0/debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

perfact_dbutils-1.7.0/doc/source/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

perfact_dbutils-1.7.0/doc/source/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "python-perfact-dbutils"
+copyright = "2026"
+author = "Alexander Rolfes, Viktor Dick, Ján Jockusch"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# -- Options for todo extension ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+
+todo_include_todos = True
+
+# -- Options for auto documentation of typehints -----------------------------
+
+always_document_param_types = True

perfact_dbutils-1.7.0/doc/source/index.rst

@@ -0,0 +1,18 @@
+.. perfact documentation master file, created by
+   sphinx-quickstart on Fri Jan  9 12:50:21 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+perfact documentation
+=====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   api/modules 

perfact_dbutils-1.7.0/perfact/dbutils/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/python3
+from .conn import wrap_zrdbconn, wrap_zrdbconn_sqasession
+
+__all__ = ["wrap_zrdbconn", "wrap_zrdbconn_sqasession"]

perfact_dbutils-1.7.0/perfact/dbutils/allowedclasses.py

@@ -0,0 +1,11 @@
+from .api import LCC, Context, User
+from .conn import Namespace, Results, ZRDBConnectionWrapper
+
+__all__ = [
+    "User",
+    "LCC",
+    "Context",
+    "ZRDBConnectionWrapper",
+    "Namespace",
+    "Results",
+]

perfact_dbutils-1.7.0/perfact/dbutils/api.py

@@ -0,0 +1,188 @@
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Protocol, TypedDict
+
+from .conn import Executor
+
+
+@dataclass
+class User:
+    """
+    Class for the user object within the Context object
+
+    :param name: Name of the user
+    :param user_roles: List of active user roles
+    :param is_manager: Pointer to the function is_manager
+    :param user_has_role: Pointer to the function is_manager user_has_role
+    """
+
+    name: str
+    user_roles: list[str]
+    is_manager: Callable[[], bool]
+    user_has_role: Callable[[list[str]], bool]
+
+
+class CodedHook(Protocol):
+    """
+    Class describing the expected signature of the coded hooks.
+
+    :param conn: DB Connector
+    :type conn: Executor
+
+    :param lib: Pointer to the lib functions
+    :type lib: Any
+
+    :param user: User object
+    :type user: User
+
+    :param id: Id of the record
+    :type id: int
+
+    :param table: Name of the table
+    :type table: str
+    """
+
+    def __call__(self, conn: Executor, id: int, table: str, **kw: Any): ...
+
+
+class MayResult(TypedDict):
+    """The MayResult dict may be returned by may hooks"""
+
+    may: bool
+    """True if the lc transition is allowed. Otherwise false."""
+    hint: str
+    """May contain a hint for the user why the transition is not allowed."""
+
+
+class MayHook(Protocol):
+    """
+    Class describing the expected signature of the may hooks. A may hook
+    function must have the following signature:
+
+    :param conn: DB Connector
+    :type conn: Executor
+
+    :param lib: Pointer to the lib functions
+    :type lib: Any
+
+    :param user: User object
+    :type user: User
+
+    :param id: Id of the record
+    :type id: int
+
+    :param table: Name of the table
+    :type table: str
+
+    :return: Returns true if the lc transition is allowed. May also return a
+        MayResult dict instead.
+    :rtype: bool | MayResult
+    """
+
+    def __call__(
+        self, conn: Executor, id: int, table: str, **kw
+    ) -> bool | MayResult: ...
+
+
+class CodedHooksResolver(Protocol):
+    """
+    Class describing the signature of the coded_hooks_resolver function. The
+    coded hooks resolver function must have the following signature:
+
+    :param table: Name of the table
+    :type table: str
+
+    :param src_lc_id: ID of the source lc
+    :type src_lc_id: int
+
+    :param tgt_lc_id: ID of the target lc
+    :type tgt_lc_id: int
+
+    :param hook_name: Name of the hook
+    :type hook_name: str
+
+    :param hook_path: Overwrites the automatically build path. Defaults to None
+    :type hook_path: Optional[str]
+
+    :return: Returns a callable if the hook could be resolved
+    :rtype: CodedHook | MayHook | None
+    """
+
+    def __call__(
+        self,
+        table: str,
+        src_lc_id: int,
+        tgt_lc_id: int,
+        hook_name: str,
+        hook_path: Optional[str] = None,
+    ) -> CodedHook | MayHook | None: ...
+
+
+@dataclass
+class LCC:
+    """
+    Class for the lcc object within the Context object
+
+    :param coded_hooks_resolver: Pointer to the function that will be used to
+        resolve the coded hooks.
+    :param side_effect_resolver: Pointer to the function that will be used to
+        resolve the side effects.
+    """
+
+    coded_hooks_resolver: CodedHooksResolver
+    side_effect_resolver: Callable[[str], Callable]
+
+
+class SelfilterGenerator(Protocol):
+    """
+    Class describing the signature of the coded_hooks_resolver function. The
+    coded hooks resolver function must have the following signature:
+
+    :param table: Name of the table
+    :type table: str
+
+    :param column: Name of the column
+    :type column: str
+
+    :param kw: Additonal keyword arguments
+    :type kw: Any
+
+    :return: Returns the selfilter for the given table and column
+    :rtype: str
+    """
+
+    def __call__(
+        self,
+        table: str,
+        column: str,
+        **kw: Any,
+    ) -> str: ...
+
+
+def dummy_selfilter_gen(
+    table: str,
+    column: str,
+    **kw: Any,
+) -> str:
+    return ""
+
+
+@dataclass
+class Context:
+    """
+    Class for the ctx object
+
+    :param conn: DB connector
+    :param user: User object, containing information about the current user
+    :param lcc: LCC object, containing functions to resolve the lcc hooks
+    :param lib: Pointer to the lib context
+    :param api: Pointer to the api context
+    :param selfilter_generator: Pointer to a function that can generate the
+        selfilter for a table.
+    """
+
+    conn: Executor
+    user: User
+    lcc: LCC
+    lib: Any
+    api: Any
+    selfilter_generator: SelfilterGenerator = dummy_selfilter_gen