Date Utilities#

High-performance date manipulation and actuarial age/duration functions following Spanish and international conventions. Key capabilities:

Actuarial age — Age Last Birthday (ALB), Age Nearest Birthday (ANB), Age Next Birthday (ANEXT), and exact fractional age with daily resolution.
Duration calculations — days, complete calendar months, and fractional years (Actual/Actual ISDA or days/365.25 approximation).
Anniversary dates — generation of payment or projection date grids at any frequency (\(m\) = 1, 2, 3, 4, 6, 12, 24, 26, 52, 365; m=14 raises ValueError — use m=12 with separate extraordinary cash flows for the Spanish “14 pagas” scheme).
Date construction and arithmetic — end-of-month dates, durations, formatting, and robust parsing of integers (YYYYMMDD), ISO strings, European and US slash formats, and third-party types (datetime.date, pandas.Timestamp, numpy.datetime64, Polars).
Calendar utilities — leap year detection, days in month, days in year.

The active date_format setting in Config controls which input representations are accepted and how output is formatted.

Actuarial age#

Short-form aliases are exported directly in the top-level lactuca namespace:

Alias	Equivalent	Convention
`lactuca.alb`	`age_last_birthday`	ALB — floor to last integer year
`lactuca.anb`	`age_nearest_birthday`	ANB — round to nearest integer year
`lactuca.anextb`	`age_next_birthday`	ANEXTB — ceiling to next integer year

The name anextb (not anext) is used to avoid shadowing builtins.anext (Python 3.10+, used for async iteration).

Union type alias for all date-like inputs accepted by the public API.

Supported types:

int — 8-digit integer YYYYMMDD (e.g. 20240115)
str — ISO YYYY-MM-DD, European slash DD/MM/YYYY, European dash DD-MM-YYYY, or YMD slash YYYY/MM/DD
datetime.date or datetime.datetime
pandas.Timestamp
numpy.datetime64
Polars Date / Datetime scalars

The active date_format setting controls which string representations are accepted (e.g. ISO-only, European formats, etc.).