shacl2code 0.0.11__py3-none-any.whl

shacl2code/main.py

@@ -0,0 +1,139 @@
+#! /usr/bin/env python3
+#
+# Copyright (c) 2024 Joshua Watt
+#
+# SPDX-License-Identifier: MIT
+
+import argparse
+import json
+import sys
+import urllib.request
+import rdflib
+from pathlib import Path
+
+from . import Model, UrlContext, ContextData
+from .version import VERSION
+from .lang import LANGUAGES
+
+
+def main(args=None):
+    def handle_generate(parser, args):
+        graph = rdflib.Graph()
+        for inmodel in args.input:
+            if inmodel == "-":
+                if args.input_format == "auto":
+                    print("ERROR: Input format must be specified with stdin")
+                    parser.print_help()
+                    return 1
+
+                graph.parse(sys.stdin, format=args.input_format)
+            else:
+                if args.input_format == "auto":
+                    graph.parse(inmodel)
+                else:
+                    graph.parse(inmodel, format=args.input_format)
+
+        contexts = []
+        for c in args.context:
+            with urllib.request.urlopen(c) as f:
+                data = json.load(f)
+            contexts.append(ContextData(data, c))
+
+        for location, url in args.context_url:
+            if "://" in location:
+                with urllib.request.urlopen(location) as f:
+                    data = json.load(f)
+            else:
+                with Path(location).open("r") as f:
+                    data = json.load(f)
+            contexts.append(ContextData(data, url))
+
+        m = Model(graph, UrlContext(contexts))
+
+        render = args.lang(args)
+        render.output(m)
+        return 0
+
+    def handle_list(parser, args):
+        width = max(len(lang) for lang in LANGUAGES)
+        for k, v in LANGUAGES.items():
+            if args.short:
+                print(k)
+            else:
+                print(f"{k:{width}} - {v.HELP}")
+
+        return 0
+
+    def handle_version(parser, args):
+        print(VERSION)
+        return 0
+
+    parser = argparse.ArgumentParser(
+        description=f"Convert JSON-LD model to python. Version {VERSION}"
+    )
+    command_subparser = parser.add_subparsers(
+        title="command",
+        description="Command to execute",
+        required=True,
+    )
+    generate_parser = command_subparser.add_parser(
+        "generate",
+        help="Generate language bindings",
+    )
+    generate_parser.add_argument(
+        "--input",
+        "-i",
+        help="Input model (path, URL, or '-')",
+        action="append",
+        default=[],
+        required=True,
+    )
+    generate_parser.add_argument(
+        "--input-format",
+        "-t",
+        help="Input file format, or 'auto' to attempt to determine automatically. Default is %(default)s",
+        default="auto",
+    )
+    generate_parser.add_argument(
+        "--context",
+        "-x",
+        help="Require context for output (URL)",
+        action="append",
+        default=[],
+    )
+    generate_parser.add_argument(
+        "--context-url",
+        "-u",
+        help="Require context from LOCATION (path or URL), but report as URL in generated code",
+        nargs=2,
+        metavar=("LOCATION", "URL"),
+        action="append",
+        default=[],
+    )
+    generate_parser.set_defaults(func=handle_generate)
+
+    lang_subparser = generate_parser.add_subparsers(
+        title="language",
+        description="Language to generate",
+        required=True,
+    )
+    for k, v in LANGUAGES.items():
+        p = lang_subparser.add_parser(k, help=v.HELP)
+        v.get_arguments(p)
+        p.set_defaults(lang=v)
+
+    list_parser = command_subparser.add_parser("list", help="List languages")
+    list_parser.add_argument(
+        "--short",
+        "-s",
+        action="store_true",
+        help="Only list languages without descriptions",
+    )
+    list_parser.set_defaults(func=handle_list)
+
+    version_parser = command_subparser.add_parser("version", help="Show version")
+    version_parser.set_defaults(func=handle_version)
+
+    parsed_args = parser.parse_args(args)
+
+    return parsed_args.func(parser, parsed_args)

shacl2code/model.py

