shacl2code 0.0.9__tar.gz → 0.0.11__tar.gz

shacl2code-0.0.11/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,174 @@
+# 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.9 → shacl2code-0.0.11}/pyproject.toml

@@ -6,7 +6,7 @@ dependencies = [
     "jinja2 >= 3.1.2",
     "rdflib >= 7.0.0",
 ]
-required-python = ">= 3.8"
+requires-python = ">= 3.8"
 authors = [
     {name = "Joshua Watt", email = "JPEWhacker@gmail.com"},
 ]

{shacl2code-0.0.9 → shacl2code-0.0.11}/src/shacl2code/lang/common.py

@@ -31,15 +31,15 @@ class BasicJinjaRender(object):
     """
     Common Jinja Template Renderer
 
-    Renderers that only use a single Jinja file can derive from this class. The
-    class should set the class member variable `TEMPLATE` to indicate which
-    template file to use. For example:
+    Renderers that only use a single Jinja file can derive from this class. For
+    example:
 
         @language("my-lang")
         class MyRendered(BasicJinjaRenderer):
             HELP = "Generates my-lang bindings"
-            TEMPLATE = "my-lang.j2"
 
+            def __init__(self, args):
+                super().__init__(args, PATH / TO / TEMPLATE)
     """
 
     def __init__(self, args, template):
@@ -62,22 +62,31 @@ class BasicJinjaRender(object):
     def get_extra_env(self):
         return {}
 
-    def output(self, model):
+    def render(self, template, output, *, extra_env={}, render_args={}):
         def abort_helper(msg):
             raise TemplateRuntimeError(msg)
 
-        def get_all_derived(cls):
-            nonlocal classes
+        env = Environment(loader=FileSystemLoader([template.parent, THIS_DIR.parent]))
+        for k, v in extra_env.items():
+            env.globals[k] = v
+        env.globals["abort"] = abort_helper
+        env.globals["SHACL2CODE"] = SHACL2CODE
+        env.globals["SH"] = SH
+        template = env.get_template(template.name)
 
-            def _recurse(cls):
-                result = set(cls.derived_ids)
-                for r in cls.derived_ids:
-                    result |= _recurse(classes.get(r))
-                return result
+        render = template.render(
+            disclaimer=f"This file was automatically generated by {os.path.basename(sys.argv[0])}. DO NOT MANUALLY MODIFY IT",
+            **render_args,
+        )
 
-            d = list(_recurse(cls))
-            d.sort()
-            return d
+        output.write(render)
+        if not render[-1] == "\n":
+            output.write("\n")
+
+    def output(self, model):
+        """
+        Render the provided model
+        """
 
         class ObjectList(object):
             def __init__(self, objs):
@@ -92,29 +101,44 @@ class BasicJinjaRender(object):
                         return o
                 raise KeyError(f"Object with ID {_id} not found")
 
-        env = Environment(
-            loader=FileSystemLoader([self.__template.parent, THIS_DIR.parent])
-        )
-        for k, v in self.get_extra_env().items():
-            env.globals[k] = v
-        env.globals["abort"] = abort_helper
-        env.globals["get_all_derived"] = get_all_derived
-        env.globals["SHACL2CODE"] = SHACL2CODE
-        env.globals["SH"] = SH
-        template = env.get_template(self.__template.name)
+        def get_all_derived(cls):
+            nonlocal classes
+
+            def _recurse(cls):
+                result = set(cls.derived_ids)
+                for r in cls.derived_ids:
+                    result |= _recurse(classes.get(r))
+                return result
+
+            d = list(_recurse(cls))
+            d.sort()
+            return d
 
         classes = ObjectList(model.classes)
+        concrete_classes = ObjectList(
+            list(c for c in model.classes if not c.is_abstract)
+        )
+        abstract_classes = ObjectList(list(c for c in model.classes if c.is_abstract))
         enums = ObjectList(model.enums)
 
-        render = template.render(
-            disclaimer=f"This file was automatically generated by {os.path.basename(sys.argv[0])}. DO NOT MANUALLY MODIFY IT",
-            enums=enums,
-            classes=classes,
-            context=model.context,
+        render_args = {
+            "classes": classes,
+            "concrete_classes": concrete_classes,
+            "abstract_classes": abstract_classes,
+            "enums": enums,
+            "context": model.context,
             **self.get_additional_render_args(),
-        )
+        }
+
+        env = {
+            "get_all_derived": get_all_derived,
+            **self.get_extra_env(),
+        }
 
         with self.__output.open() as f:
-            f.write(render)
-            if not render[-1] == "\n":
-                f.write("\n")
+            self.render(
+                self.__template,
+                f,
+                extra_env=env,
+                render_args=render_args,
+            )

{shacl2code-0.0.9 → shacl2code-0.0.11}/src/shacl2code/lang/jsonschema.py

@@ -10,8 +10,8 @@ import re
 import keyword
 
 
-def varname(name):
-    name = str(name).replace("@", "_")
+def varname(*name):
+    name = str("_".join(name)).replace("@", "_")
     name = re.sub(r"[^a-zA-Z0-9_]", "", name)
     while keyword.iskeyword(name):
         name = name + "_"

{shacl2code-0.0.9 → shacl2code-0.0.11}/src/shacl2code/lang/python.py

@@ -10,7 +10,8 @@ import re
 import keyword
 
 
-def varname(name):
+def varname(*name):
+    name = "_".join(name)
     # Any invalid characters at the beginning of the name are removed (except
     # "@")
     name = re.sub(r"^[^a-zA-Z0-9_@]*", "", name)