ahbicht.models package

Submodules

ahbicht.models.categorized_key_extract module

Contains the CategorizedKeyExtract and a schema for (de)serialization.

class ahbicht.models.categorized_key_extract.CategorizedKeyExtract(*, hint_keys: list[str] = <factory>, format_constraint_keys: list[str] = <factory>, requirement_constraint_keys: list[str] = <factory>, package_keys: list[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^\d+P$)]] = <factory>, time_condition_keys: list[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^UB(?:1|2|3)$)]] = <factory>)[source]

Bases: BaseModel

A Categorized Key Extract contains those condition keys that are contained inside an expression. For expressions (that do not contain any unresolved package) it’s possible to pre-generate all possible outcomes of a content evaluation. CategorizedKeyExtract is also the answer to the question: ‘Which information do I need to provide in a ContentEvaluationResult in order to evaluate a given expression?’

format_constraint_keys: list[str]: list of keys for which you’ll need to provide EvaluatedFormatConstraints

generate_possible_content_evaluation_results() → list[ContentEvaluationResult][source]: A categorized key extract allows generating nearly all possible content evaluation results, except for hints, error messages, resolving packages.

hint_keys: list[str]: list of keys for which you’ll need to provide hint texts in a ContentEvaluationResult

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

package_keys: list[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^\d+P$)]]: list of packages that need to be resolved (additionally)

requirement_constraint_keys: list[str]: list of keys for which you’ll need to provide ConditionFulfilledValues

sanitize() → None[source]: Sanitize the result (remove duplicates, sort keys)

time_condition_keys: list[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^UB(?:1|2|3)$)]]: a list of time conditions, if present

ahbicht.models.categorized_key_extract.CategorizedKeyExtracts: alias of RootModel[list[CategorizedKeyExtract]]

ahbicht.models.condition_node_type module

contains the ConditionNodeType enum

class ahbicht.models.condition_node_type.ConditionNodeType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StrEnum

Possible types of condition nodes. The value is usually determined using the key of the respective condition node. For the descriptions of the different types see also the README.

FORMAT_CONSTRAINT = 'FORMAT_CONSTRAINT': A Format Constraint (FC) is what edi@energy refers to as “Formatbedingung”. Other than requirement constraints (RC) format constraints do not refer to a data constellation in the edifact message as a whole (or at least parts of it) but to the value used at the place where the format constraint is used.

HINT = 'HINT': A Hint is a node whose text/description starts with “Hinweis”. It’s a text that cannot be interpreted automatically.

PACKAGE = 'PACKAGE': A package is an abbreviation for an expression.

PACKAGE_REPEATABILITY = 'PACKAGE_REPEATABILITY': Package Repeatablity for resolved package nodes in tree

REPEATABILITY_CONSTRAINT = 'REPEATABILITY_CONSTRAINT': Repeatability Constraints are what edi@energy refers to as “Wiederholbarkeiten”. They describe how often you may insert segment (groups) into a message (e.g. min. 1 but max 10 times).

REQUIREMENT_CONSTRAINT = 'REQUIREMENT_CONSTRAINT': A Requirement Constraint (RC) is what edi@energy refers to as “Voraussetzung”. It describes a data constellation that might (or might not) occur in a edifact message.

ahbicht.models.condition_nodes module

This module contains the abstract class ConditionNode, which specifies the nodes of the parsed tree. The type of the subclass is the decisive factor on how the respective node is handled in the context of the compositions it is used in. There are three possible input nodes (RequirementConstraint, Hint and FormatConstraint) and the EvaluatedComposition node which results from a combination of two nodes (of all possible types).

The used terms are defined in the README_conditions.md.

