Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (89 loc) · 2.95 KB

CONTRIBUTING.md

File metadata and controls

127 lines (89 loc) · 2.95 KB
Raw

Contributing

Thanks for contributing to pdfrest.

Development setup

  1. Install project tooling:
uv sync --group dev
  1. (Recommended) install git hooks:
uv run pre-commit install
  1. Verify package import/version:
uv run python -c "import pdfrest; print(pdfrest.__version__)"

Adding or evolving a client API

When asking Codex to add a documented pdfRest endpoint or a compatible parameter to an existing endpoint, begin the prompt with the repository-local $pdfrest-client-api skill. Include the Jira work item key when one exists. The PDFCloud-API checkout and its documented OpenAPI operation must be available before using the skill. Prefer adding the neighboring PDFCloud-API directory to the Codex project so the skill can read the contract directly. For example:

$pdfrest-client-api PDFCLOUD-6233: Add the documented PDFCloud-API operation
for ...

The skill uses the PDFCloud-API OpenAPI specification as the contract; keeps the sync and async clients aligned; puts wire serialization and validation in Pydantic payload models; preserves existing caller behavior; and requires focused unit coverage plus matching live endpoint tests. It also handles the versioning required for a newly added public API.

Code quality checks

Run these before opening a PR:

uv run ruff format .
uv run ruff check .
uv run basedpyright

Check tracked filenames for UTF-8 NFC normalization and collisions:

uv run --script .cit-quality/vendor/check_nfc_filenames.py

This read-only check also runs through pre-commit. It requires Python 3.11 or newer and reports offending filenames without renaming them. Copy identity and the review boundary are recorded in the quality tooling notes.

Tests

Quick local run:

uv run pytest -n auto --maxschedchunk 2

Full interpreter matrix with coverage artifacts (coverage/py<version>/):

uvx nox -s tests

Class/function coverage gate for client classes:

uvx nox -s class-coverage

To reuse existing coverage JSON without rerunning tests:

uvx nox -s class-coverage -- --no-tests

Live tests

Live tests require PDFREST_API_KEY. By default, the test fixture tries the local service, the development service, and then the production service. To run against a specific reachable pdfRest deployment first, set PDFREST_LIVE_BASE_URL to its base URL:

export PDFREST_API_KEY="..."
export PDFREST_LIVE_BASE_URL="https://pdfrest.example.com"
uvx nox -s tests-3.11 -- tests/live

If that URL is unavailable, the fixture continues with its normal fallback URLs and fails only when none are reachable.

Examples

Run all examples:

uvx nox -s examples

Run one example:

uv run nox -s run-example -- examples/delete/delete_example.py

Docs preview (optional)

uv run mkdocs serve
uv run mkdocs build --strict