Run All Checks

Execute all project checks (ruff, mypy, pytest, Sphinx docs) and fix any errors found.

Quick Start

Run all checks and fix errors:

1. Execute the run-all-checks script (or run checks manually).
2. Review output for errors and warnings.
3. Fix any issues found.
4. Re-run checks to verify fixes.

Preferred Method: Script

From project root with venv activated:

bash
1./scripts/run-all-checks.sh

Options:

• -p, --parallel — Run code checks and docs in parallel (default).
• -s, --sequential — Run all checks one after another (easier to debug).
• -c, --code — Only ruff, mypy, pytest.
• -d, --docs — Only Sphinx documentation build.
• -h, --help — Show usage.

Check Commands (Manual)

All commands assume project root and source venv/bin/activate (or venv\Scripts\activate on Windows).

Code (from project root)

bash
1# Lint (ruff)
2python -m ruff check src tests examples
3python -m ruff format --check src tests examples
4
5# Type check (mypy)
6python -m mypy src tests examples
7
8# Tests (pytest)
9python -m pytest tests -q

Documentation (from project root)

bash
1cd docs && make clean && make html SPHINXOPTS="-W"

The script and docs build use SPHINXOPTS="-W" so Sphinx treats warnings as errors; the docs check fails if any warnings are produced.

Execution Workflow

Copy this checklist and track progress:

text
1Check Progress:
2- [ ] Ruff check (src, tests, examples)
3- [ ] Ruff format --check
4- [ ] Mypy (src, tests, examples)
5- [ ] Pytest (tests)
6- [ ] Docs build without warnings
7- [ ] All errors fixed
8- [ ] Re-verify all checks pass

Step 1: Run All Checks

Option A – Script (recommended):

bash
1./scripts/run-all-checks.sh

Option B – Sequential manual:

bash
1source venv/bin/activate
2python -m ruff check src tests examples && \
3python -m ruff format --check src tests examples && \
4python -m mypy src tests examples && \
5python -m pytest tests -q && \
6(cd docs && make clean && make html SPHINXOPTS="-W")

Step 2: Analyze Results

Check output for:

• Errors: Must be fixed (non-zero exit code).
• Warnings: Must be fixed. The docs build is run with SPHINXOPTS="-W", so Sphinx warnings cause the documentation check to fail.

Common error types:

Step 3: Fix Issues

For each error:

1. Read the error message and file/line.
2. Open the file and apply the appropriate fix.
3. Re-run the failing check to confirm.

Step 4: Re-verify

After fixing, run all checks again:

bash
1./scripts/run-all-checks.sh

All checks should pass with exit code 0.

Common Fixes Reference

Ruff Unused Argument (ARG001)

For pytest fixtures that are dependencies but not directly used:

python
1def my_fixture(other_fixture: None) -> None:  # noqa: ARG001
2    ...

Ruff UP035 (typing → collections.abc)

Use collections.abc for AsyncGenerator, Iterable, etc.:

python
1from collections.abc import AsyncGenerator, Iterable

Sphinx Duplicate Object Warning

Add :no-index: to automodule directive:

rst
1.. automodule:: cloud_tasks.config
2   :members:
3   :no-index:

Mypy in Tests

Tests use overrides in pyproject.toml (module = "tests.*") for method-assign and attr-defined (mocks). For other mypy errors in tests, add targeted # type: ignore[code] or fix the type.

Type Annotation Errors

For union or forward-reference issues:

python
1from __future__ import annotations  # Add at top of file

Success Criteria

All checks pass when:

• ruff check src tests examples → "All checks passed!"
• ruff format --check src tests examples → "All files formatted"
• mypy src tests examples → "Success: no issues found"
• pytest tests -q → All tests pass
• make html SPHINXOPTS="-W" (in docs/) → Build completes with exit 0 (no errors or warnings)