ahbicht

Name	ahbicht JSON
Version	0.10.0 JSON
	download
home_page	None
Summary	Python Library to parse AHB expressions.
upload_time	2024-10-01 15:01:10
maintainer	None
docs_url	None
author	None
requires_python	>=3.9
license	MIT
keywords	ahb expressions parsing
VCS
bugtrack_url
requirements	attrs efoli inject lark marshmallow marshmallow-enum maus more-itertools packaging pytz
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            AHB Condition Expression Parser (AHBicht)
=========================================

|Unittests status badge| |Coverage status badge| |Linting status badge|
|Black status badge| |pypy status badge|

.. image:: https://raw.githubusercontent.com/Hochfrequenz/ahbicht/main/docs/_static/ahbicht-logo.png
   :target: https://ahbicht.readthedocs.io
   :align: right
   :alt: ahbicht logo
   :width: 150px

A python package that parses condition expressions from EDI\@Energy
Anwendungshandbücher (AHB). Since it's based on lark, we named the
module AHBicht.

What is this all about?
-----------------------

The German energy market uses
`EDIFACT <https://en.wikipedia.org/wiki/EDIFACT>`__ as an intercompany
data exchange format. The rules on how to structure and validate the
EDIFACT messages are written in

-  one **M**\ essage **I**\ mplementation **G**\ uide (MIG) per EDIFACT
   format (for example UTILMD or MSCONS)
-  one **A**\ nwendungs\ **h**\ and\ **b**\ uch (AHB,
   en. manual) per use case group (for example
   `GPKE <https://de.wikipedia.org/wiki/Gesch%C3%A4ftsprozesse_zur_Kundenbelieferung_mit_Elektrizit%C3%A4t>`__
   or *Wechselprozesse im Messwesen* (WiM))

According to the legislation for the German energy market, the
organisations in charge of maintaining the documents described above
(AHB and MIGs) are the
**B**\ undesverband **d**\ er **E**\ nergie-
und **W**\ asserwirtschaft (BDEW) and the
**B**\ undes\ **netza**\ gentur (BNetzA). They form a working
group named "Arbeitsgruppe EDI\@Energy". This work group publishes the
MIGs and AHBs on `edi-energy.de <https://edi-energy.de/>`__. The
documents are published as PDFs which is better than faxing them but far
from ideal.

The AHBs contain information on how to structure single EDIFACT
messages. To create messages that are valid according to the respective
AHB, you have to process information of the kind:
|UTILMD_AHB_WiM_3_1b_20201016.pdf page 90|

In this example: **This library parses the string
``Muss [210] U ([182] X ([90] U [183]))`` and allows determining whether
“Details der Prognosegrundlage” is an obligatory field according to the
AHB, iff the individual status of the conditions is given.** We call
this “expression evaluation”.

Note that determining the individual status of ``[210]``, ``[182]``,
``[90]`` and ``[183]`` itself (the so called “content evaluation”, see
below) is **not** within the scope of this parsing library.

Note also, that this library also parses the new convention using logical operators that becomes effective 2022-04-01 ("MaKo2022").
``Muss [210] ∧ ([182] ⊻ ([90] ∧ [183]))``.


Usage and Examples
------------------

Jupyter Notebook
~~~~~~~~~~~~~~~~
For a minimal working example on how what the library is used, check out `this Jupyter notebook <minimal_working_example.ipynb>`__.

Free to Use REST API
~~~~~~~~~~~~~~~~~~~~
You can also use our public REST API to parse condition expressions (other features will follow). Simply send a GET request with the condition expression as query parameter to:
`ahbicht.azurewebsites.net/api/ParseExpression?expression=[2] U ([3] O [4])[901] U [555] <https://ahbicht.azurewebsites.net/api/ParseExpression?expression=%5B2%5D%20U%20%28%5B3%5D%20O%20%5B4%5D%29%5B901%5D%20U%20%5B555%5D>`__

Easily Integrate AHBicht with Your Solution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to use AHBicht together with your own software, you can use the `JSON Schema files <json_schemas>`__ provided to kick start the integration.

There is a fully typed .NET client available: `AhbichtClient.NET <https://github.com/Hochfrequenz/AhbichtClient.net>`_

Code Quality / Production Readiness
-----------------------------------

-  The code has at least a 95% unit test coverage. ✔️
-  The code is rated 10/10 in pylint and type checked with mypy. ✔️
-  The code is `MIT licensed <LICENSE>`__. ✔️
-  There are only `few dependencies <requirements.in>`__. ✔️

Expression Evaluation / Parsing the Condition String
----------------------------------------------------

Evaluating expressions like ``Muss [59] U ([123] O [456])`` from the
AHBs by parsing it with the `parsing library
lark <https://lark-parser.readthedocs.io/en/latest/>`__ and
combining the parsing result with information about the state of
``[59]``, ``[123]``, ``[456]`` is called **expression evaluation**.
Determining the state of each single condition (f.e. ``[59]`` is
fulfilled, ``[123]`` is not fulfilled, ``[456]`` is unknown) for a given
message is part of the **content evaluation** (see next chapter).

If you’re new to this topic, please read `edi-energy.de → Dokumente →
Allgemeine
Festlegungen <https://www.edi-energy.de/index.php?id=38&tx_bdew_bdew%5Buid%5D=956&tx_bdew_bdew%5Baction%5D=download&tx_bdew_bdew%5Bcontroller%5D=Dokument&cHash=ae3c1bd6fe3f664cd90f5e94f9714e3e>`__
first. This document contains German explanations, how the Bedingungen
are supposed to be read.

Functionality
~~~~~~~~~~~~~

-  Expressions can contain single numbers e.g. ``[47]`` or numbers
   combined with ``U``/``O``/``X`` or ``∧``/``∨``/``⊻`` respectively which are translated to boolean
   operators ``and``/``or``/``exclusive or``, e.g. ``[45]U[2]`` or they
   can be combined **without** an operator, e.g. ``[930][5]`` in the
   case of FormatConstraints.
