How openjustice-in/ecourts works
Project type and purpose
• This is a Python-based information-retrieval toolkit (a CLI/library) for bulk fetching and parsing case data from the ECourts website (hcservices.ecourts.gov.in).
• It exposes both a command-line interface (ecourts CLI commands) and a programmatic API (ecourts.ECourt class).
File structure
• Top-level modules:
• ecourts/cli — CLI entrypoints and argument parsing
• ecourts/ecourt.py — core HTTP client (“ECourt” class)
• ecourts/captcha.py — single-threaded captcha handling
• ecourts/parsers — HTML→domain object parsing logic
• ecourts/entities — domain models (Case, Order, Hearing, etc.)
• ecourts/storage.py — local caching/persistence of fetched data
• courts.csv — static metadata: list of known courts & state codes
• pyproject.toml / setup info defines packaging; GitHub workflows define tests, publishing, docs.
README for additional insights
• Purpose: fetch lists of cases, case-details, cause-lists, orders/judgements
• Core abstractions: ECourt (handles HTTP, retries, rate-limiting), Court (metadata), Entities for domain objects
• Guiding principles: single-threaded, polite retries, use ISO-3166 codes
Main components
a. Components
1. CLI Layer („ecourts“ commands)
2. ECourt client
3. Captcha handler
4. HTTP/Network interface (Requests library)
5. External ECourts Service (hcservices.ecourts.gov.in)
6. Parsers (HTML → Entities)
7. Domain Entities (Case, Order, Hearing, etc.)
8. Storage layer (local file or in-memory cache; YAML/JSON)
9. Static court metadata (courts.csv)
b. Relationships & interactions
• User invokes CLI → CLI Layer calls ECourt API
• ECourt orchestrates:
– Load metadata (courts.csv) → pick correct state/court code
– Perform HTTP request(s) via HTTP/Network → External ECourts Service
– If Captcha challenge arises → Captcha handler intervenes → resume HTTP requests
– Receive raw HTML/JSON → dispatch to appropriate Parser
– Parser builds Domain Entities
– Entities are optionally persisted via Storage
– CLI or calling code receives Entities for display or further processing
c. Architectural patterns / design principles
• Single-responsibility: separate CLI, HTTP client, captcha logic, parsing, domain modelling, storage
• Layered architecture: Presentation (CLI/API) → Application (ECourt) → Infrastructure (HTTP, Storage)
• Domain-driven design: Entities layer encapsulates legal concepts
• Polite HTTP client: rate-limit, retry, backoff
d. Key technologies / libraries
• Python 3.x, Click or argparse (CLI)
• requests (HTTP) or similar
• BeautifulSoup / lxml (HTML parsing)
• PyYAML or JSON (storage serialization)
• pytest / vcrpy (tests and cassettes)
Essential details to capture
• Single-threaded, polite-HTTP pattern (retry/backoff)
• Captcha component inserted in the HTTP flow
• Clear separation of concerns (parsing vs. domain vs. I/O)
• Static metadata lookup (courts.csv) as part of request preparation