Base types#

Core types exported from the lactuca top-level namespace.

TableKey#

class lactuca.TableKey(table_name: str, sex: str, cohort: int | None = None, duration: TableDurationKey | None = None, unisex_blend: float | None = None)#

Bases: NamedTuple

Immutable key identifying a single actuarial table instance.

Used as a dictionary key when __new__() is called with return_dict=True. The five fields together uniquely identify any table that Lactuca can construct.

Parameters:

  • table_name (str) – Repository name of the actuarial table (e.g. 'PASEM2020_Dec_1o').

  • sex (str) – Biological sex code: 'm' (male), 'f' (female), or 'u' (unisex blend).

  • cohort (int, optional) – Birth-year for generational (projected) tables. None for static period tables. Default is None.

  • duration (int or "ult", optional) – Select-table duration index, or "ult" for the ultimate segment. None for tables without a select period. Default is None. Validated by __new__(), not by TableKey itself — see Notes.

  • unisex_blend (float, optional) – Male weight in \([0, 1]\) used to build the unisex blend. None when sex != 'u'. Default is None.

Notes

  • TableKey is a NamedTuple and therefore hashable. It can be used as a dictionary key or set element without any extra configuration.

  • Equality and hashing are field-wise: two TableKey objects are equal when all five fields compare equal.

  • Passing unisex_blend=None explicitly is identical to omitting the argument — both produce the same key. This preserves backward compatibility when upgrading code that does not use unisex blending.

  • Float precision caveat: unisex_blend is stored as a Python float. Two blends that differ only in floating-point representation noise will produce different keys. Always pass the same literal (e.g. 0.5) to guarantee key consistency.

  • Manual construction: TableKey performs no validation on duration, cohort, or unisex_blend. Values such as an invalid duration string are stored as given and may fail to match keys from __new__() with return_dict=True, which validates those fields before building keys. Prefer return_dict=True or mirror its validation rules when constructing keys by hand.

Examples

Construct a minimal key (table name and sex only):

>>> from lactuca import TableKey
>>> k = TableKey('PASEM2020_Dec_1o', 'm')
>>> k.table_name, k.sex, k.cohort, k.duration, k.unisex_blend
('PASEM2020_Dec_1o', 'm', None, None, None)

Use as a dictionary key to retrieve table instances:

>>> d = {TableKey('T1', 'm'): 'inst_m', TableKey('T1', 'f'): 'inst_f'}
>>> d[TableKey('T1', 'm')]
'inst_m'

Keys with different unisex_blend values are not equal:

>>> TableKey('T1', 'u', None, None, 0.55) == TableKey('T1', 'u', None, None, 0.45)
False
cohort: int | None#

Alias for field number 2

duration: int | Literal['ult'] | None#

Alias for field number 3

sex: str#

Alias for field number 1

table_name: str#

Alias for field number 0

unisex_blend: float | None#

Alias for field number 4