Initial release

Author: ajnelson-nist

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to title 17 Section 105 of the
+# United States Code this software is not subject to copyright
+# protection and is in the public domain. NIST assumes no
+# responsibility whatsoever for its use by other parties, and makes
+# no guarantees, expressed or implied, about its quality,
+# reliability, or any other characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Python virtualenv for Github runner
+      run: |
+        python -m pip install --upgrade pip
+        pip install virtualenv
+    - name: Start from clean state
+      run: make clean
+    - name: Run tests
+      run: make check

.gitignore

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

Makefile

@@ -0,0 +1,60 @@
+#!/usr/bin/make -f
+
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to title 17 Section 105 of the
+# United States Code this software is not subject to copyright
+# protection and is in the public domain. NIST assumes no
+# responsibility whatsoever for its use by other parties, and makes
+# no guarantees, expressed or implied, about its quality,
+# reliability, or any other characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+SHELL := /bin/bash
+
+all:
+
+.PHONY: \
+  download
+
+.git_submodule_init.done.log: \
+  .gitmodules
+	# Log current submodule pointers.
+	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 \
+	  download
+	$(MAKE) \
+	  --directory dependencies/CASE-Examples-QC/tests \
+	  ontology_vocabulary.txt
+	touch $@
+
+check: \
+  .git_submodule_init.done.log
+	$(MAKE) \
+	  --directory tests \
+	  check
+
+clean:
+	@$(MAKE) \
+	  --directory tests \
+	  clean
+
+distclean: \
+  clean
+	@rm -rf \
+	  build \
+	  *.egg-info \
+	  dist
+
+download: \
+  .git_submodule_init.done.log
+	$(MAKE) \
+	  --directory tests \
+	  download

README.md

@@ -1,2 +1,79 @@
-# opensource-repo
-This repository is the recommended template repository for NIST opensource contributions.
+# CASE Python Utilities
+
+This project provides various specialized utilities for producing data in the [CASE](https://caseontology.org/) format.
+
+
+## Disclaimer
+
+Participation by NIST in the creation of the documentation of mentioned software is not intended to imply a recommendation or endorsement by the National Institute of Standards and Technology, nor is it intended to imply that any specific software is necessarily the best available for the purpose.
+
+
+## Installation
+
+1. Clone this repository.
+2. (Optional) Create and activate a virtual environment.
+3. Run `python setup.py`.
+
+Installation is demonstrated in the `.venv.done.log` target of the [`tests/`](tests/) directory.
+
+
+## Usage
+
+
+### `case_file`
+
+To characterize a file, including hashes:
+
+```bash
+case_file sample.txt.json sample.txt
+```
+
+To characterize a file, but skip hashing it:
+
+```bash
+case_file --disable-hashes sample.txt.json sample.txt
+```
+
+
+### `local_uuid`
+
+This [module](case_utils/local_uuid.py) provides a wrapper UUID generator, `local_uuid()`.  Its main purpose is making example data generate consistent identifiers, and intentionally includes mechanisms to make it difficult to activate this mode without awareness of the caller.
+
+
+## Development status
+
+This repository follows [CASE community guidance on describing development status](https://caseontology.org/resources/software.html#development_status), by adherence to noted support requirements.
+
+The status of this repository is:
+
+4 - Beta
+
+
+## Versioning
+
+This project follows [SEMVER 2.0.0](https://semver.org/) where versions are declared.
+
+
+## Ontology versions supported
+
+This repository supports the ontology versions that are linked as submodules in the [CASE Examples QC](https://github.com/ajnelson-nist/CASE-Examples-QC) repository.  Currently, the ontology versions are:
+
+* CASE - 0.3.0
+* UCO - 0.5.0
+
+
+## Repository locations
+
+This repository is available at the following locations:
+* [https://github.com/casework/CASE-Utilities-Python](https://github.com/casework/CASE-Utilities-Python)
+* [https://github.com/usnistgov/CASE-Utilities-Python](https://github.com/usnistgov/CASE-Utilities-Python) (a mirror)
+
+Releases and issue tracking will be handled at the [casework location](https://github.com/casework/CASE-Utilities-Python).
+
+
+## Make targets
+
+Some `make` targets are defined for this repository:
+* `check` - Run unit tests.
+* `clean` - Remove test build files, but not downloaded files.
+* `download` - Download files sufficiently to run the unit tests offline.  This will *not* include the ontology repositories tracked as submodules.  Note if you do need to work offline, be aware touching the `setup.cfg` file in the project root directory, or `tests/requirements.txt`, will trigger a virtual environment rebuild.

case_utils/__init__.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to title 17 Section 105 of the
+# United States Code this software is not subject to copyright
+# protection and is in the public domain. NIST assumes no
+# responsibility whatsoever for its use by other parties, and makes
+# no guarantees, expressed or implied, about its quality,
+# reliability, or any other characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+__version__ = "0.1.0"
+
+import rdflib.util
+
+from . import local_uuid
+
+def guess_format(fpath, fmap=None):
+    """
+    This function is a wrapper around rdflib.util.guess_format(), adding that the .json extension should be recognized as JSON-LD.
+
+    :param fpath: File path.
+    :type fpath: string
+
+    :param fmap: Mapper dictionary; see rdflib.util.guess_format() for further description.  Note that as in rdflib 5.0.0, supplying this argument overwrites, not augments, the suffix format map used by rdflib.
+    :type fmap: dict
+
+    :returns: RDF file format, fit for rdflib.Graph.parse() or .serialize(); or, None if file extension not mapped.
+    :rtype: string
+    """
+
+    assert fmap is None or isinstance(fmap, dict), "Type check failed"
+
+    if fmap is None:
+        updated_fmap = {key:rdflib.util.SUFFIX_FORMAT_MAP[key] for key in rdflib.util.SUFFIX_FORMAT_MAP}
+        if not "json" in updated_fmap:
+            updated_fmap["json"] = "json-ld"
+    else:
+        updated_fmap = {k:fmap[k] for k in fmap}
+
+    return rdflib.util.guess_format(fpath, updated_fmap)