Skip to content

Data models

Every result type is a plain dataclass with a to_dict() / to_json() mixin, so results serialise straight to JSON for spreadsheets, dashboards or case-management tools.

models

Data models for bharat-courts.

All models are dataclasses with built-in JSON serialization via to_dict() and to_json(). Date fields serialize to ISO 8601 strings. Enum fields serialize to their string values. Binary fields (pdf_bytes) are excluded from serialization by default.

Judgment dataclass 

Judgment(
    cnr: str | None = None,
    case_id: str | None = None,
    title: str | None = None,
    court: Court | None = None,
    court_name_raw: str = "",
    bench: str | None = None,
    court_code: str | None = None,
    judges: list[str] = list(),
    author_judge: str | None = None,
    decision_date: date | None = None,
    date_of_registration: date | None = None,
    petitioner: str | None = None,
    respondent: str | None = None,
    citation: str | None = None,
    disposal_nature: str | None = None,
    description: str | None = None,
    pdf_path: str | None = None,
    available_languages: list[str] = list(),
    pdf_exists: bool | None = None,
    source: str = "archive",
    year: int | None = None,
)

Bases: _Serializable

A delivered judgment, source-agnostic.

Populated by the archive client (parquet metadata) and, in later phases, by the live judgment-search clients via a federated facade. Fields that don't apply to a given source are left None / empty.

JudgmentResult dataclass 

JudgmentResult(
    title: str,
    court_name: str,
    case_number: str = "",
    judgment_date: date | None = None,
    judges: list[str] = list(),
    pdf_url: str = "",
    pdf_bytes: bytes | None = None,
    citation: str = "",
    bench_type: str = "",
    source_url: str = "",
    source_id: str = "",
    metadata: dict = dict(),
)

Bases: _Serializable

A judgment from the judgment search portal.

CaseInfo dataclass 

CaseInfo(
    case_number: str,
    case_type: str,
    cnr_number: str = "",
    filing_number: str = "",
    registration_number: str = "",
    registration_date: date | None = None,
    petitioner: str = "",
    respondent: str = "",
    status: str = "",
    court_name: str = "",
    judges: list[str] = list(),
    next_hearing_date: date | None = None,
)

Bases: _Serializable

Basic case metadata from a search result.

CaseOrder dataclass 

CaseOrder(
    order_date: date,
    order_type: str,
    judge: str = "",
    pdf_url: str = "",
    pdf_bytes: bytes | None = None,
    order_text: str = "",
    neutral_citation: str = "",
)

Bases: _Serializable

A single order/judgment attached to a case.

CauseListPDF dataclass 

CauseListPDF(
    serial_number: int,
    bench: str,
    cause_list_type: str = "",
    pdf_url: str = "",
    pdf_bytes: bytes | None = None,
)

Bases: _Serializable

A cause list PDF from HC Services.

The portal returns a table of PDF links, one per bench/judge. Each entry contains the bench name, list type, and a URL to the PDF.

CauseListEntry dataclass 

CauseListEntry(
    serial_number: int,
    case_number: str,
    case_type: str = "",
    petitioner: str = "",
    respondent: str = "",
    advocate_petitioner: str = "",
    advocate_respondent: str = "",
    court_number: str = "",
    judge: str = "",
    listing_date: date | None = None,
    item_number: str = "",
)

Bases: _Serializable

An entry from a court's cause list (daily schedule).

Note: HC Services returns cause lists as PDFs per bench/judge. Use :class:CauseListPDF for the actual portal response. This model is retained for parsed/structured cause list data.

SearchResult dataclass 

SearchResult(
    items: list[
        CaseInfo | JudgmentResult | CauseListEntry
    ] = list(),
    total_count: int = 0,
    page: int = 1,
    page_size: int = 10,
    has_next: bool = False,
)

Bases: _Serializable

Paginated search result container.

to_dict 

to_dict(*, exclude_none: bool = False) -> dict[str, Any]

Override to properly serialize nested items.

Source code in src/bharat_courts/models.py 
245
246
247
248
249
250
251
252
253
254
255
def to_dict(self, *, exclude_none: bool = False) -> dict[str, Any]:
    """Override to properly serialize nested items."""
    result = {
        "total_count": self.total_count,
        "page": self.page,
        "page_size": self.page_size,
        "has_next": self.has_next,
        "total_pages": self.total_pages,
        "items": [item.to_dict(exclude_none=exclude_none) for item in self.items],
    }
    return result

Court dataclass 

Court(
    name: str,
    code: str,
    state_code: str,
    court_type: CourtType,
    bench: str | None = None,
    judgment_code: str = "",
)

Bases: _Serializable

An Indian court with its eCourts identifiers.

judgment_compound_code property 

judgment_compound_code: str

Compound code for judgments portal: {judgment_code}~{state_code}.

CourtType

Bases: str, Enum