aeat.domain.contribuyente.inventory package¶

Inventory ledgers for actividad economica stock valuation.

Defines strict pydantic v2 records for tracking opening stock, period movements (purchases, COGS, counts), and closing stock per activity / year, plus the FIFO and weighted-average (PMP / coste medio) valuation engines required by LIS art. 17.1. LIFO is rejected explicitly via LIFOForbiddenError.

Public functions:: parse_valuation_method() — coerce user input into a ValuationMethod, refusing LIFO. compute_inventory_valuation() — value closing stock and COGS for one ledger. compute_inventory_variation() — signed Anexo D 0155 closing-minus-opening stock variation. compute_anexo_d_inventory_variation() — per-activity aggregation across multiple ledgers.

exception AmortizacionLedgerError(message=None, *, context=None, suggestion=None, translated_message=None)[source]¶

Bases: AeatError

Raised when an amortizacion ledger operation is invalid.

Parameters:

message (str | None)
context (dict[str, object] | None)
suggestion (str | None)
translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]¶

exception InventoryLedgerError(message=None, *, context=None, suggestion=None, translated_message=None)[source]¶

Bases: AeatError

Raised when an inventory ledger operation is invalid.

Parameters:

message (str | None)
context (dict[str, object] | None)
suggestion (str | None)
translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]¶

exception InventoryValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]¶

Bases: InventoryLedgerError, CoreValidationError

Raised when an inventory ledger fails Pydantic validation.

Inherits from CoreValidationError (which itself inherits from CoreError and ValueError) to participate in the shared CoreValidationError catch surface and remain compatible with pydantic validators.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
suggestion (str | None)
translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]¶

exception LIFOForbiddenError(method='lifo')[source]¶

Bases: InventoryLedgerError

Raised when a caller attempts LIFO inventory valuation.

LIS art. 17.1 does not admit LIFO for tax-purpose stock valuation in this regime; the message routes the operator to FIFO, PMP, or coste medio.

Parameters:: method (str)
Return type:: None

code: ClassVar[ErrorCode]¶

exception BasisCapExceededError(message=None, *, context=None, suggestion=None, translated_message=None)[source]¶

Bases: AmortizacionLedgerError

Raised when cumulative amortization would exceed cost basis.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
suggestion (str | None)
translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]¶

INVENTORY_SCHEMA_VERSION¶: Forward-compatible schema version stamped onto every record in this module.

class MovementKind(*values)[source]¶

Bases: StrEnum

Supported inventory movement kinds.

Variables:

OPENING – Stock present at the start of the period.
PURCHASE – Inbound inventory acquisition.
COGS – Cost-of-goods-sold consumption.
COUNT – Adjustment to the physical count, modelled as a synthetic COGS movement against the discrepancy.

OPENING¶

PURCHASE¶

COGS¶

COUNT¶

class ValuationMethod(*values)[source]¶

Bases: StrEnum

Supported inventory valuation methods.

FIFO¶

PMP¶

COSTE_MEDIO¶

class MovementRecord(**data)[source]¶

Bases: BaseModel

One inventory movement for an activity/year.

Variables:

movement_id – Stable natural key for the movement.
movement_date – Date the movement applies on.
kind – MovementKind.
sku – SKU / item identifier; defaults to "default" for single-SKU ledgers.
quantity – Movement quantity (strictly positive).
unit_cost – IVA-exclusive per-unit cost.
taxable_base – Invoice taxable base (IVA-exclusive).
iva_rate – IVA rate percentage (0-100).
iva_amount – Optional explicit IVA amount; when set must equal taxable_base * iva_rate / 100.
deductible_iva_ratio – Fraction of input IVA the contribuyente may deduct (0-1).
schema_version – Forward-compatible schema version. "1".

Parameters:

movement_id (str)
movement_date (date)
kind (MovementKind)
sku (str)
quantity (Decimal)
unit_cost (Decimal | None)
taxable_base (Decimal | None)
iva_rate (Decimal)
iva_amount (Decimal | None)
deductible_iva_ratio (Decimal)
schema_version (str)

movement_id: str¶

movement_date: date¶

kind: MovementKind¶

sku: str¶

quantity: Decimal¶

unit_cost: Decimal | None¶

taxable_base: Decimal | None¶

iva_rate: Decimal¶

iva_amount: Decimal | None¶

deductible_iva_ratio: Decimal¶

schema_version: str¶

property value: Decimal¶: Return the IVA-exclusive movement value.

property resolved_unit_cost: Decimal¶: Return the IVA-exclusive unit cost, falling back to taxable_base / quantity.

class StockLayer(**data)[source]¶

Bases: BaseModel

