| 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
