Contributing & Developer Setup¶

bharat-courts is free, open-source software and contributions are welcome — bug reports, fixes, more court coverage, better CAPTCHA solving, and docs all help. This page gets you from a fresh clone to a green test run.

The code lives on GitHub at github.com/iamshouvikmitra/bharat-courts. Open issues and pull requests there.

Prerequisites¶

• Python 3.11+ — check with python3 --version. If your system Python is older, use python3.12 explicitly in the commands below.
• git

Dev environment setup¶

Fork the repo on GitHub, then clone your fork:

# 1. Clone (swap in your fork's URL)
git clone https://github.com/<your-username>/bharat-courts.git
cd bharat-courts

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate     # Linux/macOS
# .venv\Scripts\activate      # Windows

# 3. Editable install with all extras (OCR + ONNX + CLI + archive + dev tools)
pip install -e ".[all]"

# 4. Verify everything works
pytest
ruff check . && ruff format --check .

pip install -e ".[all]" installs the package in editable mode with every optional extra, so you can work on any backend — live clients, the archive, the CLI — without reinstalling.

python3.12 -m venv .venv

Running tests¶

The unit suite is 250 tests and runs entirely offline — no network, no CAPTCHA, no AWS. It should pass on a fresh clone in seconds.

# Full unit suite (fast, offline)
pytest

# A single test file
pytest tests/test_hcservices_parser.py

# A single test
pytest tests/test_hcservices_parser.py::test_parse_case_status_json

# Verbose output
pytest -v

Live integration tests¶

The tests/integration/ directory holds standalone scripts that hit the real eCourts portals and the real AWS Open Data buckets. They are not collected by pytest (the default python_files=test_*.py pattern does not match them), so you invoke them directly. They need network access, and the portal-facing ones need a CAPTCHA solver (install the [ocr] extra, included in [all]). Each script prints PASS/FAIL and exits non-zero on failure, which makes them useful for pre-release validation.

python tests/integration/hcservices.py            # HC Services portal + CAPTCHA
python tests/integration/archive.py               # archive + facade vs real S3
python tests/integration/districtcourts.py        # District Courts portal
python tests/integration/calcuttahc_wpa_12886.py  # Calcutta HC regression case

See tests/integration/README.md for the full list and details.

Linting and formatting¶

The project uses ruff for both linting and formatting.

# Check for lint issues
ruff check .

# Auto-fix what ruff can fix
ruff check --fix .

# Check formatting without writing
ruff format --check .

# Reformat the codebase
ruff format .

Config lives in pyproject.toml: Python 3.11 target, 100-character line length, rule sets E, F, I, N, W.

Source layout¶

All package code is under src/bharat_courts/ (a src/ layout, which prevents accidental imports of the working tree during development). The headline modules:

The clients in hcservices/, districtcourts/, calcuttahc/, and judgments/ each follow the same internal split — client.py (the public class), endpoints.py (URL and form builders), parser.py (response parsers).

For deeper architectural background see How it works and the data sources page.

Testing approach¶

Knowing how the suite is built makes it easier to add tests for your change:

• HTTP is mocked with respx, which hooks into httpx natively. Parser tests feed recorded HTML/JSON fixtures from tests/fixtures/ through the parsers.
• CAPTCHA in tests is handled by a custom CaptchaSolver subclass that returns a fixed string, so live-client tests never touch a real solver.
• Archive tests build synthetic in-memory tars and respx-mocked HTTP instead of hitting S3, and stub the DuckDB query / cache layer with AsyncMock + unittest.mock.patch.object.
• Facade tests stub both backends with AsyncMock so the routing decision matrix is exercised without touching either S3 or the live portal.

Areas where help is needed¶

A few concrete places where contributions would land well:

• Better CAPTCHA solving — ddddocr is ~75% accurate on the judgments portal; the ONNX solver is an alternative, but a fine-tuned model would help further.
• District court reliability — broader coverage testing across more states/complexes; case_status_by_party still has no pagination.
• Supreme Court case search — SCIClient.search_by_year / search_by_party are stubbed; the live www.sci.gov.in portal has a CAPTCHA-protected case-no/diary-no/party-name form that needs wiring up.
• HC Services case history — case_status does not return Pending/Disposed (or registration date / next hearing) because the SDK hits showRecords only; calling o_civil_case_history.php afterwards would fill in the rest.
• More High Court coverage — testing against courts beyond Delhi, Bombay, and Allahabad.
• Documentation — more examples and tutorials.

Submitting changes¶

1. Fork the repo and create a branch: git checkout -b my-feature.
2. Make your changes.
3. Run pytest and ruff check . to confirm tests pass and the code is clean.
4. Commit with a descriptive message.
5. Open a pull request against iamshouvikmitra/bharat-courts.

Bug reports and feature requests are equally welcome on the issue tracker.

License¶

bharat-courts is released under the MIT License. Note that the historical archive data itself is CC-BY-4.0 — attribute Dattam Labs / the eCourts platform when you redistribute it. See Data sources for details.