@@ -0,0 +1,293 @@
+#! /usr/bin/env python3
+#
+# Copyright (c) 2024 Joshua Watt
+#
+# SPDX-License-Identifier: MIT
+
+import typing
+from dataclasses import dataclass
+
+from rdflib import URIRef
+from rdflib.namespace import RDF, RDFS, OWL, SH, XSD, DefinedNamespace, Namespace
+
+PATTERN_DATATYPES = [
+    str(XSD.string),
+    str(XSD.dateTime),
+    str(XSD.dateTimeStamp),
+    str(XSD.anyURI),
+]
+
+
+class SHACL2CODE(DefinedNamespace):
+    idPropertyName: URIRef
+    isExtensible: URIRef
+    isAbstract: URIRef
+
+    _NS = Namespace("https://jpewdev.github.io/shacl2code/schema#")
+
+
+class ModelException(Exception):
+    pass
+
+
+def common_prefix(*s):
+    if not s:
+        return ""
+
+    if len(s) == 1:
+        return s[0]
+
+    p1 = common_prefix(*s[: len(s) // 2])
+    p2 = common_prefix(*s[len(s) // 2 :])
+    for idx in range(len(p1)):
+        if idx >= len(p2):
+            return p2
+
+        if p1[idx] != p2[idx]:
+            return p2[:idx]
+
+    return p1
+
+
+def remove_common_prefix(val, *cmp):
+    prefix = common_prefix(val, *cmp)
+    return val[len(prefix) :]
+
+
+@dataclass
+class Individual:
+    _id: str
+    varname: str
+    comment: str = ""
+
+
+@dataclass
+class Property:
+    path: str
+    varname: str
+    comment: str = ""
+    max_count: int = None
+    min_count: int = None
+    enum_values: list = None
+    class_id: str = ""
+    datatype: str = ""
+    pattern: str = ""
+
+
+@dataclass
+class Class:
+    _id: str
+    clsname: str
+    parent_ids: typing.List[str]
+    derived_ids: list
+    properties: typing.List[Property]
+    comment: str = ""
+    id_property: str = ""
+    node_kind: str = None
+    is_extensible: bool = False
+    is_abstract: bool = False
+    named_individuals: list = None
+
+
+class Model(object):
+    def __init__(self, graph, context=None):
+        self.model = graph
+        self.context = context
+        self.compact_ids = {}
+        self.objects = {}
+        self.enums = []
+        self.classes = []
+        class_iris = set()
+        classes_by_iri = {}
+
+        def int_val(v):
+            if not v:
+                return None
+            return int(v)
+
+        def str_val(v):
+            if v is None:
+                return v
+            return str(v)
+
+        def get_inherited_value(subject, predicate, default=None):
+            def get_value(subject, predicate):
+                value = self.model.value(subject, predicate)
+                if value is not None:
+                    return value
+
+                for parent in self.model.objects(subject, RDFS.subClassOf):
+                    value = get_value(parent, predicate)
+                    if value is not None:
+                        return value
+
+                return None
+
+            value = get_value(subject, predicate)
+            if value is not None:
+                return value
+            return default
+
+        def set_prop_range(p, range_id):
+            nonlocal class_iris
+
+            if range_id in class_iris:
+                p.class_id = str(range_id)
+                return True
+
+            return False
+
+        def get_named_individuals(cls_iri):
+            members = []
+            for member_iri in self.model.subjects(RDF.type, cls_iri):
+                if (member_iri, RDF.type, OWL.NamedIndividual) not in self.model:
+                    continue
+
+                members.append(
+                    Individual(
+                        _id=str(member_iri),
+                        varname=remove_common_prefix(member_iri, cls_iri).lstrip("/"),
+                        comment=str(
+                            self.model.value(member_iri, RDFS.comment, default="")
+                        ),
+                    )
+                )
+            return members
+
+        def is_abstract(s):
+            if (
+                s,
+                RDF.type,
+                URIRef("http://spdx.invalid./AbstractClass"),
+            ) in self.model:
+                return True
+
+            return bool(self.model.value(s, SHACL2CODE.isAbstract, default=False))
+
+        class_iris = set(self.model.subjects(RDF.type, OWL.Class))
+        for cls_iri in class_iris:
+            c = Class(
+                _id=str(cls_iri),
+                parent_ids=[
+                    str(parent_iri)
+                    for parent_iri in self.model.objects(cls_iri, RDFS.subClassOf)
+                    if parent_iri in class_iris
+                ],
+                derived_ids=[],
+                clsname=self.get_class_name(cls_iri),
+                comment=str(self.model.value(cls_iri, RDFS.comment, default="")),
+                properties=[],
+                id_property=str_val(
+                    get_inherited_value(cls_iri, SHACL2CODE.idPropertyName)
+                ),
+                node_kind=get_inherited_value(cls_iri, SH.nodeKind, SH.BlankNodeOrIRI),
+                is_extensible=bool(self.model.value(cls_iri, SHACL2CODE.isExtensible)),
+                is_abstract=is_abstract(cls_iri),
+                named_individuals=get_named_individuals(cls_iri),
+            )
+
+            if c.node_kind not in (SH.IRI, SH.BlankNode, SH.BlankNodeOrIRI):
+                raise ModelException(
+                    f"Class {c._id} has unsupported '{SH.nodeKind}' value '{c.node_kind}'"
+                )
+
+            for obj_prop in self.model.objects(cls_iri, SH.property):
+                prop = self.model.value(obj_prop, SH.path)
+
+                p = Property(
+                    varname=self.model.value(
+                        obj_prop,
+                        SH.name,
+                        default=self.get_compact_id(
+                            prop,
+                            fallback=remove_common_prefix(prop, cls_iri).lstrip("/"),
+                        ),
+                    ),
+                    path=str(prop),
+                    comment=str(self.model.value(prop, RDFS.comment, default="")),
+                    max_count=int_val(self.model.value(obj_prop, SH.maxCount)),
+                    min_count=int_val(self.model.value(obj_prop, SH.minCount)),
+                )
+
+                if in_list := self.model.value(obj_prop, SH["in"]):
+                    p.enum_values = sorted(tuple(self.model.items(in_list)))
+
+                if range_id := self.model.value(obj_prop, SH["class"]):
+                    if not set_prop_range(p, range_id):
+                        raise ModelException(
+                            f"Prop {prop} has unknown class restriction {range_id}"
+                        )
+
+                elif range_id := self.model.value(obj_prop, SH.datatype):
+                    p.datatype = str(range_id)
+
+                elif range_id := self.model.value(prop, RDFS.range):
+                    if not set_prop_range(p, range_id):
+                        p.datatype = str(range_id)
+
+                else:
+                    raise ModelException(f"Prop '{prop}' is missing range")
+
+                if pattern := self.model.value(obj_prop, SH.pattern):
+                    if not p.datatype:
+                        raise ModelException(
+                            f"Property '{prop}' is not a datatype and may not have a pattern"
+                        )
+                    if p.datatype not in PATTERN_DATATYPES:
+                        raise ModelException(
+                            f"Property '{prop}' of type '{p.datatype}' cannot have a pattern. Must be one of type {' '.join(PATTERN_DATATYPES)}"
+                        )
+                    p.pattern = str(pattern)
+
+                c.properties.append(p)
+
+            c.properties.sort(key=lambda p: p.path)
+
+            self.classes.append(c)
+            classes_by_iri[str(cls_iri)] = c
+
+        for c in self.classes:
+            for p in c.parent_ids:
+                classes_by_iri[p].derived_ids.append(c._id)
+
+        for c in self.classes:
+            c.derived_ids.sort()
+
+        self.enums.sort(key=lambda e: e._id)
+        self.classes.sort(key=lambda c: c._id)
+
+        tmp_classes = self.classes
+        done_ids = set()
+        self.classes = []
+
+        while tmp_classes:
+            c = tmp_classes.pop(0)
+
+            # If any parent classes of this class are outstanding, then push it
+            # back on the end of the class list and try again. This ensures that
+            # derived classes are always written after any parent classes
+            if not all(p in done_ids for p in c.parent_ids):
+                tmp_classes.append(c)
+                continue
+
+            self.classes.append(c)
+            done_ids.add(c._id)
+
+    def get_compact_id(self, _id, *, fallback=None):
+        """
+        Returns the "compacted" name of an object, that is the name of the
+        object with the context applied
+        """
+        _id = str(_id)
+        if _id not in self.compact_ids:
+            self.compact_ids[_id] = self.context.compact(_id)
+
+        if self.compact_ids[_id] == _id and fallback is not None:
+            return fallback
+        return self.compact_ids[_id]
+
+    def get_class_name(self, c):
+        """
+        Returns the name for a class that should be used in Code
+        """
+        return self.get_compact_id(c).split(":")

shacl2code/urlcontext.py

@@ -0,0 +1,23 @@
+#! /usr/bin/env python3
+#
+# Copyright (c) 2024 Joshua Watt
+#
+# SPDX-License-Identifier: MIT
+
+import typing
+from dataclasses import dataclass
+from .context import Context
+
+
+@dataclass
+class ContextData:
+    context: typing.Dict
+    url: str
+
+
+class UrlContext(Context):
+    def __init__(self, contexts=[]):
+        super().__init__([c.context.get("@context", {}) for c in contexts])
+        self.urls = []
+        for ctx in contexts:
+            self.urls.append(ctx.url)

shacl2code/version.py

@@ -0,0 +1 @@
+VERSION = "0.0.11"

shacl2code-0.0.11.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.3
+Name: shacl2code
+Version: 0.0.11
+Summary: Convert SHACL model file to code bindings
+Project-URL: Homepage, https://github.com/JPEWdev/shacl2code
+Project-URL: Repository, https://github.com/JPEWdev/shacl2code.git
+Project-URL: Issues, https://github.com/JPEWdev/shacl2code/issues
+Author-email: Joshua Watt <JPEWhacker@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: rdflib>=7.0.0
+Provides-Extra: dev
+Requires-Dist: flake8>=7.0.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.21.1; extra == 'dev'
+Requires-Dist: pyshacl>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-server-fixtures>=1.7; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Convert SHACL Model to code bindings
+[![Coverage Report](https://raw.githubusercontent.com/JPEWdev/shacl2code/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/JPEWdev/shacl2code/blob/python-coverage-comment-action-data/htmlcov/index.html)
+
+This tool can be used to convert a SHACL model into various code bindings
+
+## Installation
+
+`shacl2code` can be installed using pip:
+
+```shell
+python3 -m pip install shacl2code
+```
+
+## Usage
+
+`shacl2code` can generate bindings from either a local file:
+```shell
+shacl2code generate -i model.jsonld python -o out.py
+```
+Or from a URL:
+```shell
+shacl2code generate -i https://example.com/rdf/model.jsonld python -o out.py
+```
+Or from stdin:
+```shell
+cat model.jsonld | shacl2code generate -i - python -o - > out.py
+```
+
+For more information, run:
+```shell
+shacl2code --help
+```
+
+The available language bindings can be viewed by running:
+```shell
+shacl2code list
+```
+
+## Developing
+
+Developing on `shacl2code` is best done using a virtual environment. You can
+configure one and install shacl2code in editable mode with all necessary
+development dependencies by running:
+
+```shell
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Testing
+
+`shacl2code` has a test suite written in [pytest][pytest]. To run it, setup a
+virtual environment as shown above, then run:
+```shell
+pytest
+```
+
+In addition to the test results, a test coverage report will also be generated
+using [pytest-cov][pytest-cov]
+
+
+## Custom Annotations
+
+`shacl2code` supports a number of custom annotations that can be specified in a
+SHACL model to give hints about the generated code. All of these annotations
+live in the `https://jpewdev.github.io/shacl2code/schema#` namespace, and
+commonly are given the `sh-to-code` prefix to make it easier to reference them.
+For example, in Turtle one would add the prefix mapping:
+
+```ttl
+@prefix sh-to-code: <https://jpewdev.github.io/shacl2code/schema#> .
+```
+
+### ID Property Name
+
+The `idPropertyName` annotation allows a class to specify what the name of the
+"property" that specifies the RDF subject of an object is for serializations
+that support it. For example, in JSON-LD, the `@id` property indicates the
+subject in RDF. If you wanted to alias the `@id` property to another name, the
+`idPropertyName` annotation will let you do this. For example, the following
+turtle will use `MyId` instead of `@id` when writing JSON-LD bindings:
+
+```ttl
+<MyClass> a owl:Class, sh:NodeShape ;
+    sh-to-code:idPropertyName "MyId"
+    .
+```
+
+When doing this, the class would then look like this in JSON-LD:
+```json
+{
+    "@type": "MyClass",
+    "MyId": "http://example.com/id"
+}
+```
+
+The `idProperyName` annotation is inherited by derived classes, so for example
+any class that derived from `MyClass` would also use `MyId` as the subject
+property.
+
+**Note:** This only specifies what the name of the field should be in generated
+bindings and has no bearing on how an RDF parser would interpret the property.
+In order to still be parsed by RDF, you would also need context file that maps
+`MyId` to `@id`, for example:
+
+```json
+{
+    "@context": {
+        "MyId": "@id"
+    }
+}
+```
+
+`shacl2code` doesn't do this for you, nor does it validate that you have done
+it.
+
+### Extensible Classes
+
+Most bindings generated from `shacl2code` are "closed" in that they do not
+allow extra properties to be added to object outside of what is specified in
+model. This ensures that field name typos and other unintended properties are
+not added to an object. However, in some cases a class may be specifically
+intended to be extended such that arbitrary fields can be added to it, which
+can be done using the `isExtensible` property. This is a boolean property that
+indicates if a class can be extended, and defaults to `false`. For example, the
+following turtle will declare a class as extensible:
+
+```ttl
+
+<MyClass> a owl:Class, sh:NodeShape ;
+    sh-to-code:isExtensible true
+    .
+```
+
+The `isExtensible` property is _not_ inherited by derived classes, meaning it
+is possible to have a class derived from `MyClass` which is itself not
+extensible.
+
+The mechanism for dealing with extensible classes will vary between the
+different bindings, but in general it means that they will not be very picky
+about object types and properties in any location where an extensible class is
+allowed.
+
+**Note**: You may want to be careful about where and how many extensible
+classes are allowed in your model. If there are too many and they are allowed
+anywhere, it may mean that typos in object types (e.g. `@type` in JSON-LD) are
+not caught by validation as they will have to be assumed to be a derived class
+from an extensible type.
+
+### Abstract Classes
+
+By default, classes generated by `shacl2code` are all instantiable (i.e. they
+can be created). In some instances, it may be desirable to declare a class as
+abstract (meaning that it cannot be instantiated, but non-abstract derived
+classes can). This can be done with the boolean `isAbstract` property. For
+example, the following turtle will declare a class as abstract:
+
+```ttl
+
+<MyClass> a owl:Class, sh:NodeShape ;
+    sh-to-code:isAbstract true
+    .
+```
+
+The `isAbstract` property is _not_ inherited by derived classes, so any derived
+classes are automatically concrete unless they indicate otherwise.
+
+Note that for compatibility reasons, it is also possible to define a class as
+abstract by declaring it to be of type: `http://spdx.invalid./AbstractClass`,
+but this is not preferred.
+
+[pytest]: https://www.pytest.org
+[pytest-cov]: https://pytest-cov.readthedocs.io/en/latest/

shacl2code-0.0.11.dist-info/RECORD

@@ -0,0 +1,20 @@
+shacl2code/__init__.py,sha256=aq5je2i1vkTFCIhUEEt1RsbJlsXpg2rzPLEK_PJh3ac,197
+shacl2code/__main__.py,sha256=xWmYOo4S8cDiXgIQFhBg1fdHi1ANIbviMSrbx4LXOAw,173
+shacl2code/context.py,sha256=pzu_GseOZVz4gR0JC5LjuKigOn5LrlS9rlwyu9wfgDA,5368
+shacl2code/main.py,sha256=eQ5bWu7pGKWb2DAEOc4brMapzPlghtuW6hOZ9M85lMo,4005
+shacl2code/model.py,sha256=ESABSh4xHh5e5qfmeqQqLqdI1G1EWVsoLQMJ-sTBqgY,9077
+shacl2code/urlcontext.py,sha256=cOlNXX1gdbhtmV4hnPTwEdMOPNn8iP0l3sH6pEr3pwQ,472
+shacl2code/version.py,sha256=wvhEP9_tqxjTVjTcNW0lZOeHOeP3yZH_m-zQShg9NXI,19
+shacl2code/lang/__init__.py,sha256=yy-nNrvlRM_O--MpBZ55OO2HoU6W9ICN6H_CE75JJnA,314
+shacl2code/lang/common.py,sha256=pGftHigCCq_MEYny6EqtBnvLxnDEOfrljT0sIKw2YNs,3932
+shacl2code/lang/jinja.py,sha256=MlxZUMoBSaD76ahwBSmGTBJilGiecdvA__WxUqfRZUI,607
+shacl2code/lang/jsonschema.py,sha256=PfffswQ-QY0rV0aGR9qzVzJ-P78UKFvMh8yiuCA2RDo,1292
+shacl2code/lang/lang.py,sha256=4TbEsktsHCrMwLlT4bkhh2fhMWkIxFdwhT1vwML8Rx8,296
+shacl2code/lang/python.py,sha256=umiZx0p2J_vBaoTnPx3ldx4e5yKmQ0hGd7qN6lTVsy8,1414
+shacl2code/lang/templates/jsonschema.j2,sha256=cuTGYvQ1pLj6aMnMwtwTVRxyQMRWdY7YOt-6kzJqCaw,11340
+shacl2code/lang/templates/python.j2,sha256=oXQqL2KoRsf974l-jk4ImOCXYn49iyy5h1Svevkbalg,57340
+shacl2code-0.0.11.dist-info/METADATA,sha256=XjDPB8Wn1q928vJardZ4P0JTRD-ACuRIdvrdP339eYA,6927
+shacl2code-0.0.11.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+shacl2code-0.0.11.dist-info/entry_points.txt,sha256=xMo3DqLqOpZfEwDXLL3lqQZoXUXKUUhgn-ABzH4nOEg,47
+shacl2code-0.0.11.dist-info/licenses/LICENSE,sha256=npUT32k_O0lU4UHJ8ZZ2_Ti0GR1oSbNGRzID9lSWkxs,1068
+shacl2code-0.0.11.dist-info/RECORD,,

shacl2code-0.0.11.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.24.2
+Root-Is-Purelib: true
+Tag: py3-none-any

shacl2code-0.0.11.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shacl2code = shacl2code:main