cadrumo.domain.invoices.enums module¶

Registry-projected enumerations and tokens for invoice records.

Defines IvaRate and PaymentStatus. IvaRate is a registry-validated token only: the legal number behind a numeric slot is resolved from the IVA governed-fact authority at the explicit devengo date held by the composition boundary.

IvaRate keeps the typed token role for invoice records, and the IVA facade is the sole legal-grade authority for which rates existed when.

class IvaRate(value, *, _registry_validated=False)[source]¶

Bases: str

Opaque invoice-rate token projected from the dated slot catalogue.

The slot membership and its substrate semantics are governed by the IVA rate-slot fact. A token can only be constructed by the registry projection; the numeric rate itself remains a separate dated schedule fact.

Parameters:

value (str)
_registry_validated (bool)

Return type:

Self

classmethod from_registry(value)[source]¶

Materialise one token from the typed facts projection.

Return type:: Self
Parameters:: value (str)

property name: str¶: Return the persisted token for diagnostics and structured context.

property value: str¶: Return the persisted token for serialization boundaries.

class PaymentStatus(*values)[source]¶

Bases: StrEnum

Lifecycle states for an invoice payment.

Variables:

PAID – Settled in full.
PENDING – Awaiting payment within agreed terms.
PARTIALLY_PAID – Partially settled; remainder outstanding.
OVERDUE – Past the due date and still outstanding.
CANCELLED – Cancelled, regardless of whether previously paid.

PAID¶

PENDING¶

PARTIALLY_PAID¶

OVERDUE¶

CANCELLED¶

class InvoiceClass(value, *, _registry_validated=False)[source]¶

Bases: StrictRegistryToken

Opaque invoice-class token projected from the dated facts registry.

Parameters:

value (str)
_registry_validated (bool)

Return type:

Self

class InvoiceOperationDateRole(value, *, _registry_validated=False)[source]¶

Bases: StrictRegistryToken

Opaque operation-date role projected from the dated facts registry.

Parameters:

value (str)
_registry_validated (bool)

Return type:

Self

require_invoice_class(value, *, effective_date=None)[source]¶

Resolve an invoice-class token through the dated facts authority.

Return type:

InvoiceClass

Parameters:

value (object)
effective_date (date | None)

require_invoice_operation_date_role(value, *, effective_date=None)[source]¶

Resolve an operation-date role through the dated facts authority.

Return type:

InvoiceOperationDateRole

Parameters:

value (object)
effective_date (date | None)

invoice_class_ordinaria(*, effective_date=None)[source]¶

Return the registry-declared ordinary invoice-class token.

Return type:: InvoiceClass
Parameters:: effective_date (date | None)

invoice_class_simplificada(*, effective_date=None)[source]¶

Return the registry-declared simplified invoice-class token.

Return type:: InvoiceClass
Parameters:: effective_date (date | None)

invoice_class_rectificativa(*, effective_date=None)[source]¶

Return the registry-declared corrective invoice-class token.

Return type:: InvoiceClass
Parameters:: effective_date (date | None)

operation_performed_role(*, effective_date=None)[source]¶

Return the registry-declared performed-operation date role.

Return type:: InvoiceOperationDateRole
Parameters:: effective_date (date | None)

advance_payment_received_role(*, effective_date=None)[source]¶

Return the registry-declared advance-payment date role.

Return type:: InvoiceOperationDateRole
Parameters:: effective_date (date | None)

default_invoice_class(*, effective_date=None)[source]¶

Return the registry-declared default invoice-class token.

Return type:: InvoiceClass
Parameters:: effective_date (date | None)

class InvoiceLegalMentionDeclaration(token, phrase, provision, legal_refs, declares, expects_repercutido_line)[source]¶

Bases: object

One registry-projected fixed legal notice for an invoice.

Parameters:

token (str)
phrase (str)
provision (str)
legal_refs (tuple[str, ...])
declares (str | None)
expects_repercutido_line (bool)

token: str¶

phrase: str¶

provision: str¶

legal_refs: tuple[str, ...]¶

declares: str | None¶

expects_repercutido_line: bool¶

class InvoiceLegalMention(value, *, _registry_validated=False)[source]¶

Bases: str

Opaque token for a printed notice validated against the dated registry.

