Errors¶
Every error the engine raises for an input, a data gap or a bundle defect
is a CcnlEngineError exported at the root, with a stable code (one of
ccnl_engine.errors.PUBLIC_ERROR_CODES), the feature and the ruleset it concerns and a
remediation. None of them is a ValueError: catch CcnlEngineError, or
one of its subclasses.
| Error | code |
Raised when |
|---|---|---|
InvalidInputError |
invalid_input |
An input or a facade argument is not what it must be; field names it, e.g. "PeriodFacts.events[2]" or "Employment.roles['x']" |
UnknownCcnlError |
unknown_ccnl |
The CCNL slug or code is not in the bundle |
UnknownLevelError |
unknown_level |
The level code is not a level of the CCNL |
MissingRuleError |
missing_rule |
The bundle has no value of a rule on the date a run reads it |
MissingRequiredFactError |
missing_required_fact |
A computation path needs a fact the caller did not supply |
UnsupportedTaxYearError |
unsupported_tax_year |
The bundle has no tax tables for the tax year of the payment |
OutOfScopeError |
out_of_scope |
The engine does not model the requested computation |
DataIntegrityError |
data_integrity |
A bundled file fails an integrity check, or a run breaks a state invariant |
Inputs are frozen dataclasses validated on construction by shared
validators: scalars by type and range (Decimal amounts finite and below
1E+9 in magnitude, int fields never a bool, dates never a
datetime, enums as a member or its string value), collections element by
element and stored as tuples or frozensets once valid. A missing fact that
lowers a result is a CalculationIssue whose fact is the name of the
public field to set (seniority, contribution_history, sector,
activity, agreement_signed_on, employment_income).
ccnl_engine.CcnlEngineError
¶
Bases: Exception
Base class for all ccnl-engine public errors.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
Stable machine-readable error code. |
|
feature |
Engine feature that triggered the error, e.g. |
|
ruleset |
CCNL slug when the error is scoped to a specific contract. |
|
remediation |
Suggested fix for the caller, or |
|
result_usable |
Whether a partial result is still valid for the caller. |
ccnl_engine.DataIntegrityError
¶
Bases: CcnlEngineError
Raised when a knowledge-base file fails an integrity check.
Covers hash mismatches, year/sector mismatches, and any other case where the bundled data is internally inconsistent. The engine cannot produce a trustworthy result when data integrity is violated.
ccnl_engine.InvalidInputError
¶
Bases: CcnlEngineError
Raised when caller-supplied inputs are invalid or incompatible.
Not a ValueError: like every public error it is caught as
:class:CcnlEngineError, so a caller never mistakes a bug of its own
(or of the engine) for rejected input.
Attributes:
| Name | Type | Description |
|---|---|---|
field |
Path of the rejected field within the input that rejected it,
e.g. |
ccnl_engine.MissingRequiredFactError
¶
Bases: CcnlEngineError
Raised when a computation path requires caller-supplied facts that are absent.
Some computation paths (e.g. domestic contribution brackets) require facts that cannot be derived from the CCNL or tax tables alone. The engine refuses to silently produce zero or approximate results; callers must supply the missing facts explicitly.
ccnl_engine.MissingRuleError
¶
Bases: CcnlEngineError
Raised when the knowledge bundle has no rule value on a date a run needs.
The date precedes the first value of the rule, or falls in a gap the
bundle declares (see :class:~ccnl_engine.agreement.validity.rules.SalaryGapKind).
Attributes:
| Name | Type | Description |
|---|---|---|
as_of |
Date the rule was read on. |
|
gap_kind |
Kind of the declared gap, |
|
detail |
Why the rule has no value on |
ccnl_engine.OutOfScopeError
¶
Bases: CcnlEngineError
Raised when a requested computation cannot be performed for this CCNL.
Raised when a caller requests a computation (e.g. apprenticeship pay) that
the CCNL does not model, and no partial result is meaningful. Features
that are modelled but not requested are reported as "excluded" in the
calculation scope without raising.
Attributes:
| Name | Type | Description |
|---|---|---|
reason |
Sub-reason code, e.g. |
ccnl_engine.UnknownCcnlError
¶
Bases: CcnlEngineError
Raised when a CCNL identifier cannot be resolved.
Attributes:
| Name | Type | Description |
|---|---|---|
ccnl_id |
The unresolvable identifier. |
|
suggestions |
Similar known identifiers, up to 5. |
ccnl_engine.UnknownLevelError
¶
Bases: CcnlEngineError
Raised when a level code cannot be resolved within a CCNL.
Attributes:
| Name | Type | Description |
|---|---|---|
level_code |
The unresolvable level code. |
|
ccnl_id |
The CCNL slug in which the lookup failed. |
ccnl_engine.UnsupportedTaxYearError
¶
Bases: CcnlEngineError
Raised when the knowledge bundle has no tax tables for a tax year.
The tax year of a run follows its payment date: a run paid in the next year can need tables the bundle does not ship yet.
Attributes:
| Name | Type | Description |
|---|---|---|
year |
The tax year with no bundled tables. |
|
sector |
Tax sector of the missing table, |
|
supported |
The tax years the bundle ships, empty when unknown. |