Add and confirm prefix customization; start doctests

This patch is an isolated and expanded change drawn from PR 38.

This patch was written to integrate into the current class hierarchy
without disruption to existing code.  This patch does not necessarily
indicate agreement with the current class hierarchy.

A follow-on patch will regenerate Make-managed files.

References:
* #38

Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>

Author: ajnelson-nist

.gitignore

@@ -19,3 +19,4 @@ __pycache__/
 # Build Artifacts
 build/
 dist/
+case.ttl

Makefile

@@ -81,7 +81,26 @@ case.jsonld: \
 	    _$@
 	mv _$@ $@
 
+case.ttl: \
+  case.jsonld
+	source venv/bin/activate \
+	  && rdfpipe \
+	    --output-format turtle \
+	    $< \
+	    > _$@
+	source venv/bin/activate \
+	  && case_validate \
+	    _$@
+	@# In instances where graph nodes omit use of a prefix, a 'default' prefix-base is used that incorporates the local directory as a file URL.  This is likely to be an undesired behavior, so for the generated example JSON-LD in the top source directory, check that "file:///" doesn't start any of the graph individuals' IRIs.
+	test \
+	  0 \
+	  -eq \
+	  $$(grep 'file:' _$@ | wc -l) \
+	  || ( echo "ERROR:Some graph IRIs do not supply a resolving prefix.  Look for the string 'file:///' in the file _$@ to see these instances." ; exit 1)
+	mv _$@ $@
+
 check: \
-  all
+  all \
+  case.ttl
 	source venv/bin/activate \
-	  && poetry run pytest
+	  && poetry run pytest --doctest-modules

case_mapping/base.py

@@ -1,5 +1,6 @@
 import json
 from datetime import datetime
+from typing import Any
 
 from cdo_local_uuid import local_uuid
 
@@ -20,8 +21,35 @@ def wrapper(self, *args, **kwargs):
 
 
 class FacetEntity(dict):
-    def __init__(self):
-        self["@id"] = str(local_uuid())
+    def __init__(
+        self,
+        *args: Any,
+        prefix_iri: str = "http://example.org/kb/",
+        prefix_label: str = "kb",
+        **kwargs: Any,
+    ) -> None:
+        """
+        :param prefix_iri: The IRI to be concatenated with the prefixed name's local part in order to form the node's absolute IRI.
+        :param prefix_label: The prefix separated from the compact IRI's local name by a colon.
+
+        References
+        ==========
+
+        .. [#turtle_prefixed_name] https://www.w3.org/TR/turtle/#prefixed-name
+
+        Examples
+        ========
+
+        When instantiating a ``FacetEntity``, the JSON dictionary's ``@id`` key will start with the object's ``prefix_label``.
+
+        >>> x = FacetEntity()
+        >>> assert x["@id"][0:3] == "kb:"
+        >>> y = FacetEntity(prefix_label="ex")
+        >>> assert y["@id"][0:3] == "ex:"
+        """
+        self.prefix_iri = prefix_iri
+        self.prefix_label = prefix_label
+        self["@id"] = prefix_label + ":" + str(local_uuid())
 
     def __str__(self):
         return json.dumps(self, indent=4)
@@ -159,6 +187,9 @@ def __handle_var_type_errors(var_name, var_val, expected_type):
 
 
 class ObjectEntity(FacetEntity):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
     @unpack_args_array
     def append_facets(self, *args):
         """

case_mapping/uco/core.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from ..base import ObjectEntity, unpack_args_array
 
 
@@ -8,11 +10,13 @@ def __init__(
         uco_core_name=None,
         spec_version=None,
         description=None,
-    ):
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
         """
         The main CASE Object for representing a case and its activities and objects.
         """
-        super().__init__()
+        super().__init__(*args, **kwargs)
         self.build = []
         self["@context"] = {
             "@vocab": "http://caseontology.org/core#",
@@ -31,6 +35,17 @@ def __init__(
             "uco-vocabulary": "https://ontology.unifiedcyberontology.org/uco/vocabulary/",
             "xsd": "http://www.w3.org/2001/XMLSchema#",
         }
+
+        # Assign caller-selectible prefix label and IRI, after checking
+        # for conflicts with hard-coded prefixes.
+        # https://www.w3.org/TR/turtle/#prefixed-name
+        if self.prefix_label in self["@context"]:
+            raise ValueError(
+                "Requested prefix label already in use in hard-coded dictionary: '%s'.  Please revise caller to use another label."
+                % self.prefix_label
+            )
+        self["@context"][self.prefix_label] = self.prefix_iri
+
         self["@type"] = "uco-core:Bundle"
         self._str_vars(
             **{

case_mapping/uco/observable.py

@@ -269,7 +269,10 @@ def __init__(
             }
 
         if hash_method is not None or hash_value is not None or hash_value != "-":
-            data = {"@id": str(local_uuid()), "@type": "uco-types:Hash"}
+            data = {
+                "@id": self.prefix_label + ":" + str(local_uuid()),
+                "@type": "uco-types:Hash",
+            }
             if hash_method is not None:
                 data["uco-types:hashMethod"] = {
                     "@type": "uco-vocabulary:HashNameVocab",
@@ -416,7 +419,7 @@ def __init__(self, browser=None, history_entries=None):
         self["uco-observable:urlHistoryEntry"] = []
         for entry in history_entries:
             history_entry = {}
-            history_entry["@id"] = local_uuid()
+            history_entry["@id"] = self.prefix_label + ":" + local_uuid()
             history_entry["@type"] = "uco-observable:URLHistoryEntry"
             for key, var in entry.items():
                 if key in keys_str:
@@ -858,14 +861,14 @@ def __init__(self, **kwargs):
         self["@type"] = "uco-observable:EXIFFacet"
 
         self["uco-observable:exifData"] = {
-            "@id": str(local_uuid()),
+            "@id": self.prefix_label + ":" + str(local_uuid()),
             "@type": "uco-types:ControlledDictionary",
             "uco-types:entry": [],
         }
         for k, v in kwargs.items():
             if v not in ["", " "]:
                 item = {
-                    "@id": str(local_uuid()),
+                    "@id": self.prefix_label + ":" + str(local_uuid()),
                     "@type": "uco-types:ControlledDictionaryEntry",
                     "uco-types:key": k,
                     "uco-types:value": v,
@@ -1356,7 +1359,7 @@ def __init__(
         self._node_reference_vars(**{"uco-observable:participant": participants})
 
         self["uco-observable:messageThread"] = {
-            "@id": str(local_uuid()),
+            "@id": self.prefix_label + ":" + local_uuid(),
             "@type": "uco-types:Thread",
         }