Metadata-Version: 2.3
Name: citation-date
Version: 1.0.1
Summary: Regex date formula and decoder - Philippine Supreme Court Decisions
Requires-Python: >=3.14
Description-Content-Type: text/markdown

![Github CI](https://github.com/justmars/citation-date/actions/workflows/ci.yml/badge.svg)

# 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](https://lawsql.com).

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](https://justmars.github.io/citation-date/releases/) 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

```py
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](https://justmars.github.io/citation-date) for the
regex contracts, decoder reference, and usage paths.