The legal-mention vocabulary is not a Python enum. A token can only be created by resolve_invoice_legal_mention(), after the selected registry variant has proved that its exact token is governed. This keeps invoice evidence typed while making missing or stale registry data fail closed instead of silently accepting an invented member.

Parameters:

value (str)
_registry_validated (bool)

Return type:

Self

classmethod from_registry(value)[source]¶

Materialise one token from the typed facts projection.

Return type:: Self
Parameters:: value (str)

invoice_legal_mention_declarations(on_date, *, authority=None)[source]¶

Project the dated legal-mention vocabulary and semantics from the registry.

Return type:

tuple[InvoiceLegalMentionDeclaration, ...]

Parameters:

on_date (date)
authority (GovernedFactSource | None)

resolve_invoice_legal_mention(value, on_date, *, authority=None)[source]¶

Return a typed invoice-mention token only when the registry accepts it.

Return type:

InvoiceLegalMention

Parameters:

value (str)
on_date (date)
authority (GovernedFactSource | None)

resolve_iva_rate_token(value, on_date, *, authority=None)[source]¶

Project one persisted rate token only when its registry membership exists.

Return type:

IvaRate

Parameters:

value (str)
on_date (date)
authority (GovernedFactSource | None)

iva_rate_slots_on(on_date)[source]¶

Return type:: tuple[IvaRate, ...]
Parameters:: on_date (date)

resolve_iva_rate_slot_fact(rate, on_date)[source]¶

Resolve a numeric slot’s exact authority fact with its provenance.

Zero is a permanent semantic slot whose IVA facade accepts the fraction on every date but which no flat rate fact can fully model; it consequently has no single rate-fact variant to return. Registry-declared nonnumeric slots likewise have no rate-fact variant.

Parameters:

rate (IvaRate)
on_date (date)

iva_rate_percentage(rate, on_date)[source]¶

Resolve rate to its fractional authority value at on_date.

The result is projected from the exact Spanish member-state, tier, role, and devengo-date fact. No rate is parsed from the persisted token.

Resolving through cadrumo.domain.iva.lookup.lookup_rate() instead would answer a different question and silently return a different number. That function deliberately skips supersedes_tier_default records, because a rate applying to only part of a tier’s supplies cannot say what the tier means – so a coexisting transitional line never computes from the ordinary tier default. cadrumo.domain.iva.lookup.rate_kinds_for_declared_rate() is the inverse authority built for this direction and does see those records.

Parameters:

rate (IvaRate) – IVA rate slot.
on_date (date) – The explicit devengo date at which the slot is resolved.

Return type:

Decimal | None

Returns:

The slot’s own percentage as a fractional Decimal; None for registry-declared nonnumeric slots, which carry no percentage.

Raises:

IvaRateNotFoundError – If the slot’s rate was not in force for its tier on on_date – a transitional slot used outside its statutory window, or a standing slot the registry no longer serves. Refusing is the point: substituting whatever the tier happens to mean that day would record a number the invoice never carried. When the rate table does not reach on_date FOR THAT TIER the refusal says so instead, because “not in force” would be a false claim about the law rather than a true one about our coverage. The reach differs between tiers, so the question is never whether the table reaches a date at all: it carries the general and reducido records well before the super-reducido ones. The registry-declared zero slot is never refused, because rate_kinds_for_declared_rate() answers ZERO on every date – Spain zero-rates on three permanent grounds the rate table cannot express, so its silence there is incomplete coverage rather than a statement that zero-rating was unlawful.

iva_rate_kind(rate, on_date=None)[source]¶

Return the substrate rate tier for an invoice line rate slot.

The out-of-scope slot has no OSS/IOSS rate tier because it is outside the taxable-supply universe; callers that need a Modelo 369 candidate should skip or reject it explicitly. Numeric and exempt slots return their corresponding IvaRateKind; a slot whose declared substrate kind is the catalogue’s non-rate token returns None.

Return type:

IvaRateKind | None

Parameters:

rate (IvaRate)
on_date (date | None)

resolve_iva_rate_slot(percentage, on_date)[source]¶

Resolve a printed percentage to its persisted slot at an explicit date.

Return type:

IvaRate

Parameters:

percentage (Decimal | None)
on_date (date)