aeat.domain.contribuyente.family module

Typed personal/family profile records for Modelo 100 inputs.

The records in this module describe factual people and family-unit flags. They do not decide Modelo 100 legal treatment, minimum amounts, deduction eligibility, or casilla formulas; those remain registry-owned.

DescendantInfo, RentaDescendantProfile, and RentaAscendantProfile feed RentaFamilyProfile, whose helper methods derive Art. 58 minimum counts and Art. 81 maternity/guardería amounts from the factual profile records.

within_multi_year_applicability_window(entry_year, filing_year, *, following_periods)

Return whether filing_year is inside a multi-year applicability window.

A reusable primitive for autonomic deducciones that apply in the period of a triggering event (a nacimiento, an adopción, a rehabilitación, …) plus a fixed number of following periods. The window is the closed interval [entry_year, entry_year + following_periods]; following_periods = 0 yields a single-year window.

Parameters:

• entry_year (int) – Calendar year of the triggering event.

• filing_year (int) – The filing year whose eligibility is being tested.

• following_periods (int) – Count of periods after entry_year in which the deducción remains applicable. Must be non-negative.

Return type:

bool

class DescendantInfo(**data)

Bases: BaseModel

Structured per-descendant data for Art. 58 mínimo-por-descendientes.

This record drives the mínimo-por-descendientes calculation (casilla 0513) and the bajo-3-años supplement (Art. 58.2). It is intentionally richer than RentaDescendantProfile, which models official-form rows.

Fields

birth_date

Required date of birth.

adoption_date

Finalisation date of the adoption, or None for a biological child. When present it must be ≥ birth_date and ≤ today.

discapacidad_grado

0 = sin discapacidad, 33 = grado ≥ 33 % < 65 %, 65 = grado ≥ 65 %. A disabled descendant remains mínimo-eligible regardless of age.

convive_con_contribuyente

Whether the descendant cohabits with the taxpayer (Art. 58.1 condition).

custodia_compartida

Art. 61 LIRPF: when True, both progenitors share custody under a judicial or administrative arrangement. The mínimo-por-descendientes and the bajo-3-años supplement for this child are split 50 % between them (Art. 61 prorrata). Default False (sole custody / not applicable). Setting this flag on a non-cohabiting descendant has no additional effect because eligibility already fails.

meses_madre_trabajo_2024

Months the mother worked while this child was under 3 years old during the 2024 filing year. Used by Art. 81 LIRPF deducción maternidad: min(meses × 100, 1_200) per eligible child. Valid range: 0–12. Default 0 (no deducción contribution from this child).

gastos_guarderia_euros

Actual guardería / centro educación infantil autorizado expenses paid for this child (Art. 81 bis LIRPF). Integer euros, ≥ 0. Default 0 (no guardería expenses declared for this child).

nif

Optional NIF/NIE; validated for shape when present.

birth_date: date

adoption_date: date | None

discapacidad_grado: Literal[0, 33, 65] | None

convive_con_contribuyente: bool

custodia_compartida: bool

meses_madre_trabajo_2024: int

gastos_guarderia_euros: int

nif: str | None

age_at_year_end(filing_year)

Return the descendant’s age on 31 December of filing_year.

Return type:

int

Parameters:

filing_year (int)

is_eligible_ordinary(filing_year)

True when the descendant qualifies for the Art. 58.1 ordinary mínimo.

Eligibility: age < 25 at year-end OR any degree of discapacidad, AND cohabiting with the taxpayer.

Return type:

bool

Parameters:

filing_year (int)

is_eligible_menor_tres(filing_year)

True when the descendant qualifies for the Art. 58.2 bajo-3-años supplement.

Return type:

bool

Parameters:

filing_year (int)

entry_year()

Calendar year of the nacimiento/adopción event (deducción-window anchor).

Return type:

int

is_nacimiento_adopcion_eligible(filing_year, *, following_periods=2)

True when this descendant is inside the nacimiento/adopción window and cohabits.

The Madrid nacimiento/adopción deducción (DL 1/2010 art. 4) requires both that the parent cohabits with the child (“Solo tendrán derecho a practicar la deducción los padres que convivan con los hijos nacidos o adoptados”) and that the filing year falls inside the applicability window measured from the entry (nacimiento/adopción) year.

Return type:

bool

Parameters:

• filing_year (int)

• following_periods (int)

nacimiento_adopcion_prorrateo_share()

Return this descendant’s share of the deducción after prorrateo.

When the child cohabits with both parents and they file individually the Madrid manual splits the amount equally between the two declarations (”CUSTODIA_COMPARTIDA_PRORRATA_FACTOR” / Decimal("0.5")); otherwise the full amount accrues to this filer (Decimal("1")). custodia_compartida is the profile signal for the shared-cohabitation case that triggers the ÷2 prorrateo.

