# BO4E-Schema-Tool
This little command line tool enables you to conveniently pull BO4E-Schemas of arbitrary versions.
Additionally, it supports some features to edit those schemas which can be defined by config values.
## Features
### Overview
- Pull BO4E-Schemas of arbitrary versions
- references in `$ref` will be replaced by relative paths
- Edit schemas:
- Define non nullable properties (in most cases changes it to a required field)
- Add additional properties (keep in mind that you should avoid this if possible)
- Add additional models (keep in mind that you should avoid this if possible)
- All features also apply to Enums
## Usage
This tool is a command line tool. You can use it by installing `BO4E-Schema-Tool` it from
[pip](https://pypi.org/project/BO4E-Schema-Tool/) via
```bash
pip install BO4E-Schema-Tool
```
and then running:
```bash
> bost --help
Usage: bost [OPTIONS]
Entry point for the bost command line interface.
Options:
-o, --output DIRECTORY Output directory to pull the JSON schemas into
[required]
-t, --target-version TEXT Target BO4E version. Defaults to latest.
-c, --config-file FILE Path to the config file
-r, --update-refs / -R, --no-update-refs
Automatically update the references in the
schema files. Online references to the BO4E
schemas will be replaced by relative paths.
References to $definitions or $defs must
exists as explicit schemas in the namespace as
well and will be replaced by relative paths to
them. The definitions will be removed.
-d, --set-default-version / -D, --no-set-default-version
Automatically set or overrides the default
version for '_version' fields with --target-
version. This is especially useful if you want
to define additional models which should
always have the correct version.
--clear-output Clear the output directory before saving the
schemas
--cache-dir DIRECTORY Path to the optional cache dir. If not set the
cache is disabled. It will cache the raw
schema files downloaded from github.
--token TEXT A GitHub Access token to authenticate with the
GitHub API. Use this if you have problems with
the rate limit. Alternatively, you can set the
environment variable GITHUB_ACCESS_TOKEN.
--version Show the version and exit.
--help Show this message and exit.
```
Alternatively, you can run the code from your python code by calling `bost.main()` with the same arguments as above.
### Config file
The config file is a JSON file which can be used to customize the BO4E-Schemas. The config file is optional.
Here is a complex example of a config file:
```json
{
"nonNullableFields": [
"bo\\.Angebot\\.angebotspreis",
"(bo|com)\\.\\w+\\._typ",
"\\w+\\.\\w+\\._id"
],
"additionalFields": [
{
"pattern": "bo\\.Angebot",
"fieldName": "foo",
"fieldDef": {
"type": "number"
}
},
{
"$ref": "./models/bo/Geschaeftspartner_extension.json"
}
],
"additionalEnumItems": [
{
"pattern": "enum\\.BoTyp",
"items": [
"Bilanzierung",
"Dokument"
]
}
],
"additionalModels": [
{
"module": "bo",
"schema": {
"$ref": "models/bo/Bilanzierung.json"
}
},
{
"module": "bo",
"schema": {
"additionalProperties": true,
"title": "Dokument",
"type": "object",
"description": "A generic document reference like for bills, order confirmations and cancellations",
"properties": {
"boTyp": {
"allOf": [
{
"$ref": "../enum/BoTyp.json#"
}
],
"title": "BoTyp",
"default": "Dokument"
},
"erstellungsdatum": {
"format": "date-time",
"title": "Erstellungsdatum",
"type": "string"
}
},
"required": [
"erstellungsdatum"
]
}
}
]
}
```
The config file can contain the following keys:
- `nonNullabelFields`: A list of regex patterns which will be used to define non-nullable fields.
The field will be required if the default value was `null`, which will be mostly the case.
The regex pattern will be (full-)matched to the path of each the field.
An example of such a path would be `bo.Angebot.angebotspreis`. If the pattern matches, the field will be non-nullable.
- `additionalFields`: A list of additional fields which will be added to the schema.
- `pattern`: A regex pattern which will be used to match the path of the schema (e.g. `bo.Angebot`).
The field will be added to each schema to which the pattern matches.
- `fieldName`: The name of the field which will be added.
- `fieldDef`: The definition of the field which will be added.
- `additionalEnumItems`: A list of additional enum items which will be added to the schema.
- `pattern`: A regex pattern which will be used to match the path of the enum (e.g. `enum.BoTyp`).
The items will be added to each enum to which the pattern matches.
- `items`: A list of items which will be added to the enum.
- `additionalModels`: A list of additional models which will be added to the schema.
- `module`: The module to which the schema will be added.
- `schema`: The schema definition which will be added.
Note: For all config keys (except `requiredFields`), you can alternatively use the `"$ref"` key to reference to a file.
This is useful to keep the config file small and to reuse definitions.
If the path is relative it will be applied to the path of the directory where the config file is stored in.
But, you can define absolute paths if you want.
As a little extra feature for `additionalFields`: If you want to define multiple fields in one external file,
you can define a list of fields instead of a single field. The reference in the `"$ref"` key is the same.
Example of `./models/bo/Geschaeftspartner_extension.json`:
```json
[
{
"pattern": "bo\\.Geschaeftspartner",
"field_name": "foo",
"field_def": {
"type": "number"
}
},
{
"pattern": "bo\\.Geschaeftspartner",
"field_name": "bar",
"field_def": {
"type": "string"
}
}
]
```
### Update References
The schemas from the repository `BO4E-Schemas` contain online references to each other
(e.g. `"$ref": "https://raw.githubusercontent.com/BO4E/BO4E-Schemas/v202401.0.1/src/bo4e_schemas/bo/Angebot.json#"`).
This is not very convenient if you want to work with the schemas offline. And if you need to edit the schemas using
the config file, this would be a problem.
To solve this problem, you can use the `--update-refs` flag. This will replace the online references with
relative paths. It will also try to replace references introduced by the config file. But note that if the
software can't match the reference to the pattern of an online reference, it will not replace it but instead
log a warning.
### Set Default Version
All BO4E-Schemas contain a field `_version` which defines the used BO4E version. All schemas which are pulled
from the repository `BO4E-Schemas` will have the `_version` fields default value set to the respective version.
But if you introduce additional models, it might be a bit cumbersome to set the `_version` field to the correct
version each time you upgrade the BO4E version.
To solve this problem, you can use the `--set-default-version` flag. It will automatically set or override the default
value for `_version` fields with the `--target-version`.
### GitHub Access Token
If you have problems with the rate limit of the GitHub API, you can specify a GitHub Access token with the
`--token` flag. For more information, please refer to the
[GitHub documentation](https://docs.github.com/de/rest/using-the-rest-api/rate-limits-for-the-rest-api).
If you don't want to specify the token in the parameter list, you can also set the environment variable
`GITHUB_ACCESS_TOKEN`.
### Clear Output
If you want to pull the schemas into a directory which already contains schemas, you can use the `--clear-output` flag.
This will clear the output directory entirely before saving the schemas. This is useful if a new version of the schemas
doesn't contain some schemas anymore which were present in the previous version.
### Cache
If you specify a cache directory with the `--cache-dir` flag, the tool will cache the raw schema files downloaded from
GitHub. This cache is version specific and will be overridden if you want to download another version.
This is useful if you want to execute the tool multiple times with the same version. It will save you some time during
development.
## How to use this Repository on Your Machine
Follow the instructions in our [Python template repository](https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine).
## Contribute
You are very welcome to contribute to this repository by opening a pull request against the main branch.
### GitHub Actions
- Dependabot auto-approve / -merge:
- If the actor is the Dependabot bot (i.e. on every commit by Dependabot)
the pull request is automatically approved and auto merge gets activated
(using squash merge).
Raw data
{
"_id": null,
"home_page": null,
"name": "BO4E-Schema-Tool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "bo4e, code-generator, schemas",
"author": null,
"author_email": "Hochfrequenz Unternehmensberatung GmbH <info@hochfrequenz.de>",
"download_url": "https://files.pythonhosted.org/packages/03/b2/b76bc8136fea3ba84ad442647d471d1ae4997a4d73239b30ecfba07ecdba/bo4e_schema_tool-0.0.9.tar.gz",
"platform": null,
"description": "# BO4E-Schema-Tool\n\n\n\n\n\n\nThis little command line tool enables you to conveniently pull BO4E-Schemas of arbitrary versions.\nAdditionally, it supports some features to edit those schemas which can be defined by config values.\n\n## Features\n### Overview\n\n- Pull BO4E-Schemas of arbitrary versions\n - references in `$ref` will be replaced by relative paths\n- Edit schemas:\n - Define non nullable properties (in most cases changes it to a required field)\n - Add additional properties (keep in mind that you should avoid this if possible)\n - Add additional models (keep in mind that you should avoid this if possible)\n - All features also apply to Enums\n\n## Usage\n\nThis tool is a command line tool. You can use it by installing `BO4E-Schema-Tool` it from\n[pip](https://pypi.org/project/BO4E-Schema-Tool/) via\n```bash\npip install BO4E-Schema-Tool\n```\nand then running:\n```bash\n> bost --help\nUsage: bost [OPTIONS]\n\n Entry point for the bost command line interface.\n\nOptions:\n -o, --output DIRECTORY Output directory to pull the JSON schemas into\n [required]\n -t, --target-version TEXT Target BO4E version. Defaults to latest.\n -c, --config-file FILE Path to the config file\n -r, --update-refs / -R, --no-update-refs\n Automatically update the references in the\n schema files. Online references to the BO4E\n schemas will be replaced by relative paths.\n References to $definitions or $defs must\n exists as explicit schemas in the namespace as\n well and will be replaced by relative paths to\n them. The definitions will be removed.\n -d, --set-default-version / -D, --no-set-default-version\n Automatically set or overrides the default\n version for '_version' fields with --target-\n version. This is especially useful if you want\n to define additional models which should\n always have the correct version.\n --clear-output Clear the output directory before saving the\n schemas\n --cache-dir DIRECTORY Path to the optional cache dir. If not set the\n cache is disabled. It will cache the raw\n schema files downloaded from github.\n --token TEXT A GitHub Access token to authenticate with the\n GitHub API. Use this if you have problems with\n the rate limit. Alternatively, you can set the\n environment variable GITHUB_ACCESS_TOKEN.\n --version Show the version and exit.\n --help Show this message and exit.\n```\nAlternatively, you can run the code from your python code by calling `bost.main()` with the same arguments as above.\n\n### Config file\n\nThe config file is a JSON file which can be used to customize the BO4E-Schemas. The config file is optional.\n\nHere is a complex example of a config file:\n\n```json\n{\n \"nonNullableFields\": [\n \"bo\\\\.Angebot\\\\.angebotspreis\",\n \"(bo|com)\\\\.\\\\w+\\\\._typ\",\n \"\\\\w+\\\\.\\\\w+\\\\._id\"\n ],\n \"additionalFields\": [\n {\n \"pattern\": \"bo\\\\.Angebot\",\n \"fieldName\": \"foo\",\n \"fieldDef\": {\n \"type\": \"number\"\n }\n },\n {\n \"$ref\": \"./models/bo/Geschaeftspartner_extension.json\"\n }\n ],\n \"additionalEnumItems\": [\n {\n \"pattern\": \"enum\\\\.BoTyp\",\n \"items\": [\n \"Bilanzierung\",\n \"Dokument\"\n ]\n }\n ],\n \"additionalModels\": [\n {\n \"module\": \"bo\",\n \"schema\": {\n \"$ref\": \"models/bo/Bilanzierung.json\"\n }\n },\n {\n \"module\": \"bo\",\n \"schema\": {\n \"additionalProperties\": true,\n \"title\": \"Dokument\",\n \"type\": \"object\",\n \"description\": \"A generic document reference like for bills, order confirmations and cancellations\",\n \"properties\": {\n \"boTyp\": {\n \"allOf\": [\n {\n \"$ref\": \"../enum/BoTyp.json#\"\n }\n ],\n \"title\": \"BoTyp\",\n \"default\": \"Dokument\"\n },\n \"erstellungsdatum\": {\n \"format\": \"date-time\",\n \"title\": \"Erstellungsdatum\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"erstellungsdatum\"\n ]\n }\n }\n ]\n}\n```\n\nThe config file can contain the following keys:\n- `nonNullabelFields`: A list of regex patterns which will be used to define non-nullable fields.\n The field will be required if the default value was `null`, which will be mostly the case.\n The regex pattern will be (full-)matched to the path of each the field.\n An example of such a path would be `bo.Angebot.angebotspreis`. If the pattern matches, the field will be non-nullable.\n- `additionalFields`: A list of additional fields which will be added to the schema.\n - `pattern`: A regex pattern which will be used to match the path of the schema (e.g. `bo.Angebot`).\n The field will be added to each schema to which the pattern matches.\n - `fieldName`: The name of the field which will be added.\n - `fieldDef`: The definition of the field which will be added.\n- `additionalEnumItems`: A list of additional enum items which will be added to the schema.\n - `pattern`: A regex pattern which will be used to match the path of the enum (e.g. `enum.BoTyp`).\n The items will be added to each enum to which the pattern matches.\n - `items`: A list of items which will be added to the enum.\n- `additionalModels`: A list of additional models which will be added to the schema.\n - `module`: The module to which the schema will be added.\n - `schema`: The schema definition which will be added.\n\nNote: For all config keys (except `requiredFields`), you can alternatively use the `\"$ref\"` key to reference to a file.\nThis is useful to keep the config file small and to reuse definitions.\nIf the path is relative it will be applied to the path of the directory where the config file is stored in.\nBut, you can define absolute paths if you want.\n\nAs a little extra feature for `additionalFields`: If you want to define multiple fields in one external file,\nyou can define a list of fields instead of a single field. The reference in the `\"$ref\"` key is the same.\n\nExample of `./models/bo/Geschaeftspartner_extension.json`:\n```json\n[\n {\n \"pattern\": \"bo\\\\.Geschaeftspartner\",\n \"field_name\": \"foo\",\n \"field_def\": {\n \"type\": \"number\"\n }\n },\n {\n \"pattern\": \"bo\\\\.Geschaeftspartner\",\n \"field_name\": \"bar\",\n \"field_def\": {\n \"type\": \"string\"\n }\n }\n]\n```\n\n### Update References\n\nThe schemas from the repository `BO4E-Schemas` contain online references to each other\n(e.g. `\"$ref\": \"https://raw.githubusercontent.com/BO4E/BO4E-Schemas/v202401.0.1/src/bo4e_schemas/bo/Angebot.json#\"`).\nThis is not very convenient if you want to work with the schemas offline. And if you need to edit the schemas using\nthe config file, this would be a problem.\n\nTo solve this problem, you can use the `--update-refs` flag. This will replace the online references with\nrelative paths. It will also try to replace references introduced by the config file. But note that if the\nsoftware can't match the reference to the pattern of an online reference, it will not replace it but instead\nlog a warning.\n\n### Set Default Version\n\nAll BO4E-Schemas contain a field `_version` which defines the used BO4E version. All schemas which are pulled\nfrom the repository `BO4E-Schemas` will have the `_version` fields default value set to the respective version.\nBut if you introduce additional models, it might be a bit cumbersome to set the `_version` field to the correct\nversion each time you upgrade the BO4E version.\n\nTo solve this problem, you can use the `--set-default-version` flag. It will automatically set or override the default\nvalue for `_version` fields with the `--target-version`.\n\n### GitHub Access Token\n\nIf you have problems with the rate limit of the GitHub API, you can specify a GitHub Access token with the\n`--token` flag. For more information, please refer to the\n[GitHub documentation](https://docs.github.com/de/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\nIf you don't want to specify the token in the parameter list, you can also set the environment variable\n`GITHUB_ACCESS_TOKEN`.\n\n### Clear Output\n\nIf you want to pull the schemas into a directory which already contains schemas, you can use the `--clear-output` flag.\nThis will clear the output directory entirely before saving the schemas. This is useful if a new version of the schemas\ndoesn't contain some schemas anymore which were present in the previous version.\n\n### Cache\n\nIf you specify a cache directory with the `--cache-dir` flag, the tool will cache the raw schema files downloaded from\nGitHub. This cache is version specific and will be overridden if you want to download another version.\nThis is useful if you want to execute the tool multiple times with the same version. It will save you some time during\ndevelopment.\n\n## How to use this Repository on Your Machine\n\nFollow the instructions in our [Python template repository](https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine).\n\n## Contribute\n\nYou are very welcome to contribute to this repository by opening a pull request against the main branch.\n\n### GitHub Actions\n\n- Dependabot auto-approve / -merge:\n - If the actor is the Dependabot bot (i.e. on every commit by Dependabot)\n the pull request is automatically approved and auto merge gets activated\n (using squash merge).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This little (python) tool allows to conveniently pull the BO4E-Schemas of a certain version and to edit them in certain ways.",
"version": "0.0.9",
"project_urls": {
"Changelog": "https://github.com/Hochfrequenz/BO4E-Schema-Tool/releases",
"Homepage": "https://github.com/Hochfrequenz/BO4E-Schema-Tool"
},
"split_keywords": [
"bo4e",
" code-generator",
" schemas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "df61b30f3dd097649935312bf9504658b1e96c31d3f0f2c0db3237c51cda6da4",
"md5": "e4488b66a13ee4da4b71d871f6d1097e",
"sha256": "a789ee74965b5a44060ca53def31d8525a6a20cad2b76e21e78af18ce89f0e19"
},
"downloads": -1,
"filename": "bo4e_schema_tool-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4488b66a13ee4da4b71d871f6d1097e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 18089,
"upload_time": "2024-07-31T15:53:29",
"upload_time_iso_8601": "2024-07-31T15:53:29.233628Z",
"url": "https://files.pythonhosted.org/packages/df/61/b30f3dd097649935312bf9504658b1e96c31d3f0f2c0db3237c51cda6da4/bo4e_schema_tool-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "03b2b76bc8136fea3ba84ad442647d471d1ae4997a4d73239b30ecfba07ecdba",
"md5": "ab9c686babe1b980255a668d4a215346",
"sha256": "b14d9d40a811f5170c4beb14097a231c611383d4ad8619113e9aa907802a5348"
},
"downloads": -1,
"filename": "bo4e_schema_tool-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "ab9c686babe1b980255a668d4a215346",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 24036,
"upload_time": "2024-07-31T15:53:30",
"upload_time_iso_8601": "2024-07-31T15:53:30.369732Z",
"url": "https://files.pythonhosted.org/packages/03/b2/b76bc8136fea3ba84ad442647d471d1ae4997a4d73239b30ecfba07ecdba/bo4e_schema_tool-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 15:53:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hochfrequenz",
"github_project": "BO4E-Schema-Tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.6.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2023.7.22"
]
]
},
{
"name": "cffi",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.1"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "cryptography",
"specs": [
[
"==",
"42.0.1"
]
]
},
{
"name": "deprecated",
"specs": [
[
"==",
"1.2.14"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "more-itertools",
"specs": [
[
"==",
"10.3.0"
]
]
},
{
"name": "pycparser",
"specs": [
[
"==",
"2.21"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "pydantic-core",
"specs": [
[
"==",
"2.20.1"
]
]
},
{
"name": "pygithub",
"specs": [
[
"==",
"2.1.1"
]
]
},
{
"name": "pyjwt",
"specs": [
[
"==",
"2.8.0"
]
]
},
{
"name": "pynacl",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.8.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.0.7"
]
]
},
{
"name": "wrapt",
"specs": [
[
"==",
"1.16.0"
]
]
}
],
"tox": true,
"lcname": "bo4e-schema-tool"
}
JSON