-  Expressions can contain random whitespaces.
-  Input conditions are passed in form of a ``ConditionNode``, see
   below.
-  Bedingungen/``RequirementConstraints`` with a boolean value,
   Hinweise/``Hints`` and Formatdefinitionen/``FormatConstraints`` are
   so far functionally implemented as the result returns if the
   condition expression is fulfilled and which Hints and
   FormatConstraints are relevant.
-  The boolean logic follows 'brackets ``( )`` before ``then_also``
   before ``and`` before ``or``'.
-  Hints and UnevaluatedFormatConstraints are implemented as ``neutral``
   element, so not changing the boolean outcome of an expression for the
   evaluation regarding the requirement constraints and raising errors
   when there is no sensible logical outcome of the expression.
-  A ``condition_fulfilled`` attribute can also take the value
   ``unknown``.
-  Brackets e.g. ``([43]O[4])U[5]``
-  Requirement indicators (i.e ``Muss``, ``Soll``, ``Kann``, ``X``,
   ``O``, ``U``) are separated from the condition expressions and also
   separated into single requirement indicator expressions if there are
   more than one (for modal marks).
-  ``Format Constraint Expressions`` that are returned after the
   requirement condition evaluation can now be parsed and evaluated.
-  Evaluate several modal marks in one ahb_expression: the first one
   that evaluates to fulfilled is the valid one.

In planning
^^^^^^^^^^^

-  Evaluate requirement indicators:

   -  Soll, Kann, Muss, X, O, U -> is_required, is_forbidden, etc…

Definition of terms
~~~~~~~~~~~~~~~~~~~

+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Term                                       | Description                                                                                                                                                                                                                                                                                                                                                     | Example                                                                                                 |
+============================================+=================================================================================================================================================================================================================================================================================================================================================================+=========================================================================================================+
| condition                                  | single operand                                                                                                                                                                                                                                                                                                                                                  | [53]                                                                                                    |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| condition_key                              | int or str, the number of the condition                                                                                                                                                                                                                                                                                                                         | 53                                                                                                      |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| operator                                   | combines two conditions                                                                                                                                                                                                                                                                                                                                         | U, O                                                                                                    |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| composition                                | two parts of an expression combined by an operator                                                                                                                                                                                                                                                                                                              | ([4]U[76])O[5] consists of an and_composition of [4] and [76] and an or_composition of [4]U[76] and [5] |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | used in the context of the parsing and evaluation of the expression                                                                                                                                                                                                                                                                                             |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| ahb expression                             | an expression as given from the ahb                                                                                                                                                                                                                                                                                                                             | X[59]U[53]                                                                                              |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | Consists of at least one single requirement indicator expression.                                                                                                                                                                                                                                                                                               | Muss[59]U([123]O[456])Soll[53]                                                                          |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | In case of several model mark expressions the first one will be evaluated and if not fulfilled, it will be continued with the next one.                                                                                                                                                                                                                         |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| single requirement indicator expression    | An expression consisting of exactly one requirement indicator and their respective condition expression.                                                                                                                                                                                                                                                        | Soll[53]                                                                                                |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | If there is only one requirement indicator in the ahb expression, then both expressions are identical.                                                                                                                                                                                                                                                          |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| condition expression                       | one or multiple conditions combined with or (in case of FormatConstraints) also without operators                                                                                                                                                                                                                                                               | [1]                                                                                                     |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | used as input for the condition parser                                                                                                                                                                                                                                                                                                                          | [4]O[5]U[45]                                                                                            |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| format constraint expression               | Is returned after the evaluation of the RequirementConstraints                                                                                                                                                                                                                                                                                                  | [901]X[954]                                                                                             |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | consist only of FormatConstraints                                                                                                                                                                                                                                                                                                                               |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| requirement indicator                      | The Merkmal/modal_mark or Operator/prefix_operator of the data element/data element group/segment/segment group.                                                                                                                                                                                                                                                | Muss, Soll, Kann, X, O, U                                                                               |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Merkmal / modal_mark                       | as defined by the EDI Energy group (see edi-energy.de → Dokumente → Allgemeine Festlegungen)                                                                                                                                                                                                                                                                    | Muss, Soll, Kann                                                                                        |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | Stands alone or before a condition expression, can be the start of several requirement indicator expressions in one ahb expression                                                                                                                                                                                                                              |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| prefix operator                            | Operator which does not function to combine conditions, but as requirement indicator.                                                                                                                                                                                                                                                                           | X, O, U                                                                                                 |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | Stands alone or in front of a condition expression.                                                                                                                                                                                                                                                                                                             |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| tree, branches, token                      | as used by lark                                                                                                                                                                                                                                                                                                                                                 |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| ConditionNode                              | Defines the nodes of the tree as they are passed, evaluated und returned.                                                                                                                                                                                                                                                                                       | RequirementConstraint, FormatConstraint, Hint, EvaluatedComposition, RepeatabilityConstraint            |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | There are different kinds of conditions (Bedingung, Hinweis, Format) as defined by the EDI Energy group (see edi-energy.de → Dokumente → Allgemeine Festlegungen) and also a EvaluatedComposition after a composition of two nodes is evaluated.                                                                                                                |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Bedingung / RequirementConstraint (rc)     | - are true or false, has to be determined                                                                                                                                                                                                                                                                                                                       | "falls SG2+IDE+CCI == EHZ"                                                                              |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | - keys between [1] and [499]                                                                                                                                                                                                                                                                                                                                    |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Wiederholbarkeit / RepeatabilityConstraint | - gives minimum and maximum occurrence                                                                                                                                                                                                                                                                                                                          | "Segmentgruppe ist mindestens einmal je SG4 IDE+24 (Vorgang) anzugeben"                                 |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | - keys between [2000] and [2499]                                                                                                                                                                                                                                                                                                                                |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Hinweis / Hint                             | - just a hint, even if it is worded like a condition                                                                                                                                                                                                                                                                                                            | "Hinweis: 'ID der Messlokation'"                                                                        |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | - keys from [500] onwards, starts with 'Hinweis:'                                                                                                                                                                                                                                                                                                               | "Hinweis: 'Es ist der alte MSB zu verwenden'"                                                           |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Formatdefinition / FormatConstraint (fc)   | - a constraint for how the data should be given                                                                                                                                                                                                                                                                                                                 | "Format: Muss größer 0 sein"                                                                            |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | - keys between [901] and [999], starts with 'Format:'                                                                                                                                                                                                                                                                                                           | "Format: max 5 Nachkommastellen"                                                                        |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
|                                            | Format Constraints are "collected" while evaluating the rest of the tree, meaning the evaluated composition of the Mussfeldprüfung contains an expression that consists only of format constraints.                                                                                                                                                             |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| UnevaluatedFormatConstraint                | A format constraint that is just "collected" during the requirement constraint evaluation. To have a clear separation of conditions that affect whether a field is mandatory or not and those that check the format of fields without changing their state it will become a part of the format_constraint_expression which is part of the EvaluatedComposition. |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| EvaluatableFormatConstraint                | An evaluatable FormatConstraint will (other than the UnevaluatedFormatConstraint) be evaluated by e.g. matching a regex, calculating a checksum etc. This happens after the Mussfeldprüfung. (details to be added upon implementing)                                                                                                                            |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| EvaluatedComposition                       | is returned after a composition of two nodes is evaluated                                                                                                                                                                                                                                                                                                       |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Package Resolver                           | a package resolver is a class that replaces package nodes in a tree with a sub tree that is derived from a package definition. Replacing package nodes with sub trees is referred to as "package expansion"                                                                                                                                                     | Example: "[123P]" is replaced with a tree for "[5]U[6]O[7]"                                             |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| neutral                                    | Hints and UnevaluatedFormat Constraints are seen as neutral as they don't have a condition to be fulfilled or unfulfilled and should not change the requirement outcome. See truth table below.                                                                                                                                                                 |                                                                                                         |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
| unknown                                    | If the condition can be fulfilled but we don't know (yet) if it is or not. See truth table below.                                                                                                                                                                                                                                                               | "Wenn vorhanden"                                                                                        |
+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+