class ahbicht.models.condition_nodes.ConditionFulfilledValue(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Possible values to describe the state of a condition in the condition_fulfilled attribute of the ConditionNodes.

FULFILLED = 'FULFILLED': if condition is fulfilled

NEUTRAL = 'NEUTRAL': a hint or unevaluated format constraint which does not have a status of being fulfilled or not

UNFULFILLED = 'UNFULFILLED': if condition is not fulfilled

UNKNOWN = 'UNKNOWN': if it cannot be checked if condition is fulfilled (e.g. “Wenn vorhanden”)

class ahbicht.models.condition_nodes.ConditionNode(*, conditions_fulfilled: ConditionFulfilledValue)[source]

Bases: BaseModel

This abstract class specifies the nodes of the parsed tree. The type of the subclass is the decisive factor on how the respective node is handled in the context of the compositions it is used in.

conditions_fulfilled: ConditionFulfilledValue

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.EvaluatedComposition(*, conditions_fulfilled: ConditionFulfilledValue, hint: str | None = None, format_constraints_expression: str | None = None)[source]

Bases: ConditionNode

Node which is returned after a composition of two nodes is evaluated.

format_constraints_expression: str | None: an expression that consists of (initially unevaluated) format constraints that the evaluated field needs to obey

hint: str | None: text from hints/notes

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.EvaluatedFormatConstraint(*, format_constraint_fulfilled: bool, error_message: str | None = None)[source]

Bases: BaseModel

This class is the base class of all evaluated format constraints. They are used in the context of the Mussfeldprüfung after the format constraints are evaluated to see if the format constraint expression is fulfilled or not.

error_message: str | None

format_constraint_fulfilled: bool

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.FormatConstraint(*, conditions_fulfilled: ConditionFulfilledValue, condition_key: str)[source]

Bases: ConditionNode

This class is the base class of all format constraints. FormatConstraints describe that data have to obey certain rules, meaning those conditions with an outcome that does not change whether data are obligatory or not but validates existing data.

condition_key: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.Hint(*, conditions_fulfilled: ConditionFulfilledValue = ConditionFulfilledValue.NEUTRAL, condition_key: str, hint: str)[source]

Bases: ConditionNode

A so called ‘Hinweis’, just a hint, even if it is worded like a condition, e.g. “Hinweis: ‘Es ist der alte MSB zu verwenden’”

condition_key: str

conditions_fulfilled: ConditionFulfilledValue

hint: str: an informatory text

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.RequirementConstraint(*, conditions_fulfilled: ConditionFulfilledValue, condition_key: str)[source]

Bases: ConditionNode

Bedingung, with a requirement constraint, e.g. “falls SG2+IDE+CCI == EHZ”

condition_key: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.condition_nodes.UnevaluatedFormatConstraint(*, conditions_fulfilled: ConditionFulfilledValue = ConditionFulfilledValue.NEUTRAL, condition_key: str)[source]

Bases: FormatConstraint

This class is the base class of all unevaluated format constraints. They are used in the context of the Mussfeldprüfung where the constraints are collected but not evaluated yet.

conditions_fulfilled: ConditionFulfilledValue

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ahbicht.models.content_evaluation_result module

This module contains a class to store _all_ kinds of content evaluation results.

class ahbicht.models.content_evaluation_result.ContentEvaluationResult(*, hints: dict[str, str | None] = <factory>, format_constraints: dict[str, ~ahbicht.models.condition_nodes.EvaluatedFormatConstraint], requirement_constraints: dict[str, ~ahbicht.models.condition_nodes.ConditionFulfilledValue], packages: dict[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^\d+P$)], str] | None = None, id: ~uuid.UUID | None = None)[source]

Bases: BaseModel

A class that holds the results of a full content evaluation (meaning all hints, requirement constraints and format constraints have been evaluated)

format_constraints: dict[str, EvaluatedFormatConstraint]: maps the key of a format constraint to the respective evaluation result

hints: dict[str, str | None]: maps the key of a hint (e.g. “501” to a hint text)

id: UUID | None: optional guid

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