Return type:

Decimal

Parameters:

• birth_date (date)

• adoption_date (date | None)

• discapacidad_grado (Literal[0, 33, 65] | None)

• convive_con_contribuyente (bool)

• custodia_compartida (bool)

• meses_madre_trabajo_2024 (int)

• gastos_guarderia_euros (int)

• nif (str | None)

class RentaDescendantProfile(**data)

Bases: _RentaPersonProfileBase

One descendant row from the official Modelo 100 family section.

Parameters:

• tax_id (str | None)

• display_name (str | None)

• birth_date (date)

• disability_grade (str | None)

• death_date (date | None)

class RentaAscendantProfile(**data)

Bases: _RentaPersonProfileBase

One ascendant row from the official Modelo 100 family section.

Parameters:

• tax_id (str | None)

• display_name (str | None)

• birth_date (date)

• disability_grade (str | None)

• death_date (date | None)

• cohabiting_descendant_count (int | None)

cohabiting_descendant_count: int | None

class RentaFamilyProfile(**data)

Bases: BaseModel

Typed repeated family-member facts consumed by Modelo 100 bindings.

Parameters:

• schema_version (str)

• descendants (tuple[RentaDescendantProfile, ...])

• ascendants (tuple[RentaAscendantProfile, ...])

• descendientes (tuple[DescendantInfo, ...])

• cotizaciones_ss_madre_2024 (int)

schema_version: str

descendants: tuple[RentaDescendantProfile, ...]

ascendants: tuple[RentaAscendantProfile, ...]

descendientes: tuple[DescendantInfo, ...]

cotizaciones_ss_madre_2024: int

SS cotizaciones paid by the mother during 2024 (mirrors casilla 0013).

Used as the statutory cap for the Art. 81 bis guardería incremento: 0613 = min(gastos_guarderia_reales, hijos_menores_3 × 1000, cotizaciones_ss_madre_2024). Default 0 (cap not declared; guardería incremento will be zero).

property descendientes_count: int

Total number of DescendantInfo entries.

descendientes_menores_3_year_end(filing_year)

Count of eligible descendientes whose age at year-end < 3 (Art. 58.2).

Return type:

int

Parameters:

filing_year (int)

property descendientes_menores_3_2024: int

Count of descendants eligible for the bajo-3-años supplement in 2024.

Binding-compatible property (no argument) for the 2024 registry binding renta-2024-profile-descendientes-menores-3.

property gastos_guarderia_reales_2024: int

Sum of Art. 81 bis guardería expenses across eligible children under 3 in 2024.

Only children eligible for the bajo-3-años supplement (age < 3 at year-end 2024 AND cohabiting) contribute their gastos_guarderia_euros. Used as the gastos_reales term in the 0613 formula: min(gastos_guarderia_reales_2024, descendientes_menores_3_2024 × 1000, cotizaciones_ss_madre_2024).

descendientes_eligible_minimum(filing_year)

Count of descendientes eligible for the ordinary Art. 58.1 mínimo.

A descendant is eligible when age < 25 at year-end OR discapacidad > 0, and cohabiting with the taxpayer.

Return type:

int

Parameters:

filing_year (int)

custodia_compartida_count(filing_year)

Count of eligible descendientes with custodia_compartida=True.

Only eligible (Art. 58.1) and cohabiting descendants are counted; non-eligible ones carry no mínimo, so the prorrata has no effect.

Return type:

int

Parameters:

filing_year (int)

custodia_compartida_prorrata_factor(descendant, filing_year)

Return the Art. 61 LIRPF prorrata factor for one descendant.

Returns CUSTODIA_COMPARTIDA_PRORRATA_FACTOR (0.5, Art. 61 LIRPF) when descendant.custodia_compartida is True and the descendant is eligible for the mínimo, otherwise Decimal("1").

Return type:

Decimal

Parameters:

• descendant (DescendantInfo)

• filing_year (int)

minimo_descendientes_estatal(filing_year, *, birth_order_amounts, menor_tres_supplement)

Compute the Art. 58 mínimo por descendientes aggregate (casillas 0513/0514).

Ranks every Art. 58.1-eligible descendant (age < 25 at year-end, or any discapacidad grade, and cohabiting) by birth_date ascending — the eldest eligible descendant is “el primero”, matching the AEAT Renta manual’s birth-order reading of Art. 58.1’s “primero/segundo/tercero/ cuarto y siguientes” tranches. Each eligible descendant contributes:

• the birth-order tranche amount from birth_order_amounts (index 0 for the 1st, index 1 for the 2nd, … the last entry repeats for the 4th and every subsequent descendant, per Art. 58.1’s “cuarto y siguientes” wording);

• plus menor_tres_supplement when the descendant is also Art. 58.2-eligible (age < 3 at year-end);

