aeat.domain.categories._proportionality module

Proportionality and explainability primitives for category profiles.

Defines the closed enums and strict pydantic models that encode how a spending category is deducted on the autónomo filings, plus the citation chain back to the relevant authority that makes each rule explainable. Every ProportionalityRule carries at least one CategoryCitation; the consistency rules between kind-specific fields (fixed_pct, default_ratio, statutory_cap_*) are enforced by the model validator.

class CategoryCitationSource(*values)[source]

Bases: StrEnum

Allowed citation sources for explainable category profiles.

Variables:

  • MANUAL_RENTA – AEAT Manual práctico Renta.

  • MANUAL_IVA – AEAT Manual práctico IVA.

  • LEY_IRPF – Ley del Impuesto sobre la Renta de las Personas Físicas.

  • REGLAMENTO_IRPF – Reglamento del IRPF.

  • AEAT_HELP – AEAT online help / portal text.

MANUAL_RENTA
MANUAL_IVA
LEY_IRPF
REGLAMENTO_IRPF
AEAT_HELP
class CategoryCitation(**data)[source]

Bases: _ProportionalityStrictFrozenModel

Traceable citation backing one category or proportionality rule.

Variables:

  • source – Originating CategoryCitationSource.

  • reference – Human-readable document reference (title, edition, BOE number).

  • locator – Section, article, or page locator within the referenced document.

  • url – Canonical URL where the citation can be checked.

  • quote – Authoritative Spanish-language quote backing the rule.

Parameters:
source: CategoryCitationSource
reference: str
locator: str
url: AnyHttpUrl
quote: tr
parse_http_url(value)[source]

Parse a string into a statically typed AnyHttpUrl.

Parameters:

value (str) – Raw HTTP / HTTPS URL string.

Return type:

AnyHttpUrl

Returns:

A validated pydantic.AnyHttpUrl.

class ProportionalityKind(*values)[source]

Bases: StrEnum

Supported proportionality kinds for downstream evaluator engines.

Variables:

  • FULL_DEDUCTIBLE – Fully deductible against the activity.

  • FIXED_PERCENTAGE – Deductible at a fixed percentage; requires fixed_pct.

  • USAGE_RATIO_PERSONAL – Deductible at a personal-usage ratio chosen by the taxpayer; may carry default_ratio.

  • USAGE_RATIO_HOME_AREA – Deductible at the home-office area ratio; may carry default_ratio.

  • STATUTORY_CAP – Capped by a statutory daily or annual limit; requires the matching statutory_cap_* fields.

  • NON_DEDUCTIBLE – Not deductible against the activity.

FULL_DEDUCTIBLE
FIXED_PERCENTAGE
USAGE_RATIO_PERSONAL
USAGE_RATIO_HOME_AREA
STATUTORY_CAP
NON_DEDUCTIBLE
REQUIRES_EXCLUSIVE_USE
class StatutoryCapPeriod(*values)[source]

Bases: StrEnum

Supported statutory-cap accounting periods.

Variables:

  • DAY – Cap applies per day.

  • YEAR_PER_PERSON – Cap applies per year per covered person.

DAY
YEAR_PER_PERSON
class StatutoryCapVariant(**data)[source]

Bases: _ProportionalityStrictFrozenModel

One legally distinct daily cap inside a statutory-cap rule.

Parameters:
id: str
label: tr
statutory_cap_eur_per_day: Decimal
class ProportionalityRule(**data)[source]

Bases: _ProportionalityStrictFrozenModel

Deductibility and proportionality rule for one spending category.

Variables:

  • kind – One of ProportionalityKind.

  • fixed_pct – Required when kind is ProportionalityKind.FIXED_PERCENTAGE; otherwise must be None.

  • default_ratio – Optional default usage ratio; only valid for usage-ratio kinds.

  • statutory_multiplier – Optional statutory factor applied on top of the operator-chosen usage ratio. Only valid for usage-ratio kinds. The canonical example is the LIRPF Art. 30.2 rule 5 (Ley 6/2017, BOE-A-2017-12544) 0.30 multiplier applied to suministros (utility) costs of the habitual vivienda when the operator deducts under estimacion directa: effective_deductible_pct = operator_chosen_ratio * statutory_multiplier. When None no statutory factor is applied (equivalent to Decimal("1")); the operator’s chosen ratio is the effective deductible percentage.

  • statutory_cap_eur_per_day – Daily statutory cap; only valid for ProportionalityKind.STATUTORY_CAP.

  • statutory_cap_eur – Generic statutory cap amount; only valid for ProportionalityKind.STATUTORY_CAP and must be paired with statutory_cap_period.

  • statutory_cap_period – StatutoryCapPeriod that the generic cap applies over; required when statutory_cap_eur is set.

  • statutory_cap_variants – Daily statutory caps selected by a legally relevant condition.

  • citations – At least one CategoryCitation proving the rule.

  • notes – Authoritative Spanish-language notes describing the rule.

Parameters:
kind: ProportionalityKind
fixed_pct: Decimal | None
default_ratio: Decimal | None
statutory_multiplier: Decimal | None
statutory_cap_eur_per_day: Decimal | None
statutory_cap_eur: Decimal | None
statutory_cap_period: StatutoryCapPeriod | None
statutory_cap_variants: tuple[StatutoryCapVariant, ...]
citations: tuple[CategoryCitation, ...]
notes: tr
effective_usage_ratio(rule, chosen_ratio)[source]

Return the legally-effective deductible percentage for chosen_ratio.

Applies the rule’s statutory_multiplier on top of the operator- chosen usage ratio. Only meaningful for usage-ratio kinds; raises when called on a non-usage-ratio rule (the caller is responsible for routing rules to the right evaluator).

Parameters:

  • rule (ProportionalityRule) – A ProportionalityRule of a usage-ratio kind.

  • chosen_ratio (Decimal) – The operator’s stored usage ratio (typically derived from censo office_m2 / total_m2 for HOME_AREA kinds, or a personal-use proportion for PERSONAL kinds).

Return type:

Decimal

Returns:

chosen_ratio * (rule.statutory_multiplier or Decimal("1")).

Raises:

CategoryValidationError – When rule.kind is not a usage-ratio kind.