Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (81 loc) · 2.52 KB

CONTRIBUTING.md

File metadata and controls

116 lines (81 loc) · 2.52 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

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