The decision if a requirement constraint is met / fulfilled / true is
made in the content evaluation module.

Program structure
~~~~~~~~~~~~~~~~~

The following diagram shows the structure of the condition check for
more than one condition. If it is only a single condition or just a
requirement indicator, the respective tree consists of just this token
and the result equals the input.

.. figure:: src/ahbicht/expressions/condition_structure_with_more_than_one_condition.png
   :alt: grafik

The raw and updated data for this diagram can be found in the
`draw_io_charts
repository <https://github.com/Hochfrequenz/draw_io_charts/tree/main/wimbee/conditions>`__
and edited under
`app.diagrams.net <https://app.diagrams.net/#HHochfrequenz%2Fdraw_io_charts%2Fmain%2Fwimbee%2Fconditions%2FCondition_Structure_with_more_than_one_condition.drawio>`__
with your GitHub Account.

There is also an `UML Diagram <docs/_static/ahbicht_uml.svg>`_ available (last updated 2022-01-29).

Truth tables
~~~~~~~~~~~~

Additionally to the usual boolean logic we also have ``neutral``
elements (e.g. ``Hints``, ``UnevaluatedFormatConstraints`` and in some
cases ``EvaluatedCompositions``) or ``unknown`` requirement constraints.
They are handled as follows:

``and_composition``
^^^^^^^^^^^^^^^^^^^

======= ======= =======
A       B       A U B
======= ======= =======
Neutral True    True
Neutral False   False
Neutral Neutral Neutral
Unknown True    Unknown
Unknown False   False
Unknown Unknown Unknown
Unknown Neutral Unknown
======= ======= =======

``or_composition``
^^^^^^^^^^^^^^^^^^

+---------+---------+---------------------+-----------------------+
| A       | B       | A O B               | note                  |
+=========+=========+=====================+=======================+
| Neutral | True    | does not make sense |                       |
+---------+---------+---------------------+-----------------------+
| Neutral | False   | does not make sense |                       |
+---------+---------+---------------------+-----------------------+
| Neutral | Neutral | Neutral             | no or_compositions of |
|         |         |                     | hint and format       |
|         |         |                     | constraint            |
+---------+---------+---------------------+-----------------------+
| Unknown | True    | True                |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | False   | Unknown             |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | Unknown | Unknown             |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | Neutral | does not make sense |                       |
+---------+---------+---------------------+-----------------------+

``xor_composition``
^^^^^^^^^^^^^^^^^^^

+---------+---------+---------------------+-----------------------+
| A       | B       | A X B               | note                  |
+=========+=========+=====================+=======================+
| Neutral | True    | does not make sense |                       |
+---------+---------+---------------------+-----------------------+
| Neutral | False   | does not make sense |                       |
+---------+---------+---------------------+-----------------------+
| Neutral | Neutral | Neutral             | no xor_compositions   |
|         |         |                     | of hint and format    |
|         |         |                     | constraint            |
+---------+---------+---------------------+-----------------------+
| Unknown | True    | Unknown             |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | False   | Unknown             |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | Unknown | Unknown             |                       |
+---------+---------+---------------------+-----------------------+
| Unknown | Neutral | does not make sense |                       |
+---------+---------+---------------------+-----------------------+

Link to automatically generate HintsProvider Json content:
https://regex101.com/r/za8pr3/5

Content Evaluation
------------------

