Merge pull request #43 from casework/release-0.4.0

Release 0.4.0

Author: ajnelson-nist

.gitignore

@@ -1,6 +1,7 @@
 *.done.log
 *.swp
 .DS_Store
+.idea/
 __pycache__
 build/
 case_utils.egg-info/

.gitmodules

@@ -1,6 +1,3 @@
 [submodule "dependencies/CASE"]
 	path = dependencies/CASE
 	url = https://github.com/casework/CASE.git
-[submodule "dependencies/CASE-Examples-QC"]
-	path = dependencies/CASE-Examples-QC
-	url = https://github.com/ajnelson-nist/CASE-Examples-QC.git

CONTRIBUTE.md

@@ -6,9 +6,10 @@
 1. After cloning this repository, ensure the CASE submodule is checked out.  This can be done with either `git submodule init && git submodule update`, `make .git_submodule_init.done.log`, or `make check`.
 2. Update the CASE submodule pointer to the new tagged release.
 3. The version of CASE is also hard-coded in [`case_utils/ontology/version_info.py`](case_utils/ontology/version_info.py).  Edit the variable `CURRENT_CASE_VERSION`.
-4. From the top source directory, run `make clean`.  This guarantees a clean state of this repository as well as the ontology submodules.
-5. Still from the top source directory, run `make`.
-6. Any new `.ttl` files will be created under [`case_utils/ontology/`](case_utils/ontology/).  Use `git add` to add each of them.  (The patch-weight of these files could overshadow manual revisions, so it is fine to commit the built files after the manual changes are committed.)
+4. A list of built versions of CASE is also hard-coded in [`case_utils/ontology/version_info.py`](case_utils/ontology/version_info.py).  Edit the variable `built_version_choices_list`.
+5. From the top source directory, run `make clean`.  This guarantees a clean state of this repository as well as the ontology submodules.
+6. Still from the top source directory, run `make`.
+7. Any new `.ttl` files will be created under [`case_utils/ontology/`](case_utils/ontology/).  Use `git add` to add each of them.  (The patch-weight of these files could overshadow manual revisions, so it is fine to commit the built files separately from the manual changes being committed.  Preferably, commit the built files *before* manual changes - this prevents later issues with a `git bisect` that relies on CI passing.)
 
 Here is a sample sequence of shell commands to run the build:
 
@@ -29,6 +30,6 @@ pushd case_utils/ontology
 popd
 make check
 # Assuming `make check` passes:
+git commit -m "Build CASE 0.6.0 monolithic .ttl files" case_utils/ontology/case-0.6.0-subclasses.ttl case_utils/ontology/case-0.6.0.ttl
 git commit -m "Update CASE ontology pointer to version 0.6.0" dependencies/CASE case_utils/ontology/version_info.py
-git commit -m "Build CASE 0.6.0.ttl" case_utils/ontology/case-0.6.0.ttl
 ```

Makefile

@@ -32,16 +32,6 @@ all: \
 	cd dependencies \
 	  && git diff . \
 	    | cat
-	git submodule init dependencies/CASE-Examples-QC
-	git submodule update dependencies/CASE-Examples-QC
-	# Build an ontology terms list, which has a side effect of initiating further submodules.
-	$(MAKE) \
-	  --directory dependencies/CASE-Examples-QC \
-	  .git_submodule_init.done.log \
-	  .venv.done.log
-	$(MAKE) \
-	  --directory dependencies/CASE-Examples-QC/tests \
-	  ontology_vocabulary.txt
 	test -r dependencies/CASE/ontology/master/case.ttl \
 	  || (git submodule init dependencies/CASE && git submodule update dependencies/CASE)
 	test -r dependencies/CASE/ontology/master/case.ttl
@@ -91,10 +81,6 @@ clean:
 	        tests/examples \
 	        || true \
 	  )
-	@#Remove flag files that are normally set after deeper submodules and rdf-toolkit are downloaded.
-	@rm -f \
-	  dependencies/CASE-Examples-QC/.git_submodule_init.done.log \
-	  dependencies/CASE-Examples-QC/.lib.done.log
 
 # This recipe guarantees timestamp update order, and is otherwise intended to be a no-op.
 dependencies/CASE/ontology/master/case.ttl: \

README.md

@@ -12,9 +12,10 @@ Participation by NIST in the creation of the documentation of mentioned software
 
 1. Clone this repository.
 2. (Optional) Create and activate a virtual environment.
-3. Run `python setup.py`.
+3. (Optional) Upgrade `pip` with `pip install --upgrade pip`.  (This can speed installation of some dependent packages.)
+4. Run `pip install .`.
 
-Installation is demonstrated in the `.venv.done.log` target of the [`tests/`](tests/) directory.
+Installation is demonstrated in the `.venv.done.log` target of the `tests/` directory's [`Makefile`](tests/Makefile).
 
 
 ## Usage
@@ -68,6 +69,8 @@ Two commands are provided to generate output from a SPARQL query and one or more
 
 These commands can be used with any RDF files to run arbitrary SPARQL queries.  They have one additional behavior tailored to CASE: If a path query is used for subclasses, the CASE subclass hierarchy will be loaded to supplement the input graph.  An expected use case of this feature is subclasses of `ObservableObject`.  For instance, if a data graph included an object with only the class `uco-observable:File` specified, the query `?x a/rdfs:subClassOf* uco-observable:ObservableObject` would match `?x` against that object.
 
+Note that prefixes used in the SPARQL queries do not need to be defined in the SPARQL query.  Their mapping will be inherited from their first definition in the input graph files.  However, input graphs are not required to agree on prefix mappings, so there is potential for confusion from input argument order mattering if two input graph files disagree on what a prefix maps to.  If there is concern of ambiguity from inputs, a `PREFIX` statement should be included in the query, such as is shown in [this test query](tests/case_utils/case_sparql_select/subclass.sparql).
+
 
 #### `case_sparql_construct`
 

case_utils/__init__.py

@@ -11,19 +11,6 @@
 #
 # We would appreciate acknowledgement if the software is used.
 
-__version__ = "0.3.0"
-
-import typing
-import warnings
-
-import rdflib.util  # type: ignore
+__version__ = "0.4.0"
 
 from . import local_uuid
-
-def guess_format(
-  fpath : str,
-  fmap : typing.Optional[typing.Dict[str, str]] = None
-) -> typing.Optional[str]:
-    warnings.warn("The functionality in case_utils.guess_format is now upstream.  Please revise your code to use rdflib.util.guess_format.  The function arguments remain the same.  case_utils.guess_format will be removed in case_utils 0.4.0.", DeprecationWarning)
-
-    return rdflib.util.guess_format(fpath, fmap)  # type: ignore