name	libzdock-python-engineering
description	Engineering rules for libzdock's uv-managed Python package, including packaging, layout, typing, tests, tooling, documentation, Make integration, and CI. Use for changes under python/ or any workflow that installs, builds, validates, or publishes the zdock Python distribution.
license	BSD-2-Clause
metadata	{"author":"Arjan van der Velde, Weng Lab","copyright":"Copyright (c) 2019-2026 Arjan van der Velde, Weng Lab","version":"1.0.0"}

libzdock Python Engineering

Normative Language

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative.

MUST indicates an absolute requirement.
MUST NOT indicates an absolute prohibition.
SHOULD indicates a strong recommendation that may be departed from only for a documented reason.
SHOULD NOT indicates a discouraged action that may be taken only for a documented reason.
MAY indicates an optional action.

Interpret these keywords according to RFC 2119 and RFC 8174 when they appear in uppercase.

Project And Package Layout

python/pyproject.toml MUST be the sole package and tool configuration file.
python/uv.lock MUST be the sole Python lockfile and MUST remain committed.
Dependency management and project commands MUST run through uv. Agents MUST NOT restore setup.py, ad hoc pip workflows, Poetry, or a second lockfile.
Runtime code MUST remain under python/src/zdock/ and tests under python/tests/.
Tests MUST import the installed zdock package. They MUST NOT modify sys.path to import source files directly.
Hatchling MUST remain the build backend unless a concrete packaging requirement justifies a change.
The distribution version SHOULD track the repository release version.
Supported Python versions MUST be declared in requires-python; Black MUST target the lowest supported version.

API And Implementation

The public import MUST remain from zdock import ....
Parser failures and unsupported format operations SHOULD raise ZDOCKError or a more specific documented exception.
Public functions, classes, methods, reusable test helpers, and tests MUST have complete type annotations and informative docstrings.
Return types MUST be precise. Functions MUST NOT silently return None when their contract implies a result.
Filesystem code SHOULD use pathlib.Path.
Subprocess calls MUST use explicit argument lists, shell=False, captured output, and bounded timeouts.
Mutable implementation details SHOULD NOT be exposed when an immutable public view is sufficient.
Any, local-import cycle workarounds, and type or lint suppressions SHOULD be avoided. Findings SHOULD be fixed structurally.

Tooling

Development dependencies MUST include current compatible versions of isort, Black, mypy, and pylint in uv's dev dependency group.
isort, Black, mypy, and pylint settings MUST live in python/pyproject.toml.
mypy MUST run in strict mode.
Quality checks MUST run against both src and tests.
Python-related pre-commit hooks MUST use the uv-managed environment.
Generated .venv, .uv-cache, __pycache__, build, distribution, and tool-cache directories MUST NOT be treated as source.

Tests And Documentation

Behavior changes MUST include tests for the happy path and the relevant failure boundary.
Every test MUST state its invariant in its docstring.
Parser tests SHOULD cover ordinary ZDOCK, M-ZDOCK, malformed records, mixed formats, and limiting behavior as applicable.
CLI integration tests MUST invoke the native binaries built by GNU Make and use a timeout.
Markdown prose MUST NOT be artificially hard-wrapped to satisfy source-code line limits.
python/README.md MUST document uv setup, test, quality, build, and import workflows.

Validation

Run Python checks from the repository root:

uv --directory python lock --check
uv --directory python run isort --check-only src tests
uv --directory python run black --check src tests
uv --directory python run mypy src tests
PYLINTHOME=python/.pylint.d uv --directory python run pylint src tests
uv --directory python run python -m unittest discover -s tests -v
uv --directory python build

The equivalent GNU Make entry points are make python-test and make python-check. Agents changing Make or CI integration MUST verify those entry points as well.

Before handoff, scan for unjustified suppressions:

rg -n "type:\s*ignore|pylint:\s*disable|#\s*noqa|#\s*pyright|#\s*mypy|pragma:\s*no cover" python/src python/tests python/pyproject.toml

libzdock Python Engineering

Normative Language

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative.

MUST indicates an absolute requirement.

MUST NOT indicates an absolute prohibition.

SHOULD indicates a strong recommendation that may be departed from only for a documented reason.

SHOULD NOT indicates a discouraged action that may be taken only for a documented reason.

MAY indicates an optional action.

Interpret these keywords according to RFC 2119 and RFC 8174 when they appear in uppercase.

Project And Package Layout

python/pyproject.toml MUST be the sole package and tool configuration file.

python/uv.lock MUST be the sole Python lockfile and MUST remain committed.

Dependency management and project commands MUST run through uv. Agents MUST NOT restore setup.py, ad hoc pip workflows, Poetry, or a second lockfile.

Runtime code MUST remain under python/src/zdock/ and tests under python/tests/.

Tests MUST import the installed zdock package. They MUST NOT modify sys.path to import source files directly.

Hatchling MUST remain the build backend unless a concrete packaging requirement justifies a change.

The distribution version SHOULD track the repository release version.

Supported Python versions MUST be declared in requires-python; Black MUST target the lowest supported version.

API And Implementation

The public import MUST remain from zdock import ....

Parser failures and unsupported format operations SHOULD raise ZDOCKError or a more specific documented exception.

Public functions, classes, methods, reusable test helpers, and tests MUST have complete type annotations and informative docstrings.

Return types MUST be precise. Functions MUST NOT silently return None when their contract implies a result.

Filesystem code SHOULD use pathlib.Path.

Subprocess calls MUST use explicit argument lists, shell=False, captured output, and bounded timeouts.

Mutable implementation details SHOULD NOT be exposed when an immutable public view is sufficient.

Any, local-import cycle workarounds, and type or lint suppressions SHOULD be avoided. Findings SHOULD be fixed structurally.

Tooling

Development dependencies MUST include current compatible versions of isort, Black, mypy, and pylint in uv's dev dependency group.

isort, Black, mypy, and pylint settings MUST live in python/pyproject.toml.

mypy MUST run in strict mode.

Quality checks MUST run against both src and tests.

Python-related pre-commit hooks MUST use the uv-managed environment.

Generated .venv, .uv-cache, __pycache__, build, distribution, and tool-cache directories MUST NOT be treated as source.

Tests And Documentation

Behavior changes MUST include tests for the happy path and the relevant failure boundary.

Every test MUST state its invariant in its docstring.

Parser tests SHOULD cover ordinary ZDOCK, M-ZDOCK, malformed records, mixed formats, and limiting behavior as applicable.

CLI integration tests MUST invoke the native binaries built by GNU Make and use a timeout.

Markdown prose MUST NOT be artificially hard-wrapped to satisfy source-code line limits.

python/README.md MUST document uv setup, test, quality, build, and import workflows.

Validation

Run Python checks from the repository root:

uv --directory python lock --check uv --directory python run isort --check-only src tests uv --directory python run black --check src tests uv --directory python run mypy src tests PYLINTHOME=python/.pylint.d uv --directory python run pylint src tests uv --directory python run python -m unittest discover -s tests -v uv --directory python build

The equivalent GNU Make entry points are make python-test and make python-check. Agents changing Make or CI integration MUST verify those entry points as well.

Before handoff, scan for unjustified suppressions:

libzdock-python-engineering