Remaining inventory quantity at one IVA-exclusive unit cost.

Variables:

sku – SKU / item identifier.
quantity – Layer quantity (strictly positive).
unit_cost – Per-unit cost the layer was acquired at.
source_movement_id – Stable id of the originating MovementRecord (or a synthetic id for opening stock and weighted-average pools).

Parameters:

sku (str)
quantity (Decimal)
unit_cost (Decimal)
source_movement_id (str)

sku: str¶

quantity: Decimal¶

unit_cost: Decimal¶

source_movement_id: str¶

class InventoryLedger(**data)[source]¶

Bases: BaseModel

Per-activity inventory ledger for one tax year.

Variables:

actividad_id – Activity identifier the ledger is keyed by.
year – Calendar year the ledger covers.
valuation_method – FIFO, PMP, or coste medio; LIFO is forbidden.
opening_stock – Aggregate IVA-exclusive opening valuation.
opening_layers – Per-layer breakdown of opening stock; when non-empty must value-balance with opening_stock.
closing_stock – Optional explicit closing valuation; when None it is derived from movements at compute time.
period_movements – Tuple of MovementRecord rows covering the period.
schema_version – Forward-compatible schema version. "1".

Parameters:

actividad_id (str)
year (int)
valuation_method (ValuationMethod)
opening_stock (Decimal)
opening_layers (tuple[StockLayer, ...])
closing_stock (Decimal | None)
period_movements (tuple[MovementRecord, ...])
schema_version (str)

actividad_id: str¶

year: int¶

valuation_method: ValuationMethod¶

opening_stock: Decimal¶

opening_layers: tuple[StockLayer, ...]¶

closing_stock: Decimal | None¶

period_movements: tuple[MovementRecord, ...]¶

schema_version: str¶

class InventoryLedgerDocument(**data)[source]¶

Bases: BaseModel

JSON document containing inventory ledgers.

Variables:

schema_version – Forward-compatible schema version. "1".
ledgers – Tuple of InventoryLedger rows.

Parameters:

schema_version (str)
ledgers (tuple[InventoryLedger, ...])

schema_version: str¶

ledgers: tuple[InventoryLedger, ...]¶

parse_valuation_method(raw)[source]¶

Parse a user-supplied valuation method and refuse LIFO explicitly.

Parameters:

raw (str) – User input (case- and separator-insensitive).

Return type:

ValuationMethod

Returns:

The matching ValuationMethod member.

Raises:

LIFOForbiddenError – When the input normalises to "lifo".
InventoryLedgerError – When the input matches no known method.

compute_inventory_variation(ledger, year)[source]¶

Compute signed Anexo D inventory variation for a ledger.

Returns closing stock minus opening stock for casilla 0155. If closing_stock is not supplied, it is derived via compute_inventory_valuation().

Parameters:

ledger (InventoryLedger) – Ledger to evaluate.
year (int) – Period year. The ledger is skipped when its year does not match.

Return type:

Decimal

Returns:

Signed closing-minus-opening valuation, quantised to cents.

class InventoryValuationResult(**data)[source]¶

Bases: BaseModel

Computed valuation outcome for an inventory ledger.

Variables:

closing_layers – Tuple of StockLayer rows surviving after period movements were applied.
closing_value – Aggregate closing valuation.
cogs_value – Cost-of-goods-sold for the period.
purchase_value – Aggregate value of PURCHASE movements during the period.

Parameters:

closing_layers (tuple[StockLayer, ...])
closing_value (Decimal)
cogs_value (Decimal)
purchase_value (Decimal)

closing_layers: tuple[StockLayer, ...]¶

closing_value: Decimal¶

cogs_value: Decimal¶

purchase_value: Decimal¶

compute_anexo_d_inventory_variation(year, actividad, *, ledgers=())[source]¶

Compute Anexo D normal casilla 0155 for one activity.

Parameters:

year (int) – Calendar year being filed.
actividad (str) – Activity identifier to filter ledgers by.
ledgers (tuple[InventoryLedger, ...]) – Ledgers to aggregate over.

Return type:

Decimal

Returns:

Sum of compute_inventory_variation() across matching ledgers, quantised to cents.

compute_inventory_valuation(ledger)[source]¶

Value closing stock and COGS using the ledger’s valuation method.

Dispatches to the FIFO or weighted-average implementation per InventoryLedger.valuation_method.

Parameters:: ledger (InventoryLedger) – Ledger to value.
Return type:: InventoryValuationResult
Returns:: InventoryValuationResult carrying the closing layers, closing valuation, COGS, and purchase totals.
Raises:: InventoryLedgerError – When valuation_method is not supported (defence-in-depth — should be unreachable as LIFO is rejected at parse time).