aas-core-codegen 0.0.16__py3-none-any.whl

aas_core_codegen/python/main.py

@@ -0,0 +1,323 @@
+"""Generate Python code to handle AAS models based on the meta-model."""
+from typing import TextIO
+
+from aas_core_codegen import specific_implementations, run, intermediate
+from aas_core_codegen.python import (
+    common as python_common,
+    structure as python_structure,
+    constants as python_constants,
+    aas_common as python_aas_common,
+    stringification as python_stringification,
+    verification as python_verification,
+    jsonization as python_jsonization,
+    xmlization as python_xmlization,
+)
+
+
+def execute(context: run.Context, stdout: TextIO, stderr: TextIO) -> int:
+    """Generate the code."""
+    verified_ir_table, errors = python_structure.verify(
+        symbol_table=context.symbol_table
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to verify the intermediate symbol table "
+            f"for generation of Python code"
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert verified_ir_table is not None
+
+    unsupported_contracts_errors = (
+        intermediate.errors_if_contracts_for_functions_or_methods_defined(
+            verified_ir_table
+        )
+    )
+    if unsupported_contracts_errors is not None:
+        run.write_error_report(
+            message=f"We do not support pre and post-conditions and snapshots "
+            f"at the moment. Please notify the developers if you need this "
+            f"feature (based on meta-model {context.model_path})",
+            errors=[
+                context.lineno_columner.error_message(error)
+                for error in unsupported_contracts_errors
+            ],
+            stderr=stderr,
+        )
+        return 1
+
+    unsupported_methods_errors = (
+        intermediate.errors_if_non_implementation_specific_methods(verified_ir_table)
+    )
+    if unsupported_methods_errors is not None:
+        run.write_error_report(
+            message=f"We added some support for understood methods already and keep "
+            f"maintaining it as it is only a matter of time when we will "
+            f"introduce their transpilation. Introducing them after the fact "
+            f"would have been much more difficult.\n"
+            f"\n"
+            f"At the given moment, however, we deliberately focus only on "
+            f"implementation-specific methods. "
+            f"(based on meta-model {context.model_path})",
+            errors=[
+                context.lineno_columner.error_message(error)
+                for error in unsupported_methods_errors
+            ],
+            stderr=stderr,
+        )
+        return 1
+
+    aas_module_key = specific_implementations.ImplementationKey(
+        "qualified_module_name.txt"
+    )
+
+    aas_module_text = context.spec_impls.get(aas_module_key, None)
+    if aas_module_text is None:
+        stderr.write(
+            f"The snippet with the qualified module name is missing: {aas_module_key}\n"
+        )
+        return 1
+
+    if not python_common.QUALIFIED_MODULE_NAME_RE.fullmatch(aas_module_text):
+        stderr.write(
+            f"The text from the snippet {aas_module_key} "
+            f"is not a valid qualified module name: {aas_module_text!r}\n"
+        )
+        return 1
+
+    aas_module = python_common.QualifiedModuleName(aas_module_text)
+
+    # region Structure
+
+    code, errors = python_structure.generate(
+        symbol_table=verified_ir_table,
+        aas_module=aas_module,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the structures in the Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "types.py"
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the Python structures to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Constants
+
+    code, errors = python_constants.generate(
+        symbol_table=context.symbol_table, aas_module=aas_module
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the constants in the Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "constants.py"
+    pth.parent.mkdir(exist_ok=True)
+
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the constants in the Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Common
+
+    code = python_aas_common.generate(aas_module=aas_module)
+
+    pth = context.output_dir / "common.py"
+    pth.parent.mkdir(exist_ok=True)
+
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the common Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Stringification
+
+    code, errors = python_stringification.generate(
+        symbol_table=context.symbol_table, aas_module=aas_module
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the stringification Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "stringification.py"
+    pth.parent.mkdir(exist_ok=True)
+
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the stringification Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Verification
+
+    verify_errors = python_verification.verify(
+        spec_impls=context.spec_impls,
+        verification_functions=verified_ir_table.verification_functions,
+    )
+
+    if verify_errors is not None:
+        run.write_error_report(
+            message="Failed to verify the Python-specific structures",
+            errors=verify_errors,
+            stderr=stderr,
+        )
+        return 1
+
+    code, errors = python_verification.generate(
+        symbol_table=verified_ir_table,
+        aas_module=aas_module,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the verification Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "verification.py"
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the verification Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Jsonization
+
+    code, errors = python_jsonization.generate(
+        symbol_table=context.symbol_table,
+        aas_module=aas_module,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the jsonization Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "jsonization.py"
+    pth.parent.mkdir(exist_ok=True)
+
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the jsonization Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region Xmlization
+
+    code, errors = python_xmlization.generate(
+        symbol_table=context.symbol_table,
+        aas_module=aas_module,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the xmlization Python code "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert code is not None
+
+    pth = context.output_dir / "xmlization.py"
+    pth.parent.mkdir(exist_ok=True)
+
+    try:
+        pth.write_text(code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the xmlization Python code to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    stdout.write(f"Code generated to: {context.output_dir}\n")
+    return 0

aas_core_codegen/python/naming.py

@@ -0,0 +1,255 @@
+"""Generate Python identifiers based on the identifiers from the meta-model."""
+from typing import Union
+
+from icontract import require
+
+from aas_core_codegen import intermediate, naming
+from aas_core_codegen.common import Identifier, assert_never
+
+
+# fmt: off
+@require(
+    lambda identifier: identifier[0].isupper(),
+    "Enumeration name must start with a capital letter"
+)
+# fmt: on
+def enum_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for an enum based on its meta-model ``identifier``.
+
+    >>> enum_name(Identifier("Something"))
+    'Something'
+
+    >>> enum_name(Identifier("URL_to_something"))
+    'URLToSomething'
+
+    >>> enum_name(Identifier("Something_to_URL"))
+    'SomethingToURL'
+    """
+    parts = identifier.split("_")
+
+    return Identifier(
+        "".join(part if part.upper() == part else part.capitalize() for part in parts)
+    )
+
+
+# fmt: off
+@require(
+    lambda identifier:
+    identifier[0].isupper(),
+    "Class names must start with a capital letter"
+)
+# fmt: on
+def class_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a class based on its meta-model ``identifier``.
+
+    >>> class_name(Identifier("Something"))
+    'Something'
+
+    >>> class_name(Identifier("URL_to_something"))
+    'URLToSomething'
+
+    >>> class_name(Identifier("Something_to_URL"))
+    'SomethingToURL'
+    """
+    parts = identifier.split("_")
+
+    return Identifier(
+        "".join(part if part == part.upper() else part.capitalize() for part in parts)
+    )
+
+
+def name_of(
+    something: Union[
+        intermediate.Enumeration, intermediate.AbstractClass, intermediate.ConcreteClass
+    ]
+) -> Identifier:
+    """Dispatch the name based on the run-time type of ``something``."""
+    if isinstance(something, intermediate.Enumeration):
+        return enum_name(something.name)
+
+    elif isinstance(
+        something, (intermediate.AbstractClass, intermediate.ConcreteClass)
+    ):
+        return class_name(something.name)
+
+    else:
+        assert_never(something)
+
+
+def enum_literal_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for an enum literal based on its meta-model ``identifier``.
+
+    >>> enum_literal_name(Identifier("something"))
+    'SOMETHING'
+
+    >>> enum_literal_name(Identifier("URL_to_something"))
+    'URL_TO_SOMETHING'
+    """
+    return naming.upper_snake_case(identifier)
+
+
+def private_constant_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a constant based on its meta-model ``identifier``.
+
+    >>> private_constant_name(Identifier("something"))
+    '_SOMETHING'
+
+    >>> private_constant_name(Identifier("URL_to_something"))
+    '_URL_TO_SOMETHING'
+    """
+    return Identifier(f"_{naming.upper_snake_case(identifier)}")
+
+
+def constant_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a constant based on its meta-model ``identifier``.
+
+    >>> constant_name(Identifier("something"))
+    'SOMETHING'
+
+    >>> constant_name(Identifier("URL_to_something"))
+    'URL_TO_SOMETHING'
+    """
+    return naming.upper_snake_case(identifier)
+
+
+# fmt: off
+@require(
+    lambda identifier:
+    identifier[0].isupper(),
+    "Class names must start with a capital letter"
+)
+# fmt: on
+def private_class_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a priave class based on its meta-model ``identifier``.
+
+    >>> private_class_name(Identifier("Something"))
+    '_Something'
+
+    >>> private_class_name(Identifier("URL_to_something"))
+    '_URLToSomething'
+    """
+    parts = identifier.split("_")
+
+    return Identifier(
+        "_"
+        + "".join(part if part.upper() == part else part.capitalize() for part in parts)
+    )
+
+
+def property_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a public property based on its meta-model ``identifier``.
+
+    >>> property_name(Identifier("something"))
+    'something'
+
+    >>> property_name(Identifier("something_to_URL"))
+    'something_to_url'
+
+    >>> property_name(Identifier("URL_to_something"))
+    'url_to_something'
+    """
+    return naming.lower_snake_case(identifier)
+
+
+def private_property_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a private property based on the ``identifier``.
+
+    >>> private_property_name(Identifier("something"))
+    '_something'
+
+    >>> private_property_name(Identifier("something_to_URL"))
+    '_something_to_url'
+
+    >>> private_property_name(Identifier("URL_to_something"))
+    '_url_to_something'
+    """
+    return Identifier(f"_{naming.lower_snake_case(identifier)}")
+
+
+def private_method_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a private method based on the ``identifier``.
+
+    >>> private_method_name(Identifier("something"))
+    '_something'
+
+    >>> private_method_name(Identifier("something_to_URL"))
+    '_something_to_url'
+
+    >>> private_method_name(Identifier("URL_to_something"))
+    '_url_to_something'
+    """
+    return Identifier(f"_{naming.lower_snake_case(identifier)}")
+
+
+def private_function_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a private function from its meta-model ``identifier``.
+
+    >>> private_function_name(Identifier("do_something"))
+    '_do_something'
+
+    >>> private_function_name(Identifier("do_something_to_URL"))
+    '_do_something_to_url'
+    """
+    return Identifier(f"_{naming.lower_snake_case(identifier)}")
+
+
+def function_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a function from its meta-model ``identifier``.
+
+    >>> function_name(Identifier("do_something"))
+    'do_something'
+
+    >>> function_name(Identifier("do_something_to_URL"))
+    'do_something_to_url'
+    """
+    return naming.lower_snake_case(identifier)
+
+
+def method_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for an instance method based on its meta-model ``identifier``.
+
+    >>> method_name(Identifier("do_something"))
+    'do_something'
+
+    >>> method_name(Identifier("do_something_to_URL"))
+    'do_something_to_url'
+    """
+    return naming.lower_snake_case(identifier)
+
+
+def argument_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for an argument based on its meta-model ``identifier``.
+
+    >>> argument_name(Identifier("something"))
+    'something'
+
+    >>> argument_name(Identifier("something_to_URL"))
+    'something_to_url'
+    """
+    return naming.lower_snake_case(identifier)
+
+
+def variable_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a variable based on its meta-model ``identifier``.
+
+    >>> variable_name(Identifier("something"))
+    'something'
+
+    >>> variable_name(Identifier("something_to_URL"))
+    'something_to_url'
+    """
+    return naming.lower_snake_case(identifier)

aas_core_codegen/python/stringification/__init__.py

@@ -0,0 +1,4 @@
+"""Generate Python code for de-serialization of enumerations from strings."""
+from aas_core_codegen.python.stringification import _generate
+
+generate = _generate.generate

aas_core_codegen/python/stringification/_generate.py

@@ -0,0 +1,129 @@
+"""Generate Python code for de-serialization of enumerations."""
+
+import io
+from typing import Tuple, Optional, List
+
+from icontract import ensure
+
+from aas_core_codegen import intermediate
+from aas_core_codegen.common import Error, Stripped, Identifier
+from aas_core_codegen.python import common as python_common, naming as python_naming
+from aas_core_codegen.python.common import INDENT as I, INDENT2 as II
+
+
+def _generate_enum_from_string(
+    enumeration: intermediate.Enumeration, aas_module: python_common.QualifiedModuleName
+) -> Stripped:
+    """Generate the functions for de-serializing enumeration from strings."""
+    blocks = []  # type: List[Stripped]
+
+    name = python_naming.enum_name(enumeration.name)
+
+    # region From-string-map
+
+    from_str_map_name = python_naming.constant_name(
+        Identifier(f"_{enumeration.name}_from_str")
+    )
+
+    from_str_map_writer = io.StringIO()
+    from_str_map_writer.write(
+        f"""\
+{from_str_map_name}: Mapping[str, aas_types.{name}] = {{
+"""
+    )
+
+    for literal in enumeration.literals:
+        literal_name = python_naming.enum_literal_name(literal.name)
+        from_str_map_writer.write(
+            f"{I}{python_common.string_literal(literal.value)}: "
+            f"aas_types.{name}.{literal_name},\n"
+        )
+
+    from_str_map_writer.write("}")
+
+    blocks.append(Stripped(from_str_map_writer.getvalue()))
+
+    # endregion
+
+    # region From-string-function
+
+    from_str_name = python_naming.function_name(
+        Identifier(f"{enumeration.name}_from_str")
+    )
+
+    from_str_writer = io.StringIO()
+    from_str_writer.write(
+        f"""\
+def {from_str_name}(
+{II}text: str
+) -> Optional[aas_types.{name}]:
+{I}\"\"\"
+{I}Parse :paramref:`text` as string representation
+{I}of :py:class:`{aas_module}.{name}`.
+
+{I}If :paramref:`text` is not a valid string representation of a literal
+{I}of :py:class:`{aas_module}.{name}`, return ``None``.
+
+{I}:param text: to be parsed
+{I}:return:
+{II}the corresponding literal of :py:class:`{aas_module}.{name}`
+{II}or ``None``, if :paramref:`text` invalid.
+{I}\"\"\"
+{I}return {from_str_map_name}.get(text, None)"""
+    )
+
+    blocks.append(Stripped(from_str_writer.getvalue()))
+
+    # endregion
+
+    return Stripped("\n\n\n".join(blocks))
+
+
+# fmt: off
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+@ensure(
+    lambda result:
+    not (result[0] is not None) or result[0].endswith('\n'),
+    "Trailing newline mandatory for valid end-of-files"
+)
+# fmt: on
+def generate(
+    symbol_table: intermediate.SymbolTable,
+    aas_module: python_common.QualifiedModuleName,
+) -> Tuple[Optional[str], Optional[List[Error]]]:
+    """
+    Generate the Python code for the de-serialization of strings.
+
+    The ``aas_module`` indicates the fully-qualified name of the base module.
+    """
+    blocks = [
+        Stripped('"""De-serialize enumerations from string representations."""'),
+        python_common.WARNING,
+        Stripped(
+            f"""\
+from typing import (
+{I}Mapping,
+{I}Optional,
+)
+
+import {aas_module}.types as aas_types"""
+        ),
+    ]
+
+    for enum in symbol_table.enumerations:
+        blocks.append(
+            _generate_enum_from_string(enumeration=enum, aas_module=aas_module)
+        )
+
+    blocks.append(python_common.WARNING)
+
+    out = io.StringIO()
+    for i, block in enumerate(blocks):
+        if i > 0:
+            out.write("\n\n\n")
+
+        out.write(block)
+
+    out.write("\n")
+
+    return out.getvalue(), None