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

aas_core_codegen/python_protobuf/naming.py

@@ -0,0 +1,85 @@
+"""Emulate naming logic for our types to Protocol Buffers in Python code."""
+
+from aas_core_codegen.common import Identifier
+from aas_core_codegen import naming
+
+
+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'
+    """
+    return naming.capitalized_camel_case(identifier)
+
+
+def enum_literal_constant_name(
+    enumeration_name: Identifier, literal_name: Identifier
+) -> Identifier:
+    """
+    Generate a constant identifier for an enum literal in the meta-model.
+
+    >>> enum_literal_constant_name(
+    ...     Identifier("that"), Identifier("literal")
+    ... )
+    'That_LITERAL'
+
+    >>> enum_literal_constant_name(
+    ...     Identifier("URL_to_something"), Identifier("ABC_shines")
+    ... )
+    'Urltosomething_ABC_SHINES'
+
+    >>> enum_literal_constant_name(
+    ...     Identifier("Modelling_kind"), Identifier("Template")
+    ... )
+    'Modellingkind_TEMPLATE'
+    """
+    enum_name_joined = "".join(enumeration_name.split("_"))
+
+    return Identifier(f"{enum_name_joined.capitalize()}_{literal_name.upper()}")
+
+
+def property_name(identifier: Identifier) -> Identifier:
+    """
+    Generate the name of the property in a Protocol Buffer generated class.
+
+    >>> 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 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'
+    """
+    return naming.capitalized_camel_case(identifier)
+
+
+def choice_class_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a name for a choice (union) class based on its meta-model ``identifier``.
+
+    >>> choice_class_name(Identifier("something"))
+    'Something_choice'
+
+    >>> choice_class_name(Identifier("URL_to_something"))
+    'UrlToSomething_choice'
+    """
+    return Identifier(naming.capitalized_camel_case(identifier) + "_choice")

aas_core_codegen/rdf_shacl/__init__.py

@@ -0,0 +1 @@
+"""Generate the RDF ontology and the SHACL schema corresponding to the meta-model."""

aas_core_codegen/rdf_shacl/_description.py

