Citation Date Parser

citation-date is a Python library for parsing and normalizing dates from Philippine legal citations, including dockets, reports, and other references. It handles common typos and multiple date formats with US and UK variants. It is eventually used by the dataset employed in LawSQL.

It is deliberately corpus-driven: the grammar preserves observed formatting damage in Supreme Court citation material without trying to guess unrecorded OCR spellings.

Upgrading from 0.2.1? Read the 1.0 release notes for the behavior changes and before/after examples.

Purpose

The library is designed to:

• Extract dates from text commonly found in legal documents such as Philippine Supreme Court reports (SCRA) and dockets (G.R. No. ...).
• Handle both US (Month Day, Year) and UK (Day Month Year) date formats.
• Normalize dates to standard formats (%B %d, %Y or datetime.date).
• Support dates enclosed in parentheses () or brackets [], and in raw strings.
• Provide regex patterns and utility functions for downstream processing in other citation libraries.

Key Components

Regex Patterns

US/UK Date Patterns

from citation_date import uk_pattern, us_pattern

assert us_pattern.search("Dec. 1, 2000")
assert uk_pattern.search("1Dec. 2000")

These patterns detect date candidates with compact forms, ordinary punctuation, and the documented duplicate-comma UK variant. They do not match inside a larger alphanumeric token.

Report Dates

• REPORT_DATE_REGEX matches dates in citations like 1 SCRA 200 (1Dec. 2000).
• Supports naked dates, bracketed [Dec. 1, 2000], or parenthesis (Dec. 1, 2000).

Docket Dates

• DOCKET_DATE_REGEX matches docket-specific dates such as G.R. No. 12345, Dec,1, 2000.
• DOCKET_DATE_FORMAT standardizes formatting to %b. %d, %Y.

Decoding behavior

decode_date() returns the first calendar-valid full date in the text as %B %d, %Y, or as datetime.date when is_output_date_object=True. Unsupported syntax, impossible calendar dates, and year-only report values return None. Compile raw regex constants with re.I | re.X.

Documentation

See the documentation for the regex contracts, decoder reference, and usage paths.