Evaluation is the term used for the processing of *single* unevaluated
conditions. The results of the evaluation of all relevant conditions
inside a message can then be used to validate a message. The latter is
**not** part of the evaluation.

This library does *not* provide content evaluation code for all the
conditions used in the available AHBs. You can use the Content
Evaluation class stubs though. Please contact
`@JoschaMetze <https://github.com/joschametze>`_ if you’re interested in a
ready-to-use solution to validate your EDIFACT messages according to the
latest AHBs. We probably have you covered.

EvaluatableData (Edifact Seed and others)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For the evaluation of a condition (that is referenced by its key,
e.g. “17”) it is necessary to have a data basis that allows to decide
whether the respective condition is met or not met. This data basis that
is stable for all conditions that are evaluated in on evaluation run is
called ``EvaluatableData``. These data usually contain the **edifact
seed** (a JSON representation of the EDIFACT message) but may also hold
other information. The ``EvaluatableData`` class acts a container for
these data.

EvaluationContext (Scope and others)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

While the data basis is stable, the context in which a condition is
evaluated might change during on evaluation run. The same condition can
have different evaluation results depending on e.g. in which scope it is
evaluated. A **scope** is a (json) path that references a specific
subtree of the edifact seed. For example one “Vorgang” (``SG4 IDE``) in
UTILMD could be a scope. If a condition is described as

   There has to be exactly one xyz per Vorgang (SG4+IDE) Then for ``n``
   Vorgänge there are ``n`` scopes:

