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

aas_core_codegen/rdf_shacl/main.py

@@ -0,0 +1,114 @@
+"""Generate the RDF ontology and the SHACL schema corresponding to the meta-model."""
+
+import pathlib
+from typing import TextIO
+
+import aas_core_codegen
+import aas_core_codegen.rdf_shacl.rdf
+import aas_core_codegen.rdf_shacl.shacl
+from aas_core_codegen import run
+from aas_core_codegen.rdf_shacl import common as rdf_shacl_common
+
+
+class Parameters:
+    """Represent the program parameters."""
+
+    def __init__(
+        self,
+        model_path: pathlib.Path,
+        snippets_dir: pathlib.Path,
+        output_dir: pathlib.Path,
+    ) -> None:
+        """Initialize with the given values."""
+        self.model_path = model_path
+        self.snippets_dir = snippets_dir
+        self.output_dir = output_dir
+
+
+def execute(context: run.Context, stdout: TextIO, stderr: TextIO) -> int:
+    """Generate the code."""
+    # region Dependencies
+
+    our_type_to_rdfs_range, error = rdf_shacl_common.map_our_type_to_rdfs_range(
+        symbol_table=context.symbol_table, spec_impls=context.spec_impls
+    )
+    if error:
+        run.write_error_report(
+            message=f"Failed to determine the mapping our type to ``rdfs:range`` "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error)],
+            stderr=stderr,
+        )
+
+        return 1
+
+    assert our_type_to_rdfs_range is not None
+
+    # endregion
+
+    # region RDF ontology
+
+    rdf_code, errors = aas_core_codegen.rdf_shacl.rdf.generate(
+        symbol_table=context.symbol_table,
+        our_type_to_rdfs_range=our_type_to_rdfs_range,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the RDF ontology "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert rdf_code is not None
+
+    pth = context.output_dir / "rdf-ontology.ttl"
+    try:
+        pth.write_text(rdf_code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the RDF ontology to {pth}",
+            errors=[str(exception)],
+            stderr=stderr,
+        )
+        return 1
+
+    # endregion
+
+    # region SHACL schema
+
+    shacl_code, errors = aas_core_codegen.rdf_shacl.shacl.generate(
+        symbol_table=context.symbol_table,
+        our_type_to_rdfs_range=our_type_to_rdfs_range,
+        spec_impls=context.spec_impls,
+    )
+
+    if errors is not None:
+        run.write_error_report(
+            message=f"Failed to generate the SHACL schema "
+            f"based on {context.model_path}",
+            errors=[context.lineno_columner.error_message(error) for error in errors],
+            stderr=stderr,
+        )
+        return 1
+
+    assert shacl_code is not None
+
+    pth = context.output_dir / "shacl-schema.ttl"
+    try:
+        pth.write_text(shacl_code, encoding="utf-8")
+    except Exception as exception:
+        run.write_error_report(
+            message=f"Failed to write the SHACL schema 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/rdf_shacl/naming.py

@@ -0,0 +1,145 @@
+"""Generate RDF and SHACL identifiers based on the identifiers from the meta-model."""
+from typing import List
+
+from icontract import require
+
+from aas_core_codegen import naming
+from aas_core_codegen.common import Identifier, Stripped
+
+_LOWERCASE_WORDS_IN_LABEL = {"to", "in"}
+
+
+def _capitalized_label(identifier: Identifier) -> Stripped:
+    """
+    Generate the label starting with a capital letter.
+
+    >>> _capitalized_label(Identifier("Something"))
+    'Something'
+
+    >>> _capitalized_label(Identifier("Something_good_to_URL"))
+    'Something Good to URL'
+
+    >>> _capitalized_label(Identifier("URL_to_something"))
+    'URL to Something'
+    """
+    parts = identifier.split("_")
+
+    cased = []  # type: List[str]
+    for part in parts:
+        if part in _LOWERCASE_WORDS_IN_LABEL:
+            cased.append(part.lower())
+        else:
+            if part == part.lower():
+                cased.append(part.capitalize())
+            else:
+                cased.append(part)
+
+    return Stripped(" ".join(cased))
+
+
+# fmt: off
+@require(
+    lambda identifier: identifier[0].isupper(),
+    "The class name must start with a capital letter"
+)
+# fmt: on
+def class_name(identifier: Identifier) -> Identifier:
+    """
+    Generate the class name from the intermediate class ``identifier``.
+
+    >>> class_name(Identifier("Something"))
+    'Something'
+
+    >>> class_name(Identifier("Something_to_URL"))
+    'SomethingToUrl'
+
+    >>> class_name(Identifier("URL_to_something"))
+    'UrlToSomething'
+    """
+    return naming.capitalized_camel_case(identifier)
+
+
+# fmt: off
+@require(
+    lambda identifier: identifier[0].isupper(),
+    "The class name must start with a capital letter"
+)
+# fmt: on
+def class_label(identifier: Identifier) -> Stripped:
+    """
+    Generate the class label from the intermediate class ``identifier``.
+
+    >>> class_label(Identifier("Something"))
+    'Something'
+
+    >>> class_label(Identifier("Something_good_to_URL"))
+    'Something Good to URL'
+
+    >>> class_label(Identifier("URL_to_something"))
+    'URL to Something'
+    """
+    return _capitalized_label(identifier)
+
+
+def property_name(identifier: Identifier) -> Identifier:
+    """
+    Generate a property name based on its meta-model ``identifier``.
+
+    >>> property_name(Identifier("something"))
+    'something'
+
+    >>> property_name(Identifier("something_to_URL"))
+    'somethingToUrl'
+
+    >>> property_name(Identifier("URL_to_something"))
+    'urlToSomething'
+    """
+    return naming.lower_camel_case(identifier)
+
+
+def property_label(identifier: Identifier) -> Stripped:
+    """
+    Generate the property label from the intermediate class ``identifier``.
+
+    >>> property_label(Identifier("something"))
+    'something'
+
+    >>> property_label(Identifier("something_good_to_URL"))
+    'something good to URL'
+
+    >>> property_label(Identifier("URL_to_something"))
+    'URL to something'
+    """
+    return Stripped(" ".join(identifier.split("_")))
+
+
+def enumeration_literal(identifier: Identifier) -> Stripped:
+    """
+    Generate the enumeration literal for its intermediate ``identifier``.
+
+    >>> enumeration_literal(Identifier('something'))
+    'Something'
+
+    >>> enumeration_literal(Identifier("something_to_URL"))
+    'SomethingToUrl'
+
+    >>> enumeration_literal(Identifier("URL_to_something"))
+    'UrlToSomething'
+    """
+    return naming.capitalized_camel_case(identifier)
+
+
+def enumeration_literal_label(identifier: Identifier) -> Stripped:
+    """
+    Generate the label for an enumeration literal with intermediate ``identifier``.
+
+    >>> enumeration_literal_label(Identifier("something"))
+    'Something'
+
+    >>> enumeration_literal_label(Identifier("something_good_to_URL"))
+    'Something Good to URL'
+
+    >>> enumeration_literal_label(Identifier("URL_to_something_good"))
+    'URL to Something Good'
+    """
+    return _capitalized_label(identifier)

aas_core_codegen/rdf_shacl/rdf.py

@@ -0,0 +1,435 @@
+"""Generate the RDF ontology based on the meta-model."""
+import io
+from typing import Tuple, Optional, List
+
+from icontract import ensure, require
+
+from aas_core_codegen import intermediate, specific_implementations
+from aas_core_codegen.common import Stripped, Error, assert_never
+from aas_core_codegen.rdf_shacl import (
+    naming as rdf_shacl_naming,
+    common as rdf_shacl_common,
+    _description as rdf_shacl_description,
+)
+from aas_core_codegen.rdf_shacl.common import INDENT as I, INDENT2 as II
+
+
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def _generate_summary(
+    description: intermediate.DescriptionUnion,
+) -> Tuple[Optional[str], Optional[Error]]:
+    """Generate the comment text based on the summary in the description."""
+    renderer = rdf_shacl_description.Renderer()
+    tokens, errors = renderer.transform(description.summary)
+
+    if errors is not None:
+        return None, Error(
+            description.parsed.node,
+            "Failed to generate the description comment",
+            [Error(description.parsed.node, message) for message in errors],
+        )
+
+    assert tokens is not None
+
+    tokens = rdf_shacl_description.without_redundant_breaks(tokens=tokens)
+
+    parts = []  # type: List[str]
+    for token in tokens:
+        if isinstance(token, rdf_shacl_description.TokenText):
+            parts.append(token.content)
+        elif isinstance(token, rdf_shacl_description.TokenLineBreak):
+            parts.append("\n")
+        elif isinstance(token, rdf_shacl_description.TokenParagraphBreak):
+            parts.append("\n\n")
+        else:
+            assert_never(token)
+
+    result = "".join(parts)
+
+    return result, None
+
+
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def _define_for_enumeration(
+    enumeration: intermediate.Enumeration, xml_namespace: Stripped
+) -> Tuple[Optional[Stripped], Optional[Error]]:
+    """Define an RDF definition of an enumeration."""
+    cls_name = rdf_shacl_naming.class_name(enumeration.name)
+    cls_label = rdf_shacl_naming.class_label(enumeration.name)
+
+    writer = io.StringIO()
+    writer.write(
+        f"""\
+###  {xml_namespace}/{cls_name}
+aas:{cls_name} rdf:type owl:Class ;"""
+    )
+
+    writer.write(
+        f"\n{I}rdfs:label {rdf_shacl_common.string_literal(cls_label)}^^xs:string ;"
+    )
+
+    errors = []  # type: List[Error]
+
+    if enumeration.description is not None:
+        summary, error = _generate_summary(enumeration.description)
+        if error is not None:
+            errors.append(error)
+        else:
+            assert summary is not None
+            writer.write(
+                f"\n{I}rdfs:comment {rdf_shacl_common.string_literal(summary)}@en ;"
+            )
+
+    if len(enumeration.literals) > 0:
+        writer.write(f"\n{I}owl:oneOf (\n")
+
+        # NOTE (mristin, 2022-04-20):
+        # We sort by the literal names so that the URLs are sorted in the resulting
+        # schema.
+        for literal_name in sorted(
+            rdf_shacl_naming.enumeration_literal(literal.name)
+            for literal in enumeration.literals
+        ):
+            writer.write(f"{II}<{xml_namespace}/{cls_name}/{literal_name}>\n")
+
+        writer.write(f"{I}) ;")
+
+    writer.write("\n.")
+
+    if len(enumeration.literals) > 0:
+        # NOTE (mristin, 2022-04-20):
+        # We sort by the literal names so that the URLs are sorted in the resulting
+        # schema.
+        for literal_name, literal in sorted(
+            (rdf_shacl_naming.enumeration_literal(literal.name), literal)
+            for literal in enumeration.literals
+        ):
+            literal_label = rdf_shacl_naming.enumeration_literal_label(literal.name)
+
+            writer.write("\n\n")
+            writer.write(
+                f"""\
+###  {xml_namespace}/{cls_name}/{literal_name}
+<{xml_namespace}/{cls_name}/{literal_name}> rdf:type aas:{cls_name} ;
+{I}rdfs:label {rdf_shacl_common.string_literal(literal_label)}^^xs:string ;"""
+            )
+
+            if literal.description is not None:
+                summary, error = _generate_summary(literal.description)
+                if error is not None:
+                    errors.append(error)
+                else:
+                    assert summary is not None
+                    writer.write(
+                        f"\n{I}rdfs:comment "
+                        f"{rdf_shacl_common.string_literal(summary)}@en ;"
+                    )
+
+            writer.write("\n.")
+
+    if len(errors) > 0:
+        return None, Error(
+            enumeration.parsed.node,
+            "Failed to generate the RDF definition",
+            underlying=errors,
+        )
+
+    return Stripped(writer.getvalue()), None
+
+
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def _define_owl_class_for_class(
+    cls: intermediate.ClassUnion, xml_namespace: Stripped
+) -> Tuple[Optional[Stripped], Optional[Error]]:
+    """Generate the code to define an OWL class."""
+    cls_name = rdf_shacl_naming.class_name(cls.name)
+
+    writer = io.StringIO()
+    writer.write(f"###  {xml_namespace}/{cls_name}\n")
+    writer.write(f"aas:{cls_name} rdf:type owl:Class ;\n")
+
+    for inheritance in cls.inheritances:
+        writer.write(
+            f"{I}rdfs:subClassOf "
+            f"aas:{rdf_shacl_naming.class_name(inheritance.name)} ;\n"
+        )
+
+    cls_label = rdf_shacl_naming.class_label(cls.name)
+    writer.write(
+        f"{I}rdfs:label {rdf_shacl_common.string_literal(cls_label)}^^xs:string ;\n"
+    )
+
+    if cls.description is not None:
+        summary, error = _generate_summary(cls.description)
+        if error is not None:
+            return None, error
+
+        assert summary is not None
+        writer.write(
+            f"{I}rdfs:comment {rdf_shacl_common.string_literal(summary)}@en ;\n"
+        )
+
+    writer.write(".")
+    return Stripped(writer.getvalue()), None
+
+
+@require(lambda prop, cls: id(prop) in cls.property_id_set)
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def _define_property(
+    prop: intermediate.Property,
+    cls: intermediate.ClassUnion,
+    xml_namespace: Stripped,
+    our_type_to_rdfs_range: rdf_shacl_common.OurTypeToRdfsRange,
+) -> Tuple[Optional[Stripped], Optional[Error]]:
+    """Generate the definition of a property ``prop`` of the intermediate ``cls``."""
+    type_anno = intermediate.beneath_optional(prop.type_annotation)
+
+    cls_name = rdf_shacl_naming.class_name(cls.name)
+    rdfs_domain = f"aas:{cls_name}"
+
+    rdf_type = None  # type: Optional[str]
+
+    missing_implementation = False
+
+    if isinstance(type_anno, intermediate.OurTypeAnnotation):
+        if isinstance(
+            type_anno.our_type,
+            (
+                intermediate.Enumeration,
+                intermediate.AbstractClass,
+                intermediate.ConcreteClass,
+            ),
+        ):
+            rdf_type = "owl:ObjectProperty"
+        elif isinstance(type_anno.our_type, intermediate.ConstrainedPrimitive):
+            rdf_type = "owl:DatatypeProperty"
+        else:
+            assert_never(type_anno.our_type)
+
+    elif isinstance(type_anno, intermediate.PrimitiveTypeAnnotation):
+        rdf_type = "owl:DatatypeProperty"
+
+    elif isinstance(type_anno, intermediate.ListTypeAnnotation):
+        type_anno_items = intermediate.beneath_optional(type_anno.items)
+
+        if isinstance(type_anno_items, intermediate.OurTypeAnnotation):
+            rdf_type = "owl:ObjectProperty"
+
+        elif isinstance(type_anno_items, intermediate.PrimitiveTypeAnnotation):
+            rdf_type = "owl:DatatypeProperty"
+
+        else:
+            missing_implementation = True
+    else:
+        missing_implementation = True
+
+    if missing_implementation:
+        return None, Error(
+            prop.parsed.node,
+            f"(mristin, 2021-11-12): "
+            f"We did not refine the definition of the non-atomic and non-sequential "
+            f"properties. If you see this message, it is time to implement "
+            f"this missing functionality.\n"
+            f"{prop=}, {type_anno=}, {cls=}",
+        )
+
+    assert rdf_type is not None
+
+    prop_name = rdf_shacl_naming.property_name(prop.name)
+    prop_label = Stripped(f"has {rdf_shacl_naming.property_label(prop.name)}")
+    rdfs_range = rdf_shacl_common.rdfs_range_for_type_annotation(
+        type_annotation=type_anno, our_type_to_rdfs_range=our_type_to_rdfs_range
+    )
+
+    url = f"{xml_namespace}/{cls_name}/{prop_name}"
+    writer = io.StringIO()
+    writer.write(
+        f"""\
+###  {url}
+<{url}> rdf:type {rdf_type} ;
+{I}rdfs:label {rdf_shacl_common.string_literal(prop_label)}^^xs:string ;
+{I}rdfs:domain {rdfs_domain} ;
+{I}rdfs:range {rdfs_range} ;"""
+    )
+
+    if prop.description:
+        summary, error = _generate_summary(prop.description)
+        if error is not None:
+            return None, error
+
+        assert summary is not None
+
+        writer.write(
+            f"\n{I}rdfs:comment {rdf_shacl_common.string_literal(summary)}@en ;"
+        )
+
+    writer.write("\n.")
+    return Stripped(writer.getvalue()), None
+
+
+# fmt: off
+@require(
+    lambda cls:
+    not isinstance(cls, intermediate.Class)
+    or not cls.is_implementation_specific
+)
+# fmt: on
+def _define_for_class(
+    cls: intermediate.ClassUnion,
+    our_type_to_rdfs_range: rdf_shacl_common.OurTypeToRdfsRange,
+    xml_namespace: Stripped,
+) -> Tuple[Optional[Stripped], Optional[Error]]:
+    """Generate the definition for the intermediate ``cls``."""
+    blocks = []  # type: List[Stripped]
+    errors = []  # type: List[Error]
+
+    owl_class, error = _define_owl_class_for_class(cls=cls, xml_namespace=xml_namespace)
+    if error is not None:
+        errors.append(error)
+    else:
+        assert owl_class is not None
+        blocks.append(owl_class)
+
+    # NOTE (mristin, 2022-04-20):
+    # We sort by the property names so that the URLs appear sorted in the resulting
+    # schema.
+    for _, prop in sorted(
+        (rdf_shacl_naming.property_name(prop.name), prop) for prop in cls.properties
+    ):
+        if prop.specified_for is not cls:
+            continue
+
+        prop_def, error = _define_property(
+            prop=prop,
+            cls=cls,
+            xml_namespace=xml_namespace,
+            our_type_to_rdfs_range=our_type_to_rdfs_range,
+        )
+        if error is not None:
+            errors.append(error)
+        else:
+            assert prop_def is not None
+            blocks.append(prop_def)
+
+    if len(errors) > 0:
+        return None, Error(
+            None, f"Failed to generate the definition for {cls.name}", errors
+        )
+
+    return Stripped("\n\n".join(blocks)), None
+
+
+@ensure(lambda result: (result[0] is not None) ^ (result[1] is not None))
+def generate(
+    symbol_table: intermediate.SymbolTable,
+    our_type_to_rdfs_range: rdf_shacl_common.OurTypeToRdfsRange,
+    spec_impls: specific_implementations.SpecificImplementations,
+) -> Tuple[Optional[Stripped], Optional[List[Error]]]:
+    """Generate the RDF ontology based on the ``symbol_table."""
+    errors = []  # type: List[Error]
+
+    xml_namespace = symbol_table.meta_model.xml_namespace
+
+    version_literal = rdf_shacl_common.string_literal(symbol_table.meta_model.version)
+
+    ontology_comment_literal = rdf_shacl_common.string_literal(
+        f"This ontology represents the data model for the Asset Administration Shell "
+        f"according to the specification "
+        f"version {symbol_table.meta_model.version}."
+    )
+
+    preamble = Stripped(
+        f"""\
+@prefix aas: <{xml_namespace}/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xs: <http://www.w3.org/2001/XMLSchema#> .
+@base <{xml_namespace}/> .
+
+<{xml_namespace}/> rdf:type owl:Ontology ;
+    owl:versionInfo {version_literal} ;
+    rdfs:comment {ontology_comment_literal}@en ;
+    rdfs:isDefinedBy <{xml_namespace}/> ;
+."""
+    )
+
+    blocks = [preamble]  # type: List[Stripped]
+
+    lang_string_cls, lang_string_error = rdf_shacl_common.get_lang_string_as_expected(
+        symbol_table=symbol_table
+    )
+    if lang_string_error is not None:
+        errors.append(lang_string_error)
+
+    if len(errors) > 0:
+        return None, errors
+
+    for our_type in sorted(
+        symbol_table.our_types,
+        key=lambda another_our_type: rdf_shacl_naming.class_name(another_our_type.name),
+    ):
+        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.
+            continue
+
+        if isinstance(our_type, intermediate.Enumeration):
+            block, error = _define_for_enumeration(
+                enumeration=our_type, xml_namespace=xml_namespace
+            )
+
+            if error is not None:
+                errors.append(error)
+            else:
+                assert block is not None
+                blocks.append(block)
+
+        elif isinstance(our_type, intermediate.ConstrainedPrimitive):
+            # NOTE (mristin, 2022-02-11):
+            # We have to in-line the constraints of the constrained primitives directly
+            # in SHACL as we do not want to introduce new entities into the ontology.
+            pass
+
+        elif isinstance(
+            our_type, (intermediate.AbstractClass, intermediate.ConcreteClass)
+        ):
+            if our_type.is_implementation_specific:
+                implementation_key = specific_implementations.ImplementationKey(
+                    f"rdf/{our_type.name}/owl_class.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"the class {our_type.parsed.name} "
+                            f"is missing: {implementation_key}",
+                        )
+                    )
+                else:
+                    blocks.append(implementation)
+
+            else:
+                block, error = _define_for_class(
+                    cls=our_type,
+                    our_type_to_rdfs_range=our_type_to_rdfs_range,
+                    xml_namespace=xml_namespace,
+                )
+
+                if error is not None:
+                    errors.append(error)
+                else:
+                    assert block is not None
+                    blocks.append(block)
+        else:
+            assert_never(our_type)
+
+    if len(errors) > 0:
+        return None, errors
+
+    return Stripped("\n\n".join(blocks)), None