@@ -0,0 +1,351 @@
+"""Render the description of a class or a property as a plain text."""
+from typing import Optional, List, Tuple, Sequence, cast, Union
+
+import docutils.nodes
+from icontract import ensure
+
+from aas_core_codegen.common import assert_never, assert_union_of_descendants_exhaustive
+from aas_core_codegen.intermediate import (
+    doc as intermediate_doc,
+)
+from aas_core_codegen.rdf_shacl import naming as rdf_shacl_naming
+
+# NOTE (mristin, 2022-03-23):
+# The representation of the documentation as tokens was definitely a wrong decision.
+# However, we do not prioritize descriptions in RDF+SHACL at the moment, so we leave out
+# the refactoring for now. A better approach would be to first transform
+# into a nested structure similar to HTML (paragraph, unordered list, ordered list,
+# *etc.*) and then render this nested structure in a separate step.
+
+
+class Token:
+    """Represent a token of a rendered description."""
+
+
+class TokenText(Token):
+    """Represent a text without a break."""
+
+    def __init__(self, content: str) -> None:
+        """Initialize with the given values."""
+        self.content = content
+
+    def __repr__(self) -> str:
+        return f"{TokenText.__name__}({self.content!r})"
+
+
+class TokenParagraphBreak(Token):
+    """Represent a paragraph break in a rendered description."""
+
+    def __repr__(self) -> str:
+        return f"{TokenParagraphBreak.__name__}()"
+
+
+class TokenLineBreak(Token):
+    """Represent a line break in a rendered description."""
+
+    def __repr__(self) -> str:
+        return f"{TokenLineBreak.__name__}()"
+
+
+def without_trailing_breaks(tokens: Sequence["TokenUnion"]) -> List["TokenUnion"]:
+    """Remove all the trailing breaks at the end of the ``tokens``."""
+    result = list(tokens)
+
+    first_non_break = None  # type: Optional[int]
+    for i, token in enumerate(reversed(result)):
+        if not isinstance(token, (TokenLineBreak, TokenParagraphBreak)):
+            first_non_break = i
+            break
+
+    if first_non_break is None:
+        result = []
+
+    elif first_non_break == 0:
+        pass
+
+    else:
+        result = result[:-first_non_break]  # pylint: disable=invalid-unary-operand-type
+
+    return result
+
+
+def without_redundant_breaks(tokens: Sequence["TokenUnion"]) -> List["TokenUnion"]:
+    """Remove the redundant breaks from ``tokens`` and return a cleaned-up list."""
+    if len(tokens) == 0:
+        return []
+
+    last_token = None  # type: Optional[TokenUnion]
+    result = []  # type: List[TokenUnion]
+
+    # region Remove multiple consecutive paragraph breaks and line breaks
+
+    for token in tokens:
+        if last_token is None:
+            result.append(token)
+        elif isinstance(last_token, TokenLineBreak) and isinstance(
+            token, TokenLineBreak
+        ):
+            pass
+        elif isinstance(last_token, TokenParagraphBreak) and isinstance(
+            token, TokenParagraphBreak
+        ):
+            pass
+        else:
+            result.append(token)
+
+        last_token = token
+
+    # endregion
+
+    result = without_trailing_breaks(tokens=result)
+
+    return result
+
+
+class Renderer(intermediate_doc.DocutilsElementTransformer[List["TokenUnion"]]):
+    """Render descriptions as C# docstring XML."""
+
+    # fmt: off
+    @ensure(
+        lambda result:
+        not (result[0] is not None)
+        or (
+                all(
+                    '\n' not in token.content
+                    for token in result[0]
+                    if isinstance(token, TokenText)
+                )))
+    # fmt: on
+    def transform_text(
+        self, element: docutils.nodes.Text
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        return [TokenText(element.astext().replace("\n", " "))], None
+
+    def transform_reference_to_our_type_in_doc(
+        self, element: intermediate_doc.ReferenceToOurType
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        cls_name = rdf_shacl_naming.class_name(element.our_type.name)
+        return [TokenText(f"'{cls_name}'")], None
+
+    def transform_reference_to_attribute_in_doc(
+        self, element: intermediate_doc.ReferenceToAttribute
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        if isinstance(element.reference, intermediate_doc.ReferenceToProperty):
+            prop_name = rdf_shacl_naming.property_name(element.reference.prop.name)
+            return [TokenText(f"'{prop_name}'")], None
+
+        elif isinstance(
+            element.reference, intermediate_doc.ReferenceToEnumerationLiteral
+        ):
+            literal_name = rdf_shacl_naming.enumeration_literal(
+                element.reference.literal.name
+            )
+
+            return [TokenText(f"'{literal_name}'")], None
+
+        else:
+            assert_never(element.reference)
+
+    def transform_reference_to_argument_in_doc(
+        self, element: intermediate_doc.ReferenceToArgument
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        # Argument references are not really meaningful for SHACL, so we just
+        # return them as-is.
+        return [TokenText(element.reference)], None
+
+    def transform_reference_to_constraint_in_doc(
+        self, element: intermediate_doc.ReferenceToConstraint
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        return [TokenText(f"Constraint {element.reference}")], None
+
+    def transform_reference_to_constant_in_doc(
+        self, element: intermediate_doc.ReferenceToConstant
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        # NOTE (mristin, 2022-07-10):
+        # We simply use class label here to obtain some name here. The constants are
+        # not defined in the schemas, so we can not really reference them in some
+        # meaningful way.
+
+        return [TokenText(rdf_shacl_naming.class_name(element.constant.name))], None
+
+    def transform_literal(
+        self, element: docutils.nodes.literal
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        return [TokenText(element.astext())], None
+
+    def transform_paragraph(
+        self, element: docutils.nodes.paragraph
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List["TokenUnion"]
+        errors = []  # type: List[str]
+
+        for child in element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+
+        if len(errors) > 0:
+            return None, errors
+
+        tokens.append(TokenParagraphBreak())
+
+        return tokens, None
+
+    def transform_emphasis(
+        self, element: docutils.nodes.emphasis
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List["TokenUnion"]
+        errors = []  # type: List[str]
+
+        for child in element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+
+        if len(errors) > 0:
+            return None, errors
+
+        return tokens, None
+
+    def transform_list_item(
+        self, element: docutils.nodes.list_item
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        if len(element.children) != 1 or not isinstance(
+            element.children[0], docutils.nodes.paragraph
+        ):
+            return None, [
+                (
+                    f"Expected the list item to contain a single child (paragraph), "
+                    f"but got: {element}"
+                )
+            ]
+
+        para_element = element.children[0]
+
+        tokens = []  # type: List["TokenUnion"]
+
+        if len(para_element.children) == 0:
+            return [TokenText("* (empty)")], None
+
+        errors = []  # type: List[str]
+
+        for child in para_element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.append(TokenText("* "))
+                tokens.extend(child_tokens)
+
+        if len(errors) > 0:
+            return None, errors
+
+        return tokens, None
+
+    def transform_bullet_list(
+        self, element: docutils.nodes.bullet_list
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List["TokenUnion"]
+        errors = []  # type: List[str]
+
+        for child in element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+                tokens.append(TokenLineBreak())
+
+        if len(errors) > 0:
+            return None, errors
+
+        return tokens, None
+
+    def transform_note(
+        self, element: docutils.nodes.note
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List["TokenUnion"]
+        errors = []  # type: List[str]
+
+        for child in element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+
+        if len(errors) > 0:
+            return None, errors
+
+        tokens = (
+            cast(List["TokenUnion"], [TokenText("NOTE:"), TokenLineBreak()]) + tokens
+        )
+
+        return tokens, None
+
+    def transform_reference(
+        self, element: docutils.nodes.reference
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List["TokenUnion"]
+        errors = []  # type: List[str]
+
+        for child in element.children:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+                tokens.append(TokenLineBreak())
+
+        if len(errors) > 0:
+            return None, errors
+
+        return tokens, None
+
+    def transform_field_body(
+        self, element: docutils.nodes.field_body
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List[TokenUnion]
+        errors = []  # type: List[str]
+
+        for child in element:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+
+        result = without_redundant_breaks(tokens=tokens)
+        return result, None
+
+    def transform_document(
+        self, element: docutils.nodes.document
+    ) -> Tuple[Optional[List["TokenUnion"]], Optional[List[str]]]:
+        tokens = []  # type: List[TokenUnion]
+        errors = []  # type: List[str]
+
+        for child in element:
+            child_tokens, child_errors = self.transform(child)
+            if child_errors is not None:
+                errors.extend(child_errors)
+            else:
+                assert child_tokens is not None
+                tokens.extend(child_tokens)
+
+        result = without_redundant_breaks(tokens=tokens)
+        return result, None
+
+
+TokenUnion = Union[TokenText, TokenParagraphBreak, TokenLineBreak]
+assert_union_of_descendants_exhaustive(union=TokenUnion, base_class=Token)

aas_core_codegen/rdf_shacl/common.py

@@ -0,0 +1,206 @@
+"""Provide common functions for both RDF and SHACL generators."""
+from typing import MutableMapping, Tuple, Optional, List
+
+from icontract import ensure
+
+from aas_core_codegen import intermediate, specific_implementations
+from aas_core_codegen.common import (
+    Stripped,
+    Error,
+    assert_never,
+    Identifier,
+)
+from aas_core_codegen.rdf_shacl import naming as rdf_shacl_naming
+
+INDENT = "    "
+INDENT2 = INDENT * 2
+INDENT3 = INDENT * 3
+INDENT4 = INDENT * 4
+
+
+def string_literal(text: str) -> Stripped:
+    """Generate a valid and escaped string literal based on the free-form ``text``."""
+    if len(text) == 0:
+        return Stripped('""')
+
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return Stripped(f'"{escaped}"')
+
+
+OurTypeToRdfsRange = MutableMapping[intermediate.OurType, Stripped]
+
+
+EXPLANATION_ABOUT_WHY_WE_EXPECT_LANG_STRING = (
+    "(mristin, 2022-09-01) "
+    "We hard-wire the langString's to rdf:langString. Admittedly, this is "
+    "hacky. We could have made the class ``Lang_string`` "
+    "implementation-specific and defined its ``rdfs:range`` manually as "
+    "a snippet.\n\n"
+    "However, we decided against that as such a design would force us to "
+    "define langString for every language and schema which do not natively "
+    "support it, write custom data generation methods *etc.* Given that "
+    "RDF+SHACL codegen is one out of many code generators we leave the "
+    "other code generators and test data generators as simple as possible, "
+    "and make this code generator a bit hacky in return."
+)
+
+
+@ensure(
+    lambda result: not (result[1] is not None) or (result[0] is None),
+    "If there is an error, the class must not be found.",
+)
+def get_lang_string_as_expected(
+    symbol_table: intermediate.SymbolTable,
+) -> Tuple[Optional[intermediate.ConcreteClass], Optional[Error]]:
+    """
+    Try to retrieve the ``Lang_string`` as a concrete class.
+
+    In some metamodels, we do define ``Lang_string`` and can hard-wire schema generation
+    in RDF and SHACL with it. However, in other models, we dispensed of ``Lang_string``.
+    Therefore, this function is not guaranteed to return a class. If there is no
+    ``Lang_string`` in the symbol table, no error will be returned!
+
+    However, if ``Lang_string`` exists as a class, it must be a concrete class. If it
+    does not fulfill the expectations, an error will be returned.
+    """
+    lang_string_cls = symbol_table.find_our_type(Identifier("Lang_string"))
+    if lang_string_cls is not None:
+        if not isinstance(lang_string_cls, intermediate.ConcreteClass):
+            return (
+                None,
+                Error(
+                    None,
+                    f"Expected ``Lang_string`` to be specified as "
+                    f"a concrete class in the meta model, but it has been defined "
+                    f"as: {type(lang_string_cls)}.\n\n"
+                    + EXPLANATION_ABOUT_WHY_WE_EXPECT_LANG_STRING,
+                ),
+            )
+
+    return lang_string_cls, None
+
+
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def map_our_type_to_rdfs_range(
+    symbol_table: intermediate.SymbolTable,
+    spec_impls: specific_implementations.SpecificImplementations,
+) -> Tuple[Optional[OurTypeToRdfsRange], Optional[Error]]:
+    """
+    Iterate over all our types and determine their value as ``rdfs:range``.
+
+    This also applies for ``sh:datatype`` in SHACL.
+    """
+    our_type_to_rdfs_range = dict()  # type: OurTypeToRdfsRange
+    errors = []  # type: List[Error]
+
+    lang_string_cls, lang_string_error = get_lang_string_as_expected(
+        symbol_table=symbol_table
+    )
+    if lang_string_error is not None:
+        return None, lang_string_error
+
+    for our_type in symbol_table.our_types:
+        if our_type is lang_string_cls:
+            # NOTE (mristin, 2022-09-01):
+            # Please see
+            # :py:const`aas_core_codegen.rdf_shacl.common._EXPLANATION_ABOUT_WHY_WE_EXPECT_LANG_STRING`
+            # on why we hard-wire ``Lang_string`` here.
+            our_type_to_rdfs_range[our_type] = Stripped("rdf:langString")
+
+        elif isinstance(
+            our_type, (intermediate.AbstractClass, intermediate.ConcreteClass)
+        ):
+            if our_type.is_implementation_specific:
+                implementation_key = specific_implementations.ImplementationKey(
+                    f"rdf/{our_type.name}/as_rdfs_range.ttl"
+                )
+                implementation = spec_impls.get(implementation_key, None)
+                if implementation is None:
+                    errors.append(
+                        Error(
+                            our_type.parsed.node,
+                            f"The implementation snippet for "
+                            f"how to represent the class {our_type.parsed.name} "
+                            f"as ``rdfs:range`` is missing: {implementation_key}",
+                        )
+                    )
+                else:
+                    our_type_to_rdfs_range[our_type] = implementation
+            else:
+                # NOTE (mristin, 2022-09-01):
+                # We do not define any special rdfs:range for the class. The function
+                # :function:`.rdfs_range_for_type_annotation` will take care of the
+                # general cases.
+                pass
+
+        else:
+            # NOTE (mristin, 2022-09-01):
+            # No pre-defined rdfs:range for this our type.
+            pass
+
+    if len(errors) > 0:
+        return None, Error(
+            None,
+            "Failed to determine the mapping our type 🠒 ``rdfs:range`` "
+            "for one or more of our types",
+            errors,
+        )
+
+    return our_type_to_rdfs_range, None
+
+
+PRIMITIVE_MAP = {
+    intermediate.PrimitiveType.BOOL: "xs:boolean",
+    intermediate.PrimitiveType.INT: "xs:long",
+    intermediate.PrimitiveType.FLOAT: "xs:double",
+    intermediate.PrimitiveType.STR: "xs:string",
+    intermediate.PrimitiveType.BYTEARRAY: "xs:base64Binary",
+}
+
+
+def rdfs_range_for_type_annotation(
+    type_annotation: intermediate.TypeAnnotationUnion,
+    our_type_to_rdfs_range: OurTypeToRdfsRange,
+) -> Stripped:
+    """Determine the ``rdfs:range`` corresponding to the ``type_annotation``."""
+    type_anno = intermediate.beneath_optional(type_annotation)
+
+    rdfs_range: str
+
+    if isinstance(type_anno, intermediate.PrimitiveTypeAnnotation):
+        rdfs_range = PRIMITIVE_MAP[type_anno.a_type]
+
+    elif isinstance(type_anno, intermediate.OurTypeAnnotation):
+        maybe_rdfs_range = our_type_to_rdfs_range.get(type_anno.our_type, None)
+
+        if maybe_rdfs_range is None:
+            if isinstance(
+                type_anno.our_type,
+                (
+                    intermediate.Enumeration,
+                    intermediate.AbstractClass,
+                    intermediate.ConcreteClass,
+                ),
+            ):
+                cls_name = rdf_shacl_naming.class_name(type_anno.our_type.name)
+                rdfs_range = f"aas:{cls_name}"
+
+            elif isinstance(type_anno.our_type, intermediate.ConstrainedPrimitive):
+                rdfs_range = PRIMITIVE_MAP[type_anno.our_type.constrainee]
+            else:
+                assert_never(type_anno.our_type)
+        else:
+            rdfs_range = maybe_rdfs_range
+
+    elif isinstance(type_anno, intermediate.ListTypeAnnotation):
+        rdfs_range = rdfs_range_for_type_annotation(
+            type_annotation=type_anno.items,
+            our_type_to_rdfs_range=our_type_to_rdfs_range,
+        )
+    else:
+        assert_never(type_anno)
+
+    return Stripped(rdfs_range)
+
+
+assert all(literal in PRIMITIVE_MAP for literal in intermediate.PrimitiveType)