• the sum is then multiplied by the descendant’s Art. 61.1ª LIRPF custodia-compartida prorrata factor (0.5 when custodia_compartida=True and eligible, else 1 — custodia_compartida_prorrata_factor()).

No within-year temporal prorrateo is applied: Art. 58 (in force since 01/01/2015, BOE-A-2014-12327) declares only the two numbered subsections above and no birth/adoption-date cutoff for descendientes; Art. 61’s temporal rules are scoped to a mid-year death (norma 4ª) and to ascendientes’ half-period residency (norma 5ª), neither of which applies here (see ADR modelo-100-minimo-descendientes-engine).

birth_order_amounts and menor_tres_supplement are registry money parameters the caller resolves per filing year; this domain method performs no euro-figure lookup of its own (aeat-schema-central-config).

Returns Decimal("0") when no descendant is Art. 58.1-eligible (including an empty descendientes tuple) — the legally correct zero for a childless filer, not an under-declaration.

Return type:

Decimal

Parameters:

• filing_year (int)

• birth_order_amounts (Sequence[Decimal])

• menor_tres_supplement (Decimal)

custodia_compartida_advisory(filing_year)

Return the translated Art. 61 prorrata advisory string, or None.

When at least one eligible descendant has custodia_compartida=True the returned string reads “Se ha aplicado prorrata 50 % (Art. 61 LIRPF) por custodia compartida en X descendientes.” Returns None when no prorrata is in effect.

Return type:

str | None

Parameters:

filing_year (int)

madrid_nacimiento_adopcion_eligible_count(filing_year)

Count of descendants inside the Madrid nacimiento/adopción window who cohabit.

The raw (unweighted) eligible count; madrid_nacimiento_adopcion_weighted_count applies the per-descendant prorrateo the registry cuantía is multiplied by.

Return type:

int

Parameters:

filing_year (int)

madrid_nacimiento_adopcion_weighted_count(filing_year)

Prorrateo-weighted eligible-descendant count for the Madrid deducción.

Each eligible descendant contributes its prorrateo share (1, or 0.5 under custodia compartida). The registry formula multiplies this weighted count by the per-child cuantía (721,70 € for 2023+ entries), so the per-descendant prorrateo the registry schema cannot express is embedded here — the Python/registry split the ADR mandates.

Return type:

Decimal

Parameters:

filing_year (int)

unidad_familiar_otros_miembros_base()

Base imponible of unidad-familiar members OTHER than the filer.

Framework primitive for the autonomic double income-limit gate (the unidad-familiar 61.860 € límite). For a monoparental/single filer the other members are the filer’s cohabiting children, whose own base imponible the profile does not hold and is treated as zero; the filer’s own base (casillas 0435 + 0460) is added by the registry formula. A conyugal unit’s spouse base is not persisted, so the derived-fact injector supplies this term only for the determinable single-filer case and the trigger stays advisory-only otherwise (fail-closed, no over-claim).

Return type:

Decimal

deduccion_maternidad_0611(filing_year)

Compute the Art. 81 LIRPF deducción maternidad for casilla 0611.

Formula: sum(min(meses_madre_trabajo_2024 × 100, 1_200)) for each descendant that is eligible for the bajo-3-años supplement (age < 3 at year-end AND cohabiting with the taxpayer).

Returns an integer euros amount (casilla 0611 carries no decimal places on the official form). Returns 0 when no eligible child has a non-zero meses_madre_trabajo_2024.

Return type:

int

Parameters:

filing_year (int)

incremento_guarderia_0613(filing_year)

Compute the Art. 81 LIRPF guardería incremento for casilla 0613.

Formula (Art. 81 LIRPF — incremento por gastos de custodia en guardería, NOT Art. 81 bis which covers familia numerosa / discapacidad):

min(gastos_guarderia_reales,
    hijos_menores_3 × INCREMENTO_GUARDERIA_POR_HIJO_CAP_EUR,
    cotizaciones_ss_madre_2024)

Only the 2024 filing year is supported by the profile fields (gastos_guarderia_euros and cotizaciones_ss_madre_2024); for other years, returns 0.

Returns an integer euros amount. Returns 0 when no eligible child has gastos_guarderia_euros > 0 or cotizaciones_ss_madre_2024 == 0.

Return type:

int

Parameters:

filing_year (int)

incremento_guarderia_advisory(filing_year)

Return a translated advisory string when 0613 can be auto-populated.

Returns None when the incremento is zero.

Return type:

str | None

Parameters:

filing_year (int)

deduccion_maternidad_advisory(filing_year)

Return a translated advisory string when 0611 can be auto-populated.

Returns None when no descendant under 3 carries meses_madre_trabajo_2024 > 0, i.e. the computation produces zero.

Return type:

str | None

Parameters:

filing_year (int)