Contributing#

AI usage policy#

Pintext has an explicit AI usage policy. Please read it before opening an issue or a pull request. Agent-specific guidance for working in this repository lives in AGENTS.md .

Contributing to the code base#

Requirements#

Developing requires:

the uv package manager;
the pre-commit git hook manager (or its drop-in replacement prek);
the poethepoet task runner (optional).

Setting up a development environment#

Clone the repository:

git clone git@github.com:leroyvn/pintext.git

Enter the created repository and set up the development environment:

cd pintext
uv sync --all-groups --all-extras

Finally, activate the pre-commit hooks:

pre-commit install  # or prek install

Package layout#

Pintext is built in three layers:

src/pintext/: the core, which must depend on Pint alone;
src/pintext/attrs/: attrs integration, behind the attrs extra;
src/pintext/pydantic/: pydantic integration, behind the pydantic extra.

Important

Nothing in the core may import attrs or pydantic. A dedicated CI job installs the package without extras and runs tests/core, so a stray import breaks the build.

Running tests#

The testing process of Pintext uses [pytest](https://docs.pytest.org). A task is defined to help you run the tests:

poe test  # or uv run poe test if poe is not available globally on your system

This runs unit tests, the doctests embedded in every docstring under src/, and the doctests in the documentation. Tests are split by layer:

uv run pytest tests/core       # no optional dependency required
uv run pytest tests/attrs      # skipped without attrs
uv run pytest tests/pydantic   # skipped without pydantic

Linting and type checking#

uv run ruff check
uv run ruff format --check
uv run ty chec

Repository conventions are checked with repo-review:

uvx --from 'sp-repo-review[cli]' repo-review

Deliberate exemptions are recorded in [tool.repo-review] ignore in pyproject.toml. Passing --ignore on the command line overrides that list rather than adding to it, so run the command bare.

Building the documentation#

To build the documentation, use the dedicated task:

poe docs  # or uv run poe docs

Incremental autobuild is also supported:

poe docs-serve  # or uv run poe docs-serve

Maintainers: release process#

Pintext follows Semantic Versioning.

Pre-release steps

Make sure that all tests pass.
Make sure the change log is up-to-date. Add the release date to the relevant section header.
Set the package version number to the target value:
```
uv version <MAJOR.MINOR.PATCH>
```
Create and push a commit with the following message:
```
pintext version <MAJOR.MINOR.PATCH>
```

Release steps

Create a new release on GitHub.
When asked for a tag, create a new one (v<MAJOR.MINOR.PATCH>).
The automated workflow will build the package and upload it to PyPI using Trusted Publishing. No API token is involved; the pypi environment must be configured as a trusted publisher for the project.

Post-release steps

Create a new section in the change log (CHANGELOG.md) with the title Pintext <MAJOR.MINOR.PATCH> (upcoming release).
Bump the version to the next development one:
```
uv version <MAJOR.MINOR.PATCH>.dev
```
Create and push a commit with the following message:
```
Version <MAJOR.MINOR.PATCH> ready for development
```

Roadmap#

Not planned yet

Nothing currently.