Metadata-Version: 2.4
Name: transformerbeeclient
Version: 0.2.1
Summary: async HTTP client to communicate with transformer.bee/edifact-bo4e-converter
Project-URL: Changelog, https://github.com/Hochfrequenz/TransformerBeeClient.py/releases
Project-URL: Homepage, https://github.com/Hochfrequenz/TransformerBeeClient.py
Author-email: Hochfrequenz Unternehmensberatung GmbH <info+github@hochfrequenz.de>
License: MIT
License-File: LICENSE
Keywords: bo4e,edifact,transformer.bee
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: aioauth-client
Requires-Dist: aiohttp[speedups]>=3.9.3
Requires-Dist: efoli>=1.4.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt
Provides-Extra: coverage
Requires-Dist: coverage==7.8.0; extra == 'coverage'
Provides-Extra: formatting
Requires-Dist: black==25.1.0; extra == 'formatting'
Requires-Dist: isort==6.0.1; extra == 'formatting'
Provides-Extra: linting
Requires-Dist: pylint==3.3.6; extra == 'linting'
Provides-Extra: packaging
Requires-Dist: build==1.2.2.post1; extra == 'packaging'
Requires-Dist: twine==6.1.0; extra == 'packaging'
Provides-Extra: spellcheck
Requires-Dist: codespell==2.4.1; extra == 'spellcheck'
Provides-Extra: tests
Requires-Dist: pytest-asyncio==0.26.0; extra == 'tests'
Requires-Dist: pytest==8.3.5; extra == 'tests'
Requires-Dist: testcontainers==4.9.2; extra == 'tests'
Provides-Extra: type-check
Requires-Dist: mypy[pydantic]==1.15.0; extra == 'type-check'
Requires-Dist: types-docker==7.1.0.20241229; extra == 'type-check'
Requires-Dist: types-pytz==2025.1.0.20250318; extra == 'type-check'
Description-Content-Type: text/markdown

# transformer.bee Client (Python)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Python Versions (officially) supported](https://img.shields.io/pypi/pyversions/transformerbeeclient.svg)
![Unittests status badge](https://github.com/Hochfrequenz/TransformerBeeClient.py/workflows/Unittests/badge.svg)
![Coverage status badge](https://github.com/Hochfrequenz/TransformerBeeClient.py/workflows/Coverage/badge.svg)
![Linting status badge](https://github.com/Hochfrequenz/TransformerBeeClient.py/workflows/Linting/badge.svg)
![Black status badge](https://github.com/Hochfrequenz/TransformerBeeClient.py/workflows/Formatting/badge.svg)
![PyPi Status Badge](https://img.shields.io/pypi/v/transformerbeeclient)

This library is a Python HTTP client for transformer.bee aka edifact-bo4e-converter.
We also maintain a [.NET version](https://github.com/Hochfrequenz/TransformerBeeClient.NET) of this client.

It allows you to convert EDIFACT messages to BO4E and vice versa by speaking to Hochfrequenz's transformer.bee service.
Note that the actual conversion happens in the transformer.bee service/backend, this library only provides a convenient way to use its API.

## How to use this library

### Prerequisites / Account

First of all, you need an account to use transformer.bee.
Ask info@hochfrequenz.de or ping [@JoschaMetze](https://github.com/joschametze) on GitHub to get one.

You can check if your account is working by logging [into our stage environment](https://transformerstage.utilibee.io/app/).

### Using the client
Install the library via [pip](https://pypi.org/project/transformerbeeclient/):
```bash
pip install transformerbeeclient
```

### Authentication
As of 2024-02-06 we support either no authentication or OAuth2 client ID/client secret authentication.
Both the unauthenticated and the authenticated client implement the `TransformerBeeClient` protocol, so you can use them interchangeably.

#### No Authentication
If you're hosting transformer.bee in the same network or your localhost and there is no authentication, you can instantiate the client
```python
from yarl import URL
from transformerbeeclient import UnauthenticatedTransformerBeeClient

client = UnauthenticatedTransformerBeeClient(base_url=URL("http://localhost:5021"))
```

#### OAuth2 with Client ID/Client Secret
If, which is more likely, Hochfrequenz provided you with a client Id and secret, you can use the `AuthenticatedTransformerBeeClient` class like this:
```python
from yarl import URL
from transformerbeeclient import AuthenticatedTransformerBeeClient

client = AuthenticatedTransformerBeeClient(
    base_url=URL("https://transformer.utilibee.io"),
    client_id="your_client_id",
    client_secret="your_client_secret",
)
```

#### Minimal Working Examples
Find full examples of both conversions in [the integration tests](integrationtests/test_conversion.py).
Find the respective BO4E and EDIFACTs in [the test data folder](integrationtests/TestEdifact).

### Conversion
There are two main methods to convert between EDIFACT and BO4E:
- `edifact_to_bo4e`
- `bo4e_to_edifact`

Both have an `EdifactFormatVersion` as argument (imported from [efoli](https://github.com/Hochfrequenz/efoli)), which denotes which version of the EDIFACT format you want to use.
We group all the different versions of the EDIFACT format into an enum, so you can easily choose the one you need.
E.g. `EdifactFormatVersion.FV2310` stands for all MIG/AHB versions valid since 2023-10-01.


#### Convert EDIFACT to BO4E
```python
from efoli import EdifactFormatVersion
# client instantiation goes here

bo4e = await client.edifact_to_bo4e("UNA:+,? 'UNB...", EdifactFormatVersion.FV2310)
```

#### Convert BO4E to EDIFACT
```python
from efoli import EdifactFormatVersion
from transformerbeeclient import BOneyComb
# client instantiation goes here

boney_comb = BOneyComb.model_validate({"stammdaten":[...], "transaktionsdaten":{...}})
edifact = await client.bo4e_to_edifact(boney_comb, EdifactFormatVersion.FV2310)
```

## Development
For development of this library, follow the instructions in our [Python Template Repository](https://github.com/Hochfrequenz/python_template_repository).

### Release (CI/CD)

To release a new version of this library, [create a new release](https://github.com/Hochfrequenz/TransformerBeeClient.py/releases/new) in GitHub.
Make sure its tag starts with `v` and the version number, e.g. `v1.2.3`.
Releases are not restricted to the main branch but we prefer them to happen there.

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

## Related Tools and Context
This repository is part of the [Hochfrequenz Libraries and Tools for a truly digitized market communication](https://github.com/Hochfrequenz/digital_market_communication/).

## Hochfrequenz
[Hochfrequenz Unternehmensberatung GmbH](https://www.hochfrequenz.de) is a Grünwald (near Munich) based consulting company with offices in Berlin and Bremen and attractive remote options.
We're not only a main contributor for open source software for German utilities but, according to [Kununu ratings](https://www.kununu.com/de/hochfrequenz-unternehmensberatung1), also among the most attractive employers within the German energy market. Applications of talented developers are welcome at any time!
Please consider visiting our [career page](https://www.hochfrequenz.de/index.php/karriere/aktuelle-stellenausschreibungen/full-stack-entwickler) (German only).