packages: dict[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^\d+P$)], str] | None: maps the key of a package (e.g. ‘123’) to the respective expression (e.g. ‘[1] U ([2] O [3])’

requirement_constraints: dict[str, ConditionFulfilledValue]: maps the key of a requirement_constraint to the respective evaluation result

ahbicht.models.enums module

Enums used in AHB and condition expressions.

class ahbicht.models.enums.LogicalOperator(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StrEnum

Logical operators connect two tokens.

LAND = 'U': logical AND, also denoted as “∧”, used in and_composition

LOR = 'O': logical OR, also denoted as “∨”, used in or_composition

XOR = 'X': logical excluxive OR (XOR), also denoted as “⊻”, used in xor_composition

class ahbicht.models.enums.ModalMark(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StrEnum

A modal mark describes if information are obligatory or not. The German term is “Merkmal”. The modal marks are defined by the EDI Energy group (see edi-energy.de → Dokumente → Allgemeine Festlegungen). The modal mark stands alone or before a condition expression. It can be the start of several requirement indicator expressions in one AHB expression.

KANN = 'KANN': German term for “Can”. Optional

MUSS = 'MUSS': German term for “Must”. Is required for the correct structure of the message. If the following condition is not fulfilled, the information must not be given (“must not”)

SOLL = 'SOLL': German term for “Should”. Is required for technical reasons. Always followed by a condition. If the following condition is not fulfilled, the information must not be given.

class ahbicht.models.enums.PrefixOperator(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StrEnum

Operator which does not function to combine conditions, but as requirement indicator. It stands alone or in front of a condition expression. Please find detailed descriptions of the operators and their usage in the “Allgemeine Festlegungen”. Note that with MaKo2022 introced 2022-04-01 the “O” and “U” prefix operators will be deprecated. Refer to the “Allgemeine Festlegungen” valid up to 2022-04-01 for deprecated “O” and “U”.

O = 'O': The “O” operator means that at least one out of multiple possible qualifiers/codes has to be given. This is typically found when describing ways to contact a market partner (CTA): You can use email or phone or fax but you have to provide at least one of the given possibilities. The usage of “O” as a prefix operator is deprecated since 2022-04-01. Note that “O” can also be used as a “logical or” (aka “lor”) operator in condition expressions. The prefix operator works differently from the logical operator in condition expressions! The usage of “O” as logical operator is also deprecated since 2022-04-01. It will be replaced with the “∨” symbol.

U = 'U': The “U” operator means that all provided qualifiers/codes have to be used. The usage of “U” as a prefix operator is deprecated since 2022-04-01. Note that “U” can also be used as a “logical and” (aka “land”) operator in condition expressions. The prefix operator works differently from the logical operator in condition expressions! The usage of “U” as logical operator is also deprecated since 2022-04-01. It will be replaced with the “∧” symbol.

X = 'X': The “X” operator. See “Allgemeine Festlegungen” Kapitel 6.8.1. Usually this just means something is required or required under circumstances defined in a trailing condition expression. It shall be read as “exclusive or” regarding how qualifiers/codes shall be used from a finite set. Note that “X” can also be used as “logical exclusive or” (aka “xor”) operator in condition expressions. The prefix operator works differently from the logical operator in condition expressions! The usage of “X” as logical operator is deprecated since 2022-04-01. It will be replaced with the “⊻” symbol.

ahbicht.models.enums.RequirementIndicator

A Requirement Indicator is either the Merkmal ModalMark or the PrefixOperator of the data element/data element group/segment/segment group at which it is used.

alias of PrefixOperator | ModalMark

ahbicht.models.evaluation_results module

This module contains the classes for the evaluation results. A “result” is the outcome of an evaluation. It requires actual data to be present.

class ahbicht.models.evaluation_results.AhbExpressionEvaluationResult(*, requirement_indicator: PrefixOperator | ModalMark, requirement_constraint_evaluation_result: RequirementConstraintEvaluationResult, format_constraint_evaluation_result: FormatConstraintEvaluationResult)[source]

Bases: BaseModel

A class for the result of an ahb expression evaluation.

format_constraint_evaluation_result: FormatConstraintEvaluationResult

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

requirement_constraint_evaluation_result: RequirementConstraintEvaluationResult

requirement_indicator: PrefixOperator | ModalMark

class ahbicht.models.evaluation_results.FormatConstraintEvaluationResult(*, format_constraints_fulfilled: bool, error_message: str | None = None)[source]

Bases: BaseModel

A class for the result of the format constraint evaluation.

error_message: str | None: All error messages that lead to not fulfilling the format constraint expression

format_constraints_fulfilled: bool: true if data entered obey the format constraint expression

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.evaluation_results.RequirementConstraintEvaluationResult(*, requirement_constraints_fulfilled: bool | None, requirement_is_conditional: bool | None, format_constraints_expression: str | None = None, hints: str | None = None)[source]

Bases: BaseModel

A class for the result of the requirement constraint evaluation.

format_constraints_expression: str | None

hints: str | None

‘ID der Messlokation’”

Type:: Hint text that should be displayed in the frontend, e.g. “[501] Hinweis

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

requirement_constraints_fulfilled: bool | None: true if condition expression in regard to requirement constraints evaluates to true

requirement_is_conditional: bool | None: true if it is dependent on requirement constraints; None if there are unknown condition nodes left

ahbicht.models.mapping_results module

This module contains classes that are returned by mappers, meaning they contain a mapping.

class ahbicht.models.mapping_results.ConditionKeyConditionTextMapping(*, edifact_format: EdifactFormat, condition_key: str, condition_text: str | None = None)[source]

Bases: BaseModel

maps a condition from a specified EDIFACT format onto a text as it is found in the AHB.

condition_key: str: the key of the condition without square brackets; e.g. ‘78’

condition_text: str | None: the description of the condition as in the AHB; None if unknown; e.g. ‘Wenn SG4 STS+7++E02 (Transaktionsgrund: Einzug/Neuanlage) nicht vorhanden’.

edifact_format: EdifactFormat: the format in which the condition is used; e.g. ‘UTILMD’

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ahbicht.models.mapping_results.PackageKeyConditionExpressionMapping(*, edifact_format: EdifactFormat, package_key: str, package_expression: str | None = None)[source]

Bases: BaseModel

maps a package key from a specified EDIFACT format onto a (not yet parsed) condition expression as it is found in the AHB.

edifact_format: EdifactFormat: the format in which the package is used; e.g. ‘UTILMD’

has_been_resolved_successfully() → bool[source]: return true iff the package has been resolved successfully

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

package_expression: str | None: the expression for which the package is a shortcut; None if unknown e.g. ‘[20] ∧ [244]’

package_key: str: the key of the package without square brackets but with trailing P; e.g. ‘10P’

class ahbicht.models.mapping_results.Repeatability(*, min_occurrences: int, max_occurrences: int | Literal['n'])[source]

Bases: BaseModel

describes how often a segment/code must be used when a “repeatability” is provided with packages

is_optional() → bool[source]: returns true if the package used together with this repeatability is optional

max_occurrences: int | Literal['n']: how often the segment/code may be repeated at most (upper, inclusive bound). This is inclusive meaning that [123P0..1] leads to max_occurrences==1

min_occurrences: int: how often the segment/code has to be repeated (lower, inclusive bound); may be 0 for optional packages

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ahbicht.models.mapping_results.check_max_greater_or_equal_than_min(instance: Repeatability) → None[source]: assert that 0<=min<max and not both min and max are 0

Module contents

this is a subpackage that contains all models used by ahbicht.