Configure requests and caches¶

Live clients read BharatJudgementsConfig. Archive cache controls are separate environment settings. Set values before constructing clients.

Live request settings¶

Field	Environment variable	Default	Behaviour
`request_delay`	`BHARAT_JUDGEMENTS_REQUEST_DELAY`	`1.0`	Minimum interval between requests, in seconds
`timeout`	`BHARAT_JUDGEMENTS_TIMEOUT`	`60`	HTTP timeout in seconds
`max_retries`	`BHARAT_JUDGEMENTS_MAX_RETRIES`	`3`	Total attempts for retryable HTTP failures
`verify_ssl`	`BHARAT_JUDGEMENTS_VERIFY_SSL`	`true`	Verify TLS certificates; disable only through an explicit portal exception
`calcutta_verify_ssl`	`BHARAT_JUDGEMENTS_CALCUTTA_VERIFY_SSL`	unset	Override TLS verification for the Calcutta portal only
`captcha_attempts`	`BHARAT_JUDGEMENTS_CAPTCHA_ATTEMPTS`	`5`	CAPTCHA attempt budget, 1–10
`user_agent`	`BHARAT_JUDGEMENTS_USER_AGENT`	Bundled browser-like string	Request User-Agent
`log_level`	`BHARAT_JUDGEMENTS_LOG_LEVEL`	`INFO`	Stored setting; configure Python logging explicitly

The HTTP client retries server errors and selected transport failures. It does not retry HTTP 4xx responses. CAPTCHA retries happen in the portal clients and have separate budgets. Request delays must be nonnegative, timeouts positive, and transport and CAPTCHA attempt budgets between 1 and 10.

Set environment values¶

PowerShellmacOS / Linux

$env:BHARAT_JUDGEMENTS_TIMEOUT = "120"
$env:BHARAT_JUDGEMENTS_REQUEST_DELAY = "2.0"

export BHARAT_JUDGEMENTS_TIMEOUT=120
export BHARAT_JUDGEMENTS_REQUEST_DELAY=2.0

BharatJudgementsConfig also reads .env in the current working directory. Its default singleton is created at import time, so set variables before importing the package. Keep machine-specific .env files out of version control.

Give a client explicit settings¶

import asyncio
from bharat_judgements import HCServicesClient, get_court
from bharat_judgements.config import BharatJudgementsConfig


async def main():
    settings = BharatJudgementsConfig(timeout=120, request_delay=2.0)
    async with HCServicesClient(config=settings) as client:
        print(await client.list_benches(get_court("delhi")))


asyncio.run(main())

This example makes a live request. Configuration construction alone does not contact a portal.

For Calcutta's legacy TLS handshake, the client keeps legacy renegotiation support while verifying certificates by default. If that portal cannot provide a trusted certificate chain, explicitly pass BharatJudgementsConfig(calcutta_verify_ssl=False) to that client. This disables certificate checks for that client and is a security tradeoff; keep other clients on their verified defaults. The release gate remains strict and reports certificate-chain failures.

Archive cache settings¶

Environment variable	Default	Behaviour
`BHARAT_JUDGEMENTS_ARCHIVE_METADATA_TTL_DAYS`	`30`	Age after which cached metadata is refreshed; `0` disables freshness reuse
`BHARAT_JUDGEMENTS_ARCHIVE_CACHE_MAX_GB`	`5`	PDF/tar cache size cap, in GiB

These values are read directly from the process environment by archive helpers. Adding them only to .env does not put them into os.environ; export them in the shell or load that file explicitly in your own application. Metadata refresh does not make the publisher's dataset more current.

Cache files live under ~/.cache/bharat-judgements/archive/ in the executing user's environment. Use ArchiveClient.cache_info() or bharat-judgements archive cache to inspect them. See the archive guide before bulk retrieval.

Logging and connection behaviour¶

Configure standard Python logging, for example logging.basicConfig(level=logging.INFO), to see source-routing decisions. In the CLI, use the global --verbose option. Logs can contain query parameters; review where you store them.

The live HTTP implementation verifies TLS by default. BHARAT_JUDGEMENTS_VERIFY_SSL=false is an explicit portal exception. Archive HTTP uses its separate verified client. See how requests work.

Next: configuration API, CAPTCHA solvers, or quickstart.