-  one scope for each Vorgang (path's refer to an edifact seed):

   -  ``$["Dokument"][0]["Nachricht"][0]["Vorgang"][0]``
   -  ``$["Dokument"][0]["Nachricht"][0]["Vorgang"][1]``
   -  …
   -  ``$["Dokument"][0]["Nachricht"][0]["Vorgang"][<n-1>]``

Each of the single vorgang scopes can have a different evaluation
result. Those results are relevant for the user when entering data,
probably based in a somehow Vorgang-centric manner.

The ``EvaluationContext`` class is a container for the scope and
other information that are relevant for a single condition and a single
evaluation only but (other than ``EvaluatableData``) might change within
an otherwise stable message.

.. figure:: src/ahbicht/content_evaluation/EvaluatingConditions.png
   :alt: grafik

..
    The raw and updated data for this diagram can be found in the [draw_io_charts repository](https://github.com/Hochfrequenz/draw_io_charts/tree/main/wimbee/) and edited under [app.diagrams.net](https://app.diagrams.net/#HHochfrequenz%2Fdraw_io_charts%2Fmain%2Fwimbee%2FEvaluatingConditions.drawio) with your Hochfrequenz GitHub Account. -->

Releasing
---------

To create a new release, just create a new release with a new version tag (e.g. v1.2.3) on `the releases page of this repository <https://github.com/Hochfrequenz/ahbicht/releases>`__.

Contributing
------------

You are very welcome to contribute to this repository by opening a pull
request against the main branch.

How to use this Repository on Your Machine / Local Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Please follow the instructions in our `Python Template Repository <https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine>`_.

.. |Unittests status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Unittests/badge.svg
.. |Coverage status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Coverage/badge.svg
.. |Linting status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Linting/badge.svg
.. |Black status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Black/badge.svg
.. |pypy status badge| image:: https://img.shields.io/pypi/v/ahbicht
.. |UTILMD_AHB_WiM_3_1b_20201016.pdf page 90| image:: ./docs/_static/wim_ahb_screenshot.png

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ahbicht",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "AHB, Expressions, Parsing",
    "author": null,
    "author_email": "Annika Schl\u00f6gl <annika.schloegl@hochfrequenz.de>",
    "download_url": "https://files.pythonhosted.org/packages/d4/83/90c709d64bc95af1184440aa73917c7f76d528c03e883ef93187e03ecc8f/ahbicht-0.10.0.tar.gz",
    "platform": null,
    "description": "AHB Condition Expression Parser (AHBicht)\n=========================================\n\n|Unittests status badge| |Coverage status badge| |Linting status badge|\n|Black status badge| |pypy status badge|\n\n.. image:: https://raw.githubusercontent.com/Hochfrequenz/ahbicht/main/docs/_static/ahbicht-logo.png\n   :target: https://ahbicht.readthedocs.io\n   :align: right\n   :alt: ahbicht logo\n   :width: 150px\n\nA python package that parses condition expressions from EDI\\@Energy\nAnwendungshandb\u00fccher (AHB). Since it's based on lark, we named the\nmodule AHBicht.\n\nWhat is this all about?\n-----------------------\n\nThe German energy market uses\n`EDIFACT <https://en.wikipedia.org/wiki/EDIFACT>`__ as an intercompany\ndata exchange format. The rules on how to structure and validate the\nEDIFACT messages are written in\n\n-  one **M**\\ essage **I**\\ mplementation **G**\\ uide (MIG) per EDIFACT\n   format (for example UTILMD or MSCONS)\n-  one **A**\\ nwendungs\\ **h**\\ and\\ **b**\\ uch (AHB,\n   en. manual) per use case group (for example\n   `GPKE <https://de.wikipedia.org/wiki/Gesch%C3%A4ftsprozesse_zur_Kundenbelieferung_mit_Elektrizit%C3%A4t>`__\n   or *Wechselprozesse im Messwesen* (WiM))\n\nAccording to the legislation for the German energy market, the\norganisations in charge of maintaining the documents described above\n(AHB and MIGs) are the\n**B**\\ undesverband **d**\\ er **E**\\ nergie-\nund **W**\\ asserwirtschaft (BDEW) and the\n**B**\\ undes\\ **netza**\\ gentur (BNetzA). They form a working\ngroup named \"Arbeitsgruppe EDI\\@Energy\". This work group publishes the\nMIGs and AHBs on `edi-energy.de <https://edi-energy.de/>`__. The\ndocuments are published as PDFs which is better than faxing them but far\nfrom ideal.\n\nThe AHBs contain information on how to structure single EDIFACT\nmessages. To create messages that are valid according to the respective\nAHB, you have to process information of the kind:\n|UTILMD_AHB_WiM_3_1b_20201016.pdf page 90|\n\nIn this example: **This library parses the string\n``Muss [210] U ([182] X ([90] U [183]))`` and allows determining whether\n\u201cDetails der Prognosegrundlage\u201d is an obligatory field according to the\nAHB, iff the individual status of the conditions is given.** We call\nthis \u201cexpression evaluation\u201d.\n\nNote that determining the individual status of ``[210]``, ``[182]``,\n``[90]`` and ``[183]`` itself (the so called \u201ccontent evaluation\u201d, see\nbelow) is **not** within the scope of this parsing library.\n\nNote also, that this library also parses the new convention using logical operators that becomes effective 2022-04-01 (\"MaKo2022\").\n``Muss [210] \u2227 ([182] \u22bb ([90] \u2227 [183]))``.\n\n\nUsage and Examples\n------------------\n\nJupyter Notebook\n~~~~~~~~~~~~~~~~\nFor a minimal working example on how what the library is used, check out `this Jupyter notebook <minimal_working_example.ipynb>`__.\n\nFree to Use REST API\n~~~~~~~~~~~~~~~~~~~~\nYou can also use our public REST API to parse condition expressions (other features will follow). Simply send a GET request with the condition expression as query parameter to:\n`ahbicht.azurewebsites.net/api/ParseExpression?expression=[2] U ([3] O [4])[901] U [555] <https://ahbicht.azurewebsites.net/api/ParseExpression?expression=%5B2%5D%20U%20%28%5B3%5D%20O%20%5B4%5D%29%5B901%5D%20U%20%5B555%5D>`__\n\nEasily Integrate AHBicht with Your Solution\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nIf you want to use AHBicht together with your own software, you can use the `JSON Schema files <json_schemas>`__ provided to kick start the integration.\n\nThere is a fully typed .NET client available: `AhbichtClient.NET <https://github.com/Hochfrequenz/AhbichtClient.net>`_\n\nCode Quality / Production Readiness\n-----------------------------------\n\n-  The code has at least a 95% unit test coverage. \u2714\ufe0f\n-  The code is rated 10/10 in pylint and type checked with mypy. \u2714\ufe0f\n-  The code is `MIT licensed <LICENSE>`__. \u2714\ufe0f\n-  There are only `few dependencies <requirements.in>`__. \u2714\ufe0f\n\nExpression Evaluation / Parsing the Condition String\n----------------------------------------------------\n\nEvaluating expressions like ``Muss [59] U ([123] O [456])`` from the\nAHBs by parsing it with the `parsing library\nlark <https://lark-parser.readthedocs.io/en/latest/>`__ and\ncombining the parsing result with information about the state of\n``[59]``, ``[123]``, ``[456]`` is called **expression evaluation**.\nDetermining the state of each single condition (f.e. ``[59]`` is\nfulfilled, ``[123]`` is not fulfilled, ``[456]`` is unknown) for a given\nmessage is part of the **content evaluation** (see next chapter).\n\nIf you\u2019re new to this topic, please read `edi-energy.de \u2192 Dokumente \u2192\nAllgemeine\nFestlegungen <https://www.edi-energy.de/index.php?id=38&tx_bdew_bdew%5Buid%5D=956&tx_bdew_bdew%5Baction%5D=download&tx_bdew_bdew%5Bcontroller%5D=Dokument&cHash=ae3c1bd6fe3f664cd90f5e94f9714e3e>`__\nfirst. This document contains German explanations, how the Bedingungen\nare supposed to be read.\n\nFunctionality\n~~~~~~~~~~~~~\n\n-  Expressions can contain single numbers e.g.\u00a0``[47]`` or numbers\n   combined with ``U``/``O``/``X`` or ``\u2227``/``\u2228``/``\u22bb`` respectively which are translated to boolean\n   operators ``and``/``or``/``exclusive or``, e.g.\u00a0``[45]U[2]`` or they\n   can be combined **without** an operator, e.g.\u00a0``[930][5]`` in the\n   case of FormatConstraints.\n-  Expressions can contain random whitespaces.\n-  Input conditions are passed in form of a ``ConditionNode``, see\n   below.\n-  Bedingungen/``RequirementConstraints`` with a boolean value,\n   Hinweise/``Hints`` and Formatdefinitionen/``FormatConstraints`` are\n   so far functionally implemented as the result returns if the\n   condition expression is fulfilled and which Hints and\n   FormatConstraints are relevant.\n-  The boolean logic follows 'brackets ``( )`` before ``then_also``\n   before ``and`` before ``or``'.\n-  Hints and UnevaluatedFormatConstraints are implemented as ``neutral``\n   element, so not changing the boolean outcome of an expression for the\n   evaluation regarding the requirement constraints and raising errors\n   when there is no sensible logical outcome of the expression.\n-  A ``condition_fulfilled`` attribute can also take the value\n   ``unknown``.\n-  Brackets e.g.\u00a0``([43]O[4])U[5]``\n-  Requirement indicators (i.e ``Muss``, ``Soll``, ``Kann``, ``X``,\n   ``O``, ``U``) are separated from the condition expressions and also\n   separated into single requirement indicator expressions if there are\n   more than one (for modal marks).\n-  ``Format Constraint Expressions`` that are returned after the\n   requirement condition evaluation can now be parsed and evaluated.\n-  Evaluate several modal marks in one ahb_expression: the first one\n   that evaluates to fulfilled is the valid one.\n\nIn planning\n^^^^^^^^^^^\n\n-  Evaluate requirement indicators:\n\n   -  Soll, Kann, Muss, X, O, U -> is_required, is_forbidden, etc\u2026\n\nDefinition of terms\n~~~~~~~~~~~~~~~~~~~\n\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Term                                       | Description                                                                                                                                                                                                                                                                                                                                                     | Example                                                                                                 |\n+============================================+=================================================================================================================================================================================================================================================================================================================================================================+=========================================================================================================+\n| condition                                  | single operand                                                                                                                                                                                                                                                                                                                                                  | [53]                                                                                                    |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| condition_key                              | int or str, the number of the condition                                                                                                                                                                                                                                                                                                                         | 53                                                                                                      |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| operator                                   | combines two conditions                                                                                                                                                                                                                                                                                                                                         | U, O                                                                                                    |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| composition                                | two parts of an expression combined by an operator                                                                                                                                                                                                                                                                                                              | ([4]U[76])O[5] consists of an and_composition of [4] and [76] and an or_composition of [4]U[76] and [5] |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | used in the context of the parsing and evaluation of the expression                                                                                                                                                                                                                                                                                             |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| ahb expression                             | an expression as given from the ahb                                                                                                                                                                                                                                                                                                                             | X[59]U[53]                                                                                              |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | Consists of at least one single requirement indicator expression.                                                                                                                                                                                                                                                                                               | Muss[59]U([123]O[456])Soll[53]                                                                          |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | In case of several model mark expressions the first one will be evaluated and if not fulfilled, it will be continued with the next one.                                                                                                                                                                                                                         |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| single requirement indicator expression    | An expression consisting of exactly one requirement indicator and their respective condition expression.                                                                                                                                                                                                                                                        | Soll[53]                                                                                                |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | If there is only one requirement indicator in the ahb expression, then both expressions are identical.                                                                                                                                                                                                                                                          |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| condition expression                       | one or multiple conditions combined with or (in case of FormatConstraints) also without operators                                                                                                                                                                                                                                                               | [1]                                                                                                     |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | used as input for the condition parser                                                                                                                                                                                                                                                                                                                          | [4]O[5]U[45]                                                                                            |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| format constraint expression               | Is returned after the evaluation of the RequirementConstraints                                                                                                                                                                                                                                                                                                  | [901]X[954]                                                                                             |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | consist only of FormatConstraints                                                                                                                                                                                                                                                                                                                               |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| requirement indicator                      | The Merkmal/modal_mark or Operator/prefix_operator of the data element/data element group/segment/segment group.                                                                                                                                                                                                                                                | Muss, Soll, Kann, X, O, U                                                                               |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Merkmal / modal_mark                       | as defined by the EDI Energy group (see edi-energy.de \u2192 Dokumente \u2192 Allgemeine Festlegungen)                                                                                                                                                                                                                                                                    | Muss, Soll, Kann                                                                                        |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | Stands alone or before a condition expression, can be the start of several requirement indicator expressions in one ahb expression                                                                                                                                                                                                                              |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| prefix operator                            | Operator which does not function to combine conditions, but as requirement indicator.                                                                                                                                                                                                                                                                           | X, O, U                                                                                                 |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | Stands alone or in front of a condition expression.                                                                                                                                                                                                                                                                                                             |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| tree, branches, token                      | as used by lark                                                                                                                                                                                                                                                                                                                                                 |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| ConditionNode                              | Defines the nodes of the tree as they are passed, evaluated und returned.                                                                                                                                                                                                                                                                                       | RequirementConstraint, FormatConstraint, Hint, EvaluatedComposition, RepeatabilityConstraint            |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | There are different kinds of conditions (Bedingung, Hinweis, Format) as defined by the EDI Energy group (see edi-energy.de \u2192 Dokumente \u2192 Allgemeine Festlegungen) and also a EvaluatedComposition after a composition of two nodes is evaluated.                                                                                                                |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Bedingung / RequirementConstraint (rc)     | - are true or false, has to be determined                                                                                                                                                                                                                                                                                                                       | \"falls SG2+IDE+CCI == EHZ\"                                                                              |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | - keys between [1] and [499]                                                                                                                                                                                                                                                                                                                                    |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Wiederholbarkeit / RepeatabilityConstraint | - gives minimum and maximum occurrence                                                                                                                                                                                                                                                                                                                          | \"Segmentgruppe ist mindestens einmal je SG4 IDE+24 (Vorgang) anzugeben\"                                 |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | - keys between [2000] and [2499]                                                                                                                                                                                                                                                                                                                                |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Hinweis / Hint                             | - just a hint, even if it is worded like a condition                                                                                                                                                                                                                                                                                                            | \"Hinweis: 'ID der Messlokation'\"                                                                        |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | - keys from [500] onwards, starts with 'Hinweis:'                                                                                                                                                                                                                                                                                                               | \"Hinweis: 'Es ist der alte MSB zu verwenden'\"                                                           |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Formatdefinition / FormatConstraint (fc)   | - a constraint for how the data should be given                                                                                                                                                                                                                                                                                                                 | \"Format: Muss gr\u00f6\u00dfer 0 sein\"                                                                            |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | - keys between [901] and [999], starts with 'Format:'                                                                                                                                                                                                                                                                                                           | \"Format: max 5 Nachkommastellen\"                                                                        |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n|                                            | Format Constraints are \"collected\" while evaluating the rest of the tree, meaning the evaluated composition of the Mussfeldpr\u00fcfung contains an expression that consists only of format constraints.                                                                                                                                                             |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| UnevaluatedFormatConstraint                | A format constraint that is just \"collected\" during the requirement constraint evaluation. To have a clear separation of conditions that affect whether a field is mandatory or not and those that check the format of fields without changing their state it will become a part of the format_constraint_expression which is part of the EvaluatedComposition. |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| EvaluatableFormatConstraint                | An evaluatable FormatConstraint will (other than the UnevaluatedFormatConstraint) be evaluated by e.g. matching a regex, calculating a checksum etc. This happens after the Mussfeldpr\u00fcfung. (details to be added upon implementing)                                                                                                                            |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| EvaluatedComposition                       | is returned after a composition of two nodes is evaluated                                                                                                                                                                                                                                                                                                       |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| Package Resolver                           | a package resolver is a class that replaces package nodes in a tree with a sub tree that is derived from a package definition. Replacing package nodes with sub trees is referred to as \"package expansion\"                                                                                                                                                     | Example: \"[123P]\" is replaced with a tree for \"[5]U[6]O[7]\"                                             |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| neutral                                    | Hints and UnevaluatedFormat Constraints are seen as neutral as they don't have a condition to be fulfilled or unfulfilled and should not change the requirement outcome. See truth table below.                                                                                                                                                                 |                                                                                                         |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n| unknown                                    | If the condition can be fulfilled but we don't know (yet) if it is or not. See truth table below.                                                                                                                                                                                                                                                               | \"Wenn vorhanden\"                                                                                        |\n+--------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+\n\n\nThe decision if a requirement constraint is met / fulfilled / true is\nmade in the content evaluation module.\n\nProgram structure\n~~~~~~~~~~~~~~~~~\n\nThe following diagram shows the structure of the condition check for\nmore than one condition. If it is only a single condition or just a\nrequirement indicator, the respective tree consists of just this token\nand the result equals the input.\n\n.. figure:: src/ahbicht/expressions/condition_structure_with_more_than_one_condition.png\n   :alt: grafik\n\nThe raw and updated data for this diagram can be found in the\n`draw_io_charts\nrepository <https://github.com/Hochfrequenz/draw_io_charts/tree/main/wimbee/conditions>`__\nand edited under\n`app.diagrams.net <https://app.diagrams.net/#HHochfrequenz%2Fdraw_io_charts%2Fmain%2Fwimbee%2Fconditions%2FCondition_Structure_with_more_than_one_condition.drawio>`__\nwith your GitHub Account.\n\nThere is also an `UML Diagram <docs/_static/ahbicht_uml.svg>`_ available (last updated 2022-01-29).\n\nTruth tables\n~~~~~~~~~~~~\n\nAdditionally to the usual boolean logic we also have ``neutral``\nelements (e.g.\u00a0``Hints``, ``UnevaluatedFormatConstraints`` and in some\ncases ``EvaluatedCompositions``) or ``unknown`` requirement constraints.\nThey are handled as follows:\n\n``and_composition``\n^^^^^^^^^^^^^^^^^^^\n\n======= ======= =======\nA       B       A U B\n======= ======= =======\nNeutral True    True\nNeutral False   False\nNeutral Neutral Neutral\nUnknown True    Unknown\nUnknown False   False\nUnknown Unknown Unknown\nUnknown Neutral Unknown\n======= ======= =======\n\n``or_composition``\n^^^^^^^^^^^^^^^^^^\n\n+---------+---------+---------------------+-----------------------+\n| A       | B       | A O B               | note                  |\n+=========+=========+=====================+=======================+\n| Neutral | True    | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n| Neutral | False   | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n| Neutral | Neutral | Neutral             | no or_compositions of |\n|         |         |                     | hint and format       |\n|         |         |                     | constraint            |\n+---------+---------+---------------------+-----------------------+\n| Unknown | True    | True                |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | False   | Unknown             |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | Unknown | Unknown             |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | Neutral | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n\n``xor_composition``\n^^^^^^^^^^^^^^^^^^^\n\n+---------+---------+---------------------+-----------------------+\n| A       | B       | A X B               | note                  |\n+=========+=========+=====================+=======================+\n| Neutral | True    | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n| Neutral | False   | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n| Neutral | Neutral | Neutral             | no xor_compositions   |\n|         |         |                     | of hint and format    |\n|         |         |                     | constraint            |\n+---------+---------+---------------------+-----------------------+\n| Unknown | True    | Unknown             |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | False   | Unknown             |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | Unknown | Unknown             |                       |\n+---------+---------+---------------------+-----------------------+\n| Unknown | Neutral | does not make sense |                       |\n+---------+---------+---------------------+-----------------------+\n\nLink to automatically generate HintsProvider Json content:\nhttps://regex101.com/r/za8pr3/5\n\nContent Evaluation\n------------------\n\nEvaluation is the term used for the processing of *single* unevaluated\nconditions. The results of the evaluation of all relevant conditions\ninside a message can then be used to validate a message. The latter is\n**not** part of the evaluation.\n\nThis library does *not* provide content evaluation code for all the\nconditions used in the available AHBs. You can use the Content\nEvaluation class stubs though. Please contact\n`@JoschaMetze <https://github.com/joschametze>`_ if you\u2019re interested in a\nready-to-use solution to validate your EDIFACT messages according to the\nlatest AHBs. We probably have you covered.\n\nEvaluatableData (Edifact Seed and others)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nFor the evaluation of a condition (that is referenced by its key,\ne.g.\u00a0\u201c17\u201d) it is necessary to have a data basis that allows to decide\nwhether the respective condition is met or not met. This data basis that\nis stable for all conditions that are evaluated in on evaluation run is\ncalled ``EvaluatableData``. These data usually contain the **edifact\nseed** (a JSON representation of the EDIFACT message) but may also hold\nother information. The ``EvaluatableData`` class acts a container for\nthese data.\n\nEvaluationContext (Scope and others)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhile the data basis is stable, the context in which a condition is\nevaluated might change during on evaluation run. The same condition can\nhave different evaluation results depending on e.g.\u00a0in which scope it is\nevaluated. A **scope** is a (json) path that references a specific\nsubtree of the edifact seed. For example one \u201cVorgang\u201d (``SG4 IDE``) in\nUTILMD could be a scope. If a condition is described as\n\n   There has to be exactly one xyz per Vorgang (SG4+IDE) Then for ``n``\n   Vorg\u00e4nge there are ``n`` scopes:\n\n-  one scope for each Vorgang (path's refer to an edifact seed):\n\n   -  ``$[\"Dokument\"][0][\"Nachricht\"][0][\"Vorgang\"][0]``\n   -  ``$[\"Dokument\"][0][\"Nachricht\"][0][\"Vorgang\"][1]``\n   -  \u2026\n   -  ``$[\"Dokument\"][0][\"Nachricht\"][0][\"Vorgang\"][<n-1>]``\n\nEach of the single vorgang scopes can have a different evaluation\nresult. Those results are relevant for the user when entering data,\nprobably based in a somehow Vorgang-centric manner.\n\nThe ``EvaluationContext`` class is a container for the scope and\nother information that are relevant for a single condition and a single\nevaluation only but (other than ``EvaluatableData``) might change within\nan otherwise stable message.\n\n.. figure:: src/ahbicht/content_evaluation/EvaluatingConditions.png\n   :alt: grafik\n\n..\n    The raw and updated data for this diagram can be found in the [draw_io_charts repository](https://github.com/Hochfrequenz/draw_io_charts/tree/main/wimbee/) and edited under [app.diagrams.net](https://app.diagrams.net/#HHochfrequenz%2Fdraw_io_charts%2Fmain%2Fwimbee%2FEvaluatingConditions.drawio) with your Hochfrequenz GitHub Account. -->\n\nReleasing\n---------\n\nTo create a new release, just create a new release with a new version tag (e.g. v1.2.3) on `the releases page of this repository <https://github.com/Hochfrequenz/ahbicht/releases>`__.\n\nContributing\n------------\n\nYou are very welcome to contribute to this repository by opening a pull\nrequest against the main branch.\n\nHow to use this Repository on Your Machine / Local Setup\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPlease follow the instructions in our `Python Template Repository <https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine>`_.\n\n.. |Unittests status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Unittests/badge.svg\n.. |Coverage status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Coverage/badge.svg\n.. |Linting status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Linting/badge.svg\n.. |Black status badge| image:: https://github.com/Hochfrequenz/ahbicht/workflows/Black/badge.svg\n.. |pypy status badge| image:: https://img.shields.io/pypi/v/ahbicht\n.. |UTILMD_AHB_WiM_3_1b_20201016.pdf page 90| image:: ./docs/_static/wim_ahb_screenshot.png\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python Library to parse AHB expressions.",
    "version": "0.10.0",
    "project_urls": {
        "Changelog": "https://github.com/Hochfrequenz/ahbicht/releases",
        "Documentation": "https://ahbicht.readthedocs.io/en/latest/",
        "Homepage": "https://github.com/Hochfrequenz/ahbicht"
    },
    "split_keywords": [
        "ahb",
        " expressions",
        " parsing"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f6221560ac078b31b524dbbb5291754f9e0a24c8bbf1dccd9eb6ae22af8c24c8",
                "md5": "3a2948edb31e1964cdfab9577cda02b2",
                "sha256": "7f372c74b98ead9728be2764644b1effaf90ddcdf8a325f222cb6d0e97c22131"
            },
            "downloads": -1,
            "filename": "ahbicht-0.10.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3a2948edb31e1964cdfab9577cda02b2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 371037,
            "upload_time": "2024-10-01T15:01:08",
            "upload_time_iso_8601": "2024-10-01T15:01:08.416765Z",
            "url": "https://files.pythonhosted.org/packages/f6/22/1560ac078b31b524dbbb5291754f9e0a24c8bbf1dccd9eb6ae22af8c24c8/ahbicht-0.10.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d48390c709d64bc95af1184440aa73917c7f76d528c03e883ef93187e03ecc8f",
                "md5": "26af0641dd1bf69873d16771d1d6a215",
                "sha256": "1cc742f61b66cd7d14d08ebf0af57cb46ff5e4fae460499f48c691c1b1c79b8a"
            },
            "downloads": -1,
            "filename": "ahbicht-0.10.0.tar.gz",
            "has_sig": false,
            "md5_digest": "26af0641dd1bf69873d16771d1d6a215",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 2025563,
            "upload_time": "2024-10-01T15:01:10",
            "upload_time_iso_8601": "2024-10-01T15:01:10.658826Z",
            "url": "https://files.pythonhosted.org/packages/d4/83/90c709d64bc95af1184440aa73917c7f76d528c03e883ef93187e03ecc8f/ahbicht-0.10.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-01 15:01:10",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Hochfrequenz",
    "github_project": "ahbicht",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "attrs",
            "specs": [
                [
                    "==",
                    "24.2.0"
                ]
            ]
        },
        {
            "name": "efoli",
            "specs": [
                [
                    "==",
                    "1.2.0"
                ]
            ]
        },
        {
            "name": "inject",
            "specs": [
                [
                    "==",
                    "5.2.1"
                ]
            ]
        },
        {
            "name": "lark",
            "specs": [
                [
                    "==",
                    "1.2.2"
                ]
            ]
        },
        {
            "name": "marshmallow",
            "specs": [
                [
                    "==",
                    "3.22.0"
                ]
            ]
        },
        {
            "name": "marshmallow-enum",
            "specs": [
                [
                    "==",
                    "1.5.1"
                ]
            ]
        },
        {
            "name": "maus",
            "specs": [
                [
                    "==",
                    "0.6.1"
                ]
            ]
        },
        {
            "name": "more-itertools",
            "specs": [
                [
                    "==",
                    "10.5.0"
                ]
            ]
        },
        {
            "name": "packaging",
            "specs": [
                [
                    "==",
                    "24.1"
                ]
            ]
        },
        {
            "name": "pytz",
            "specs": [
                [
                    "==",
                    "2024.2"
                ]
            ]
        }
    ],
    "tox": true,
    "lcname": "ahbicht"
}