Commit ed090dfd authored by Michael Thies's avatar Michael Thies
Browse files

readme: Some rewording, restructuering; add list of depdencies

parent b27ed194
Pipeline #259900 passed with stage
in 3 minutes and 46 seconds
# PyI40AAS – Python Industry 4.0 Asset Administration Shell
The PyI40AAS project aims to provide an implementation of the Asset Administration Shell for Industry 4.0 Systems, compliant
The PyI40AAS project aims to provide an implementation of the Asset Administration Shell (AAS) for Industry 4.0 Systems, compliant
with the meta model and interface specification provided in
[the document “Details of the Asset Administration Shell” (v2.0)](https://www.plattform-i40.de/PI40/Redaktion/DE/Downloads/Publikation/Details-of-the-Asset-Administration-Shell-Part1.html).
The implementation will include the data model as well as interface adapters for serving, retrieving, importing and
......@@ -12,21 +12,38 @@ exporting Asset Administration Shells.
The `aas`-package provides the following features:
* Modelling of Asset Administration Shells as Python objects
* (de)-serialization of Asset Administration Shells from and to python objects
(currently supported file/text formats: `JSON`, `XML`)
* `CouchDB`-storage backend
* Compliance Checks to `JSON` and `XML` schemas
* Modelling of AASs as Python objects (according to DotAAS sec. 4)
* (De-)serialization of AAS objects into/from JSON and XML (according to DotAAS sec. 5)
* Reading and writing of AASX package files (according to DotAAS sec. 7)
* Storing of AAS objects in CouchDB
* Compliance checking of AAS XML and JSON files
### Project Structure
The `aas`-package is structured into 5 submodules. For an overview, consider this project structure:
The PyI40AAS package provides the Python `aas`-package with 5 submodules:
* `aas.model`: The AAS metamodel implemented in python
* `aas.adapter`: Adapter to various file formats
* `aas.compliance_tools`: Check compliance to `JSON` and `XML` schemas
* `aas.adapter`: Adapters for various file formats and storage backends
* `aas.compliance_tools`: Compliance checker for AAS files
* `aas.util`: Provides utilities
* `aas.examples`: Examples and tutorials
* `aas.examples`: Example data and tutorials
## License
The PyI40AAS project is provided under the terms of the Apache License (Version 2.0).
For more information, especially considering the licenses of included third-party works, please consult the `NOTICE`
file.
## Dependencies
PyI40AAS requires the following Python packages to be installed for production usage:
* `python-dateutil` (BSD 3-clause License)
* `lxml` (BSD 3-clause License, using `libxml2` under MIT License)
* `pyecma376-2` (Apache License v2.0)
## Getting Started
......@@ -42,7 +59,7 @@ pip install pyi40aas
### Example
Creation of a `Submodel` with a `Propery` and serialization of said `Submodel` to `XML`:
The following code example shows how to create a `Submodel` with a `Property` serialize it into an XML file using PyI40AAS:
Create a `Submodel`:
```python
......@@ -72,14 +89,14 @@ property = model.Property(
submodel.submodel_element.add(property)
```
Serialize the `Submodel` to `XML`:
Serialize the `Submodel` to XML:
```python
import aas.adapter.xml.xml_serialization
data: model.DictObjectStore[model.Identifiable] = model.DictObjectStore()
data.add(submodel)
file = io.BytesIO()
aas.adapter.xml.xml_serialization.write_aas_xml_file(file=file, data=data)
with open('Simple_Submodel.xml', 'w', encoding='utf-8') as f:
aas.adapter.xml.xml_serialization.write_aas_xml_file(file=f, data=data)
```
......@@ -92,58 +109,40 @@ submodel reference
* `examples.tutorial_serialization_deserialization_json`: Tutorial for the serialization and deserialization of asset
administration shells, submodels and assets
* `examples.tutorial_storage`: Tutorial for storing asset administration shells, submodels and assets
* `examples.data`: Package containing simple creator functions for various example objects for testing purposes
## Contributing
When contributing to this repository, please first discuss the change you wish to make via issue,
email, or any other method with the owners of this repository before making a change.
If you plan contributing code to the PyI40AAS project, please get in touch with us via E-Mail first: m.thies@plt.rwth-aachen.de
### Codestyle and Testing
Our code follows the [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/) and especially
the in [PEP 484 -- Type Hints](https://www.python.org/dev/peps/pep-0484/) introduced type hints in the form:
```python
def function(variable: type) -> type:
"""
This line is a short description of the function
In this optional line(s) you can have a long description, or annotations for using this function
:param variable: Here the variable is explained
:return: Here the return of the function is explained
"""
do something
return object
```
Before pushing anything to the repository, make sure that you test your changes with `mypy`, `pycodestyle` and
`unittest`. To install those, use:
```
pip install mypy
pip install pycodestyle
```
The tests for the `unittest` are located in the `test`-package, which has the same structure as the `aas`-package. We
expect at least 80% coverage per module.
Our code follows the [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/).
Additionally, we use [PEP 484 -- Type Hints](https://www.python.org/dev/peps/pep-0484/) throughout the code to enable type checking the code.
Please make sure that running:
Before submitting any changes, make sure to let `mypy` and `pycodestyle` check your code and run the unit tests with
Python's builtin `unittest`. To install the required tools, use:
```bash
pip install mypy pycodestyle
```
Running all checks:
```bash
mypy aas test
python -m pycodestyle --max-line-length 120 aas test
python -m unittest
```
does not result in any error, before pushing.
### Contribute Code/Patches
We aim to cover our code with test by at least 80%. To check test coverage, you can use `coverage`:
```bash
pip install coverage
coverage run --source aas --branch -m unittest
coverage report -m
```
## License
The PyI40AAS project is provided under the terms of the Apache License (Version 2.0).
### Contribute Code/Patches
For more information, especially considering the licenses of included third-party works, please consult the `NOTICE`
file.
TBD
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment