Contributing

Development Setup

git clone https://github.com/faulander/pyjira.git
cd pyjira
uv sync --all-extras

Run Tests

uv run pytest           # run all tests
uv run pytest -v        # verbose output
uv run pytest -x        # stop on first failure
uv run pytest -k search # run only search tests

Tests use respx to mock httpx requests. No real Jira instance is needed.

Build Documentation

uv pip install -r docs/requirements.txt
sphinx-build -b html docs/source docs/build/html

Open docs/build/html/index.html to preview.

Project Structure

src/pyjira/
    __init__.py          # Public API exports
    client.py            # JiraClient, AsyncJiraClient
    auth.py              # httpx.BasicAuth wrapper
    config.py            # JiraConfig dataclass
    exceptions.py        # Exception hierarchy + raise_for_response()
    pagination.py        # Paginator, AsyncPaginator
    models/              # Pydantic v2 models (23 files)
    resources/           # API resource classes (23 files, sync + async)
tests/                   # Test suite
docs/                    # Sphinx documentation

Conventions

• 2-space indentation

• Single quotes for strings

• from __future__ import annotations in every file

• TYPE_CHECKING guard for httpx imports

• All model fields are optional (| None = None)

• camelCase JSON aliases via Field(alias='...')

• Every HTTP call followed by raise_for_response(response)

• Dual sync/async pattern: every resource has FooResource and AsyncFooResource

Adding a New Resource

1. Create a model file in src/pyjira/models/ with Pydantic v2 models

2. Create a resource file in src/pyjira/resources/ with sync + async classes

3. Export models from src/pyjira/models/__init__.py

4. Export resources from src/pyjira/resources/__init__.py

5. Wire the resource into JiraClient and AsyncJiraClient in src/pyjira/client.py

6. Add public exports to src/pyjira/__init__.py

7. Write tests in tests/