diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..5a42824 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,9 @@ +# This file lists the contributors responsible for the +# repository content. They will also be automatically +# asked to review any pull request made in this repository. + +# Each line is a file pattern followed by one or more owners. +# The sequence matters: later patterns take precedence. + +# FILES OWNERS +* @Cyber-Domain-Ontology/maintainers-global diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml new file mode 100644 index 0000000..07033d1 --- /dev/null +++ b/.github/workflows/cicd.yml @@ -0,0 +1,79 @@ +# Portions of this file contributed by NIST are governed by the +# following statement: +# +# 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 within the United States. 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 + release: + types: + - published + schedule: + - cron: '15 5 * * TUE' + +jobs: + build: + + runs-on: ubuntu-latest + strategy: + matrix: + python-version: + - '3.8' + - '3.12' + + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Pre-commit Checks + run: | + pip -q install pre-commit + pre-commit run --all-files + - name: Start from clean state + run: make clean + - name: Run tests + run: make PYTHON3=python check + + # Build the binary wheel as well as the source tar + - name: Build Objects + run: | + pip install -q twine wheel + python setup.py sdist bdist_wheel + + # Ensure the objects were packaged correctly and there wasn't an issue with + # the compilation or packaging process. + - name: Check Objects + run: twine check dist/* + + # Upload the packages on all develop and main pipleines for test consumption + - name: Upload HTML Docs + uses: actions/upload-artifact@v3 + with: + name: packages + path: ./dist/ + + # If this commit is the result of a Git tag, push the wheel and tar packages + # to the PyPi registry + - name: Publish to PyPI + if: github.event_name == 'release' && github.event.action == 'published' + run: twine upload --repository-url https://upload.pypi.org/legacy/ -u __token__ -p ${{ secrets.PYPI_API_TOKEN }} --skip-existing --verbose dist/* diff --git a/.github/workflows/ci.yml b/.github/workflows/prerelease.yml similarity index 70% rename from .github/workflows/ci.yml rename to .github/workflows/prerelease.yml index 1153e9c..74580fa 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/prerelease.yml @@ -12,15 +12,15 @@ # # We would appreciate acknowledgement if the software is used. -name: Continuous Integration +# This workflow uses Make to review direct dependencies of this +# repository. + +name: Prerelease on: - push: - branches: [ main, develop ] pull_request: - branches: [ main, develop ] - schedule: - - cron: '15 5 * * TUE' + branches: + - main jobs: build: @@ -29,8 +29,8 @@ jobs: strategy: matrix: python-version: - - '3.9' - - '3.11' + - '3.8' + - '3.12' steps: - uses: actions/checkout@v3 @@ -38,11 +38,5 @@ jobs: uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - - name: Pre-commit Checks - run: | - pip -q install pre-commit - pre-commit run --all-files - - name: Start from clean state - run: make clean - - name: Run tests - run: make PYTHON3=python3 check + - name: Review dependencies + run: make check-supply-chain-pre-commit diff --git a/.github/workflows/supply-chain.yml b/.github/workflows/supply-chain.yml deleted file mode 100644 index 206ff08..0000000 --- a/.github/workflows/supply-chain.yml +++ /dev/null @@ -1,49 +0,0 @@ -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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. - -# This workflow uses Make to review direct dependencies of this -# repository. - -name: Supply Chain - -on: - schedule: - - cron: '15 5 * * 1,2,3,4,5' - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - python-version: - - '3.9' - - '3.11' - - steps: - - uses: actions/checkout@v3 - with: - # This enables supply chain review against only a selected - # branch. For those using the "Git-Flow" style of branching, - # the ref value should be 'develop', so an upstream dependency - # only relevant for, say, code formatting does not need to - # induce a new commit on 'main', or a release. - # https://cyberdomainontology.org/ontology/development/#branching-cdo-git-flow - ref: main - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 - with: - python-version: ${{ matrix.python-version }} - - name: Review dependencies - run: make check-supply-chain diff --git a/.gitignore b/.gitignore index 39a00e3..69a9f89 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,9 @@ -*.egg-info +*.done.log +*.egg-info/ *.swp .DS_Store -.git_submodule_init.done.log -.venv-pre-commit +.idea/ +.venv-pre-commit/ __pycache__ -build -dist +build/ +dist/ diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index e69de29..0000000 diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..3b50991 --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,14 @@ +# Contributing to CDO-Utility-Local-UUID + +This project uses [the `pre-commit` tool](https://pre-commit.com/) for linting. The easiest way to install it is with `pip`: +```bash +pip install pre-commit +pre-commit --version +``` + +The `pre-commit` tool hooks into Git's commit machinery to run a set of linters and static analyzers over each change. To install `pre-commit` into Git's hooks, run: +```bash +pre-commit install +``` + +To support offline development, `make` or `make check` will install and configure `pre-commit` in any local Git clone. diff --git a/Makefile b/Makefile index 0c0f3d0..cf0638a 100644 --- a/Makefile +++ b/Makefile @@ -23,14 +23,8 @@ all: \ .PHONY: \ check-supply-chain \ - check-supply-chain-mypy \ check-supply-chain-pre-commit -.git_submodule_init.done.log: \ - .gitmodules - git submodule update --init - touch $@ - # This virtual environment is meant to be built once and then persist, even through 'make clean'. # If a recipe is written to remove this flag file, it should first run `pre-commit uninstall`. .venv-pre-commit/var/.pre-commit-built.log: @@ -55,7 +49,6 @@ all: \ touch $@ check: \ - check-supply-chain-mypy \ .venv-pre-commit/var/.pre-commit-built.log $(MAKE) \ PYTHON3=$(PYTHON3) \ @@ -64,16 +57,9 @@ check: \ # This target's dependencies potentially modify the working directory's Git state, so it is intentionally not a dependency of check. check-supply-chain: \ - check-supply-chain-pre-commit \ - check-supply-chain-mypy - -check-supply-chain-mypy: \ - .git_submodule_init.done.log - $(MAKE) \ - PYTHON3=$(PYTHON3) \ - --directory tests \ - check-mypy + check-supply-chain-pre-commit +# This target is scheduled to run as part of prerelease review. check-supply-chain-pre-commit: \ .venv-pre-commit/var/.pre-commit-built.log source .venv-pre-commit/bin/activate \ @@ -83,12 +69,13 @@ check-supply-chain-pre-commit: \ .pre-commit-config.yaml clean: - @rm -rf \ - *.egg-info \ - build \ - dist @$(MAKE) \ --directory tests \ clean - @rm -f \ - .git_submodule_init.done.log + +distclean: \ + clean + @rm -rf \ + build \ + *.egg-info \ + dist diff --git a/README.md b/README.md index d04ed76..c4ff50b 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,81 @@ -# CASE Implementation Template: CLI Example +# CDO Local UUID Utility -[![Continuous Integration](https://github.com/casework/CASE-Implementation-Template-Python-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/casework/CASE-Implementation-Template-Python-CLI/actions/workflows/ci.yml) -![CASE Version](https://img.shields.io/badge/CASE%20Version-1.2.0-green) +[![Continuous Integration](https://github.com/Cyber-Domain-Ontology/CDO-Utility-Local-UUID/actions/workflows/cicd.yml/badge.svg)](https://github.com/Cyber-Domain-Ontology/CDO-Utility-Local-UUID/actions/workflows/cicd.yml) -_(Please see the [NIST disclaimer](#disclaimer).)_ +This project provides a specialized UUID-generating function that can, on user request, cause a program to generate deterministic UUIDs. Its main purpose is to assist with generating version-controllable example data using consistent identifiers. This package intentionally includes mechanisms to make it difficult to activate this non-random mode without awareness of the caller. -This template repository is provided for those looking to develop command-line utilities using ontologies within the [Cyber Domain Ontology](https://cyberdomainontology.org) ecosystem, particularly [CASE](https://caseontology.org) and [UCO](https://unifiedcyberontology.org). -This template repository provides a [Make](https://en.wikipedia.org/wiki/Make_%28software%29)-based test workflow used in some other CASE projects. The workflow exercises this project as a command-line interface (CLI) application (under [`tests/cli/`](tests/cli/)), and as a package (under [`tests/package/`](tests/package/)). +## Disclaimer -This is only one possible application development style, and templates are available to support other styles. See for instance: +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. -* [casework/CASE-Mapping-Template-Python](https://github.com/casework/CASE-Mapping-Template-Python), which demonstrates an approach based on constructing Python `dict`s and checking generated results afterwards for CASE conformance with the [CASE Validation Action](https://github.com/kchason/case-validation-action). -Testing procedures run in _this_ repository are: +## Installation -* _GitHub Actions_: [Workflows](.github/workflows/) are defined to run testing as they would be run in a local command-line environment, reviewing on pushes and pull requests to certain branches. -* _Supply chain review_: [One workflow](.github/workflows/supply-chain.yml) checks dependencies on a schedule, confirming pinned dependencies are the latest, and loosely-pinned dependencies do not impact things like type review. -* _Type review_: `mypy --strict` reviews the package source tree and the tests directory. -* _Code style_: `pre-commit` reviews code patches in Continuous Integration testing and in local development. Running `make` will install `pre-commit` in a special virtual environment dedicated to the cloned repository instance. -* _Doctests_: Module docstrings' inlined tests are run with `pytest`. -* _CASE validation_: Unit tests that generate CASE graph files are written to run `case_validate` before considering the file "successfully" built. -* _Editable package installation_: The test suite installs the package in an "editable" mode into the virtual environment under `tests/venv/`. Activating the virtual environment (e.g. for Bash users, running `source tests/venv/bin/activate` from the repository's top source directory) enables "live code" testing. -* _Parallel Make runs_: Tests based on `make` have dependencies specified in a manner that enables `make --jobs` to run testing in parallel. -* _Directory-local Make runs_: The Makefiles are written to run regardless of the present working directory within the top source directory or the [`tests/`](tests/) directory, assuming `make check` has been run from the top source directory at least once. If a test is failing, `cd`'ing into that test's directory and running `make check` should reproduce the failure quickly and focus development effort. +This repository can be installed from PyPI or from source. -## Usage +### Installing from PyPI -To use the template, push the "Use this template" button on GitHub, and adapt files as suits your new project's needs. The README should be revised at least from its top to the "Versioning" section. Source files should be renamed and revised, and any other files with a `TODO` within it should be adjusted. +```bash +pip install cdo-local-uuid +``` -After any revisions, running `make check` (or `make -j check`) from the top source directory should have unit tests continue to pass. +### Installing from source -_Below this line is sample text to use and adapt for your project. Most text above this line is meant to document the template, rather than projects using the template._ +Users who wish to install pre-release versions and/or make improvements to the code base should install in this manner. -To install this software, clone this repository, and run `pip install .` from within this directory. (You might want to do this in a virtual environment.) +1. Clone this repository. +2. (Optional) Create and activate a virtual environment. +3. Run `pip install $x`, where `$x` is the path to the cloned repository. -This provides a standalone command: +Local installation is demonstrated in the `.venv.done.log` target of the `tests/` directory's [`Makefile`](tests/Makefile). -```bash -case_cli_example output.rdf -``` -The tests build several examples of output for the command line mode, under [`tests/cli`](tests/cli/). +## Usage -The installation also provides a package to import: +[This module](cdo_local_uuid/__init__.py) provides a wrapper UUID generator, `local_uuid()`. It is intended to replace the Python call sequence `str(uuid.uuid4())`. In the default behavior, the two idioms behave the same: ```python -import case_cli_example -help(case_cli_example.foo) +>>> from uuid import uuid4 +>>> from cdo_local_uuid import local_uuid +>>> str(uuid4()) +'168ec24a-4920-43f5-85ad-9c6088b0cad8' +>>> local_uuid() +'bd203d75-f3eb-40fe-a266-b447beadbd54' ``` +However, for some code-demonstration purposes, deterministic UUIDs might be desired, e.g. so a demonstration file including generated UUIDs can be regenerated and only change when the code changes, reducing version-control noise. + +To see how to configure UUID generation, see the `_demo_uuid` function in [this module](cdo_local_uuid/__init__.py). + + +## 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. +## Dependencies + +This repository's primary module was originally part of the [`case-utils`](https://github.com/casework/CASE-Utilities-Python) package. It was separated to provide a package with no runtime dependencies outside of the Python standard library. + + ## Make targets Some `make` targets are defined for this repository: -* `all` - Installs `pre-commit` for this cloned repository instance. -* `check` - Run unit tests. *NOTE*: The tests entail an installation of this project's source tree, including prerequisites downloaded from PyPI. -* `clean` - Remove test build files. +* `check` - Run unit tests. +* `clean` - Remove test build files, but not downloaded files. ## Licensing Portions of this repository contributed by NIST are governed by the [NIST Software Licensing Statement](LICENSE#nist-software-licensing-statement). - - -## 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. diff --git a/README_PyPI.md b/README_PyPI.md new file mode 100644 index 0000000..15b240e --- /dev/null +++ b/README_PyPI.md @@ -0,0 +1,5 @@ +# CDO Local UUID Utility + +This project provides a specialized UUID-generating function that can, on user request, cause a program to generate deterministic UUIDs. Its main purpose is to assist with generating version-controllable example data using consistent identifiers. This package intentionally includes mechanisms to make it difficult to activate this non-random mode without awareness of the caller. + +Full documentation is available at the [project homepage](https://github.com/Cyber-Domain-Ontology/CDO-Utility-Local-UUID). diff --git a/case_cli_example/__init__.py b/case_cli_example/__init__.py deleted file mode 100644 index e2e895c..0000000 --- a/case_cli_example/__init__.py +++ /dev/null @@ -1,33 +0,0 @@ -#!/usr/bin/env python3 - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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. - -# TODO - Adapt below. - -""" -case_cli_example is a command that demonstrates making a CLI application tested with a Make-based workflow. -""" - -__version__ = "0.0.1" - - -def foo() -> str: - """ - This function is provided to demonstrate the doctests system templated in this repository. If all doctests from the package source directory are removed, the 'check-doctest' recipe in /tests/Makefile will also need to be removed, because pytest reports a failure if no tests are found. - - >>> foo() - 'x' - """ - return "x" diff --git a/case_cli_example/cli.py b/case_cli_example/cli.py deleted file mode 100644 index 13f37ef..0000000 --- a/case_cli_example/cli.py +++ /dev/null @@ -1,97 +0,0 @@ -#!/usr/bin/env python3 - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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. - -# TODO - Adapt below. - -import argparse -import logging - -import case_utils -from case_utils.local_uuid import local_uuid -from case_utils.namespace import NS_RDF, NS_UCO_CORE, NS_UCO_IDENTITY, NS_XSD -from rdflib import Graph, Literal, Namespace -from rdflib.util import guess_format - - -def main() -> None: - argument_parser = argparse.ArgumentParser() - argument_parser.add_argument( - "--kb-prefix", - default="kb", - help="Prefix label to use for knowledge-base individuals. E.g. with defaults, 'http://example.org/kb/Thing-1' would compact to 'kb:Thing-1'.", - ) - argument_parser.add_argument( - "--kb-prefix-iri", - default="http://example.org/kb/", - help="Prefix IRI to use for knowledge-base individuals. E.g. with defaults, 'http://example.org/kb/Thing-1' would compact to 'kb:Thing-1'.", - ) - argument_parser.add_argument("--debug", action="store_true") - argument_parser.add_argument( - "--output-format", help="Override extension-based format guesser." - ) - # The output graph is suggested as the first positional argument to - # allow for an arbitrary number of input files as the command's end. - argument_parser.add_argument( - "out_graph", - help="A self-contained RDF graph file, in the format either requested by --output-format or guessed based on extension.", - ) - argument_parser.add_argument("in_file", nargs="*", help="One or more input files.") - - args = argument_parser.parse_args() - logging.basicConfig(level=logging.DEBUG if args.debug else logging.INFO) - - # See case_utils.local_uuid._demo_uuid for how to use this to set up - # a process call that opts in to nonrandom UUIDs. Opting in is - # beneficial for generating and version-controlling example runs of - # this tool, but might not be appropriate for production operation. - case_utils.local_uuid.configure() - - # Define Namespace object to assist with generating individual nodes. - ns_kb = Namespace(args.kb_prefix_iri) - - graph = Graph() - - # Bind various prefixes to prefix-IRIs in the output graph. - # At the time of this writing, this compacts Turtle data, but does - # not induce a JSON-LD Context Dictionary. - graph.namespace_manager.bind(args.kb_prefix, ns_kb) - graph.namespace_manager.bind("uco-core", NS_UCO_CORE) - graph.namespace_manager.bind("uco-identity", NS_UCO_IDENTITY) - - # This binding should be kept, because various RDF frameworks - # disagree on whether "xs:" or "xsd:" should be the prefix, and - # conflicting usage can lead to confusion or data errors when - # multiple tools contribute to the same graph. - graph.namespace_manager.bind("xsd", NS_XSD) - - # Generate an example object. - n_example_organization = ns_kb["Organization-" + local_uuid()] - graph.add((n_example_organization, NS_RDF.type, NS_UCO_IDENTITY.Organization)) - graph.add( - (n_example_organization, NS_UCO_CORE.name, Literal("Cyber Domain Ontology")) - ) - - # Write output file. - output_format = ( - guess_format(args.out_graph) - if args.output_format is None - else args.output_format - ) - graph.serialize(destination=args.out_graph, format=output_format) - - -if __name__ == "__main__": - main() diff --git a/cdo_local_uuid/__init__.py b/cdo_local_uuid/__init__.py new file mode 100644 index 0000000..e6cbd88 --- /dev/null +++ b/cdo_local_uuid/__init__.py @@ -0,0 +1,166 @@ +#!/usr/bin/env python3 + +# Portions of this file contributed by NIST are governed by the +# following statement: +# +# 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 within the United States. 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. + +""" +This library is a wrapper for uuid, provided to generate repeatable UUIDs if requested. + +The function local_uuid() should be used in code where a user could be expected to opt in to non-random UUIDs. +""" + +__version__ = "0.4.0" + +__all__ = ["configure", "local_uuid"] + +import logging +import os +import pathlib +import sys +import typing +import uuid +import warnings + +DEMO_UUID_BASE: typing.Optional[str] = None + +DEMO_UUID_COUNTER: int = 0 + +_logger = logging.getLogger(pathlib.Path(__file__).name) + + +def configure() -> None: + """ + This function is part of setting up _demo_uuid() to generate non-random UUIDs. See _demo_uuid() documentation for further setup notes. + """ + global DEMO_UUID_BASE + + if os.getenv("DEMO_UUID_REQUESTING_NONRANDOM") == "NONRANDOM_REQUESTED": + warnings.warn( + "Environment variable DEMO_UUID_REQUESTING_NONRANDOM is deprecated. See case_utils.local_uuid._demo_uuid for usage notes on its replacement, CASE_DEMO_NONRANDOM_UUID_BASE. Proceeding with random UUIDs.", + FutureWarning, + ) + return + + env_base_dir_name = os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE") + if env_base_dir_name is None: + return + + base_dir_original_path = pathlib.Path(env_base_dir_name) + if not base_dir_original_path.exists(): + warnings.warn( + "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to an existing directory. Proceeding with random UUIDs.", + RuntimeWarning, + ) + return + if not base_dir_original_path.is_dir(): + warnings.warn( + "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to a directory. Proceeding with random UUIDs.", + RuntimeWarning, + ) + return + + # Component: An emphasis this is an example. + demo_uuid_base_parts = ["example.org"] + + # Component: Present working directory, relative to CASE_DEMO_NONRANDOM_UUID_BASE if that environment variable is an ancestor of pwd. + base_dir_resolved_path = base_dir_original_path.resolve() + srcdir_original_path = pathlib.Path(os.getcwd()) + srcdir_resolved_path = srcdir_original_path.resolve() + # _logger.debug("base_dir_resolved_path = %r.", base_dir_resolved_path) + # _logger.debug("srcdir_resolved_path = %r.", srcdir_resolved_path) + try: + srcdir_relative_path = srcdir_resolved_path.relative_to(base_dir_resolved_path) + # _logger.debug("srcdir_relative_path = %r.", srcdir_relative_path) + demo_uuid_base_parts.append(str(srcdir_relative_path)) + except ValueError: + # If base_dir is not an ancestor directory of srcdir, default to srcdir. + # _logger.debug("PWD is not relative to base path.") + demo_uuid_base_parts.append(str(srcdir_resolved_path)) + + # Component: Command of argument vector. + env_venv_name = os.getenv("VIRTUAL_ENV") + if env_venv_name is None: + demo_uuid_base_parts.append(sys.argv[0]) + else: + command_original_path = pathlib.Path(sys.argv[0]) + command_resolved_path = command_original_path.resolve() + venv_original_path = pathlib.Path(env_venv_name) + venv_resolved_path = venv_original_path.resolve() + try: + command_relative_path = command_resolved_path.relative_to( + venv_resolved_path + ) + # _logger.debug("command_relative_path = %r.", command_relative_path) + demo_uuid_base_parts.append(str(command_relative_path)) + except ValueError: + # _logger.debug("Command path is not relative to virtual environment path.") + demo_uuid_base_parts.append(str(command_resolved_path)) + + if len(sys.argv) > 1: + # Component: Arguments of argument vector. + demo_uuid_base_parts.extend(sys.argv[1:]) + + # _logger.debug("demo_uuid_base_parts = %r.", demo_uuid_base_parts) + + DEMO_UUID_BASE = "/".join(demo_uuid_base_parts) + + +def _demo_uuid() -> str: + """ + This function generates a repeatable UUID, drawing on non-varying elements of the environment and process call for entropy. + + This function is not intended to be called outside of this module. Instead, local_uuid() should be called. + + WARNING: This function was developed for use ONLY for reducing (but not eliminating) version-control edits to identifiers when generating sample data. It creates UUIDs that are decidedly NOT random, and should remain consistent on repeated calls to the importing script. + + To prevent accidental non-random UUID usage, two setup steps need to be done before calling this function: + + * An environment variable, CASE_DEMO_NONRANDOM_UUID_BASE, must be set to a string provided by the caller. The variable's required value is the path to some directory. The variable's recommended value is the equivalent of the Make variable "top_srcdir" - that is, the root directory of the containing Git repository, some parent of the current process's current working directory. + * The configure() function in this module must be called. + """ + global DEMO_UUID_BASE + global DEMO_UUID_COUNTER + + if os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE") is None: + raise ValueError( + "demo_uuid() called without CASE_DEMO_NONRANDOM_UUID_BASE in environment." + ) + + if DEMO_UUID_BASE is None: + raise ValueError("demo_uuid() called with DEMO_UUID_BASE unset.") + + parts = [DEMO_UUID_BASE] + + # Component: Incrementing counter. + DEMO_UUID_COUNTER += 1 + parts.append(str(DEMO_UUID_COUNTER)) + + return str(uuid.uuid5(uuid.NAMESPACE_URL, "/".join(parts))) + + +def local_uuid() -> str: + """ + Generate either a UUID4, or if requested via environment configuration, a non-random demo UUID. + + >>> from cdo_local_uuid import local_uuid + >>> from uuid import UUID + >>> lu: str = local_uuid() + >>> # To get a UUID object, e.g. to verify syntax, feed local_uuid's string output into the UUID constructor. + >>> u = UUID(lu) + """ + global DEMO_UUID_BASE + if DEMO_UUID_BASE is None: + return str(uuid.uuid4()) + else: + return _demo_uuid() diff --git a/case_cli_example/py.typed b/cdo_local_uuid/py.typed similarity index 88% rename from case_cli_example/py.typed rename to cdo_local_uuid/py.typed index 3a6cd3a..38c5320 100644 --- a/case_cli_example/py.typed +++ b/cdo_local_uuid/py.typed @@ -1,5 +1,5 @@ -# Portions of this file contributed by NIST are governed by the -# following statement: +# Portions of this file contributed by NIST are governed by the following +# statement: # # This software was developed at the National Institute of Standards # and Technology by employees of the Federal Government in the course diff --git a/code.yaml b/code.yaml index 2111f90..a40bf7c 100644 --- a/code.yaml +++ b/code.yaml @@ -1,14 +1,15 @@ # NIST Opensource Portal repositories categories and themes. -# -# Chose at least one category and as many themes as you think -# adequate your opensource repository. -# You are also able to provide futher details on the choices. +# Source: https://www.nist.gov/topics +# Choose one catgeory and at least one theme as you think +# adequate for your opensource repository. +# Uncomment the category and the research +# themes that suit you best. +# You are also able to provide further details on the choices. # For example you could do: # categories: # - scientific-software: # - quantum-computing # - theory -# The same applies to themes. # Since scientific-software is most common it is left as default. # Feel free to comment it with a dash if not appropriate. # You are able to pick multiple categories and themes. @@ -17,23 +18,36 @@ # topics. The final topics are produced from this file and the topics. categories: - - scientific-software - #- simulation - #- visualization - #- ai-ml - #- build-tools - #- hpc-workflow + # - scientific-software + # - ai-ml + # - simulation + # - visualization + - build-tools + # - hpc-workflow themes: # - Advanced communications - # - Optical communications - # - Quantum communications + # - Artificial intelligence # - Bioscience - # - Buildings and Construction + # - Buildings & Construction # - Chemistry + - Cybersecurity # - Electronics # - Energy # - Environment # - Fire - Forensic Science # - Health - - Information technology + - Information Technology + # - Infrastructure + # - Manufacturing + # - Materials + # - Mathematics & Statistics + # - Metrology + # - Nanotechnology + # - Neutron research + # - Performance excellence + # - Physics + # - Public safety + # - Resilience + - Standards + # - Transportation diff --git a/setup.cfg b/setup.cfg index 42c7112..0450fd5 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,49 +1,38 @@ [metadata] -#TODO -name = case_cli_example -version = attr: case_cli_example.__version__ -#TODO -# author = Example Person -# author_email = person@example.org -#TODO -description = A mapping of Example Tool to CASE -license_files = - LICENSE - THIRD_PARTY_LICENSES.md -#TODO - PyPI will need a differently-written README. -long_description = file: README.md +name = cdo-local-uuid +version = attr: cdo_local_uuid.__version__ +author = Alex Nelson +author_email = alexander.nelson@nist.gov +description = Python utility for optionally controlling UUID generation +long_description = file: README_PyPI.md long_description_content_type = text/markdown -#TODO -url = https://github.com/casework/CASE-Implementation-Example +url = https://github.com/Cyber-Domain-Ontology/CDO-Utility-Local-UUID classifiers = - # TODO - # Please select a Development Status in line with CASE community guidance: - # https://caseontology.org/resources/github_policies.html#development-statuses - # E.g.: - # Development Status :: 3 - Alpha + Development Status :: 4 - Beta Enviroment :: Console + Intended Audience :: Developers Operating System :: OS Independent Programming Language :: Python :: 3 - Topic :: Software Development :: Testing + Topic :: Documentation + Topic :: Software Development :: Build Tools + Topic :: Software Development :: Libraries :: Python Modules + Topic :: Software Development :: Testing :: Mocking + Topic :: Utilities +license_files = + THIRD_PARTY_LICENSES.md [options] -install_requires = - case_utils >= 0.14.0, < 0.15.0 +include_package_data = true packages = find: -python_requires = >=3.9 - -[options.entry_points] -console_scripts = - #TODO - case_cli_example = case_cli_example.cli:main +python_requires = >=3.8 [options.extras_require] testing = - case_utils[testing] + mypy + pytest [options.package_data] -#TODO -case_cli_example = py.typed +cdo_local_uuid = py.typed [flake8] # https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8 diff --git a/tests/.gitignore b/tests/.gitignore index d85f153..9d74dcf 100644 --- a/tests/.gitignore +++ b/tests/.gitignore @@ -1,6 +1,3 @@ .pytest_cache -.venv.done.log -.venv_minimal.done.log _* venv -venv_minimal diff --git a/tests/Makefile b/tests/Makefile index 5e97583..076fb05 100644 --- a/tests/Makefile +++ b/tests/Makefile @@ -1,7 +1,7 @@ #!/usr/bin/make -f -# Portions of this file contributed by NIST are governed by the -# following statement: +# Portions of this file contributed by NIST are governed by the following +# statement: # # This software was developed at the National Institute of Standards # and Technology by employees of the Federal Government in the course @@ -20,15 +20,13 @@ top_srcdir := $(shell cd .. ; pwd) PYTHON3 ?= python3 -# Dependencies are listed here in desired execution-progression order. all: .PHONY: \ - check-cli \ + check-doctest \ check-mypy .venv.done.log: \ - $(top_srcdir)/.git_submodule_init.done.log \ $(top_srcdir)/setup.cfg \ $(top_srcdir)/setup.py rm -rf venv @@ -41,23 +39,19 @@ all: setuptools \ wheel source venv/bin/activate \ - && pip install \ - --editable \ - $(top_srcdir)[testing] + && cd $(top_srcdir) \ + && pip install \ + --editable \ + .[testing] touch $@ -# Dependencies are listed here in desired execution-progression order. +# These check calls are provided in preferred run-order. check: \ check-mypy \ - check-doctest \ - check-cli \ - check-package - -check-cli: \ - .venv.done.log - $(MAKE) \ - --directory cli \ - check + check-doctest + source venv/bin/activate \ + && pytest \ + --log-level=DEBUG check-doctest: \ .venv.done.log @@ -65,13 +59,7 @@ check-doctest: \ && pytest \ --doctest-modules \ --log-level=DEBUG \ - $(top_srcdir)/case_cli_example - -check-package: \ - .venv.done.log - $(MAKE) \ - --directory package \ - check + $(top_srcdir)/cdo_local_uuid check-mypy: \ .venv.done.log @@ -79,11 +67,12 @@ check-mypy: \ && mypy \ --exclude venv \ --strict \ - $(top_srcdir)/case_cli_example \ + $(top_srcdir)/cdo_local_uuid \ . clean: @rm -f \ .venv.done.log @rm -rf \ + .pytest_cache \ venv diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index 829d8d1..0000000 --- a/tests/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Test suite - -This directory houses proof-of-functionality tests. -* [`gtime_log/`](gtime_log/) - Uses scripts in source tree to build a UCO Process object in a JSON-LD file, using only a GNU Time log file. Uses a virtual environment built without installing `case_gnu_time`. -* [`gtime_and_done_log/`](gtime_and_done_log/) - As `gtime_log/`, but using a timestamp recorded in another file tied to a process output. -* [`from_pip/`](from_pip/) - Uses virtual environment with the package `case_gnu_time` installed. (Runs [`setup.py`](../setup.py), not `pip install`.) Runs program `case_gnu_time`, producing a Process as in `gtime_log`. -* [`as_import/`](as_import/) - Uses `case_gnu_time` as an imported package to create a custom-named UCO `CyberItem` with a Process Facet. - - -## Running the test suite - -Run `make check`. `make check` should be run from one directory up, at least once, to trigger some downloads. diff --git a/tests/cli/Makefile b/tests/cli/Makefile deleted file mode 100644 index 94fd389..0000000 --- a/tests/cli/Makefile +++ /dev/null @@ -1,71 +0,0 @@ -#!/usr/bin/make -f - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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 - -top_srcdir := $(shell cd ../.. ; pwd) - -all: \ - example_output.jsonld \ - example_output.rdf \ - example_output.ttl \ - example_output_debug.jsonld \ - example_output_debug.rdf \ - example_output_debug.ttl - -.PHONY: \ - check-pytest - -check: \ - check-pytest - -check-pytest: \ - all - source $(top_srcdir)/tests/venv/bin/activate \ - && pytest \ - --log-level=DEBUG - -clean: - @rm -rf \ - *.jsonld \ - *.rdf \ - *.ttl \ - .pytest_cache - -example_output.%: \ - $(top_srcdir)/case_cli_example/cli.py \ - $(top_srcdir)/tests/.venv.done.log - export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \ - && source $(top_srcdir)/tests/venv/bin/activate \ - && case_cli_example \ - _$@ - source $(top_srcdir)/tests/venv/bin/activate \ - && case_validate \ - _$@ - mv _$@ $@ - -example_output_debug.%: \ - $(top_srcdir)/case_cli_example/cli.py \ - $(top_srcdir)/tests/.venv.done.log - export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \ - && source $(top_srcdir)/tests/venv/bin/activate \ - && case_cli_example \ - --debug \ - _$@ - source $(top_srcdir)/tests/venv/bin/activate \ - && case_validate \ - _$@ - mv _$@ $@ diff --git a/tests/cli/example_output.jsonld b/tests/cli/example_output.jsonld deleted file mode 100644 index 5fc7c7c..0000000 --- a/tests/cli/example_output.jsonld +++ /dev/null @@ -1,13 +0,0 @@ -[ - { - "@id": "http://example.org/kb/Organization-b7c4b9e3-a93b-53b8-8a58-243986ddc2dc", - "@type": [ - "https://ontology.unifiedcyberontology.org/uco/identity/Organization" - ], - "https://ontology.unifiedcyberontology.org/uco/core/name": [ - { - "@value": "Cyber Domain Ontology" - } - ] - } -] \ No newline at end of file diff --git a/tests/cli/example_output.rdf b/tests/cli/example_output.rdf deleted file mode 100644 index 3370312..0000000 --- a/tests/cli/example_output.rdf +++ /dev/null @@ -1,10 +0,0 @@ - - - - - Cyber Domain Ontology - - diff --git a/tests/cli/example_output.ttl b/tests/cli/example_output.ttl deleted file mode 100644 index 96629bb..0000000 --- a/tests/cli/example_output.ttl +++ /dev/null @@ -1,7 +0,0 @@ -@prefix kb: . -@prefix uco-core: . -@prefix uco-identity: . - -kb:Organization-a70ee2b7-9fd8-537f-8f70-6f68805acae6 a uco-identity:Organization ; - uco-core:name "Cyber Domain Ontology" . - diff --git a/tests/cli/example_output_debug.jsonld b/tests/cli/example_output_debug.jsonld deleted file mode 100644 index 4c8bb03..0000000 --- a/tests/cli/example_output_debug.jsonld +++ /dev/null @@ -1,13 +0,0 @@ -[ - { - "@id": "http://example.org/kb/Organization-2ffb424f-ef33-5cc9-8185-091073051016", - "@type": [ - "https://ontology.unifiedcyberontology.org/uco/identity/Organization" - ], - "https://ontology.unifiedcyberontology.org/uco/core/name": [ - { - "@value": "Cyber Domain Ontology" - } - ] - } -] \ No newline at end of file diff --git a/tests/cli/example_output_debug.rdf b/tests/cli/example_output_debug.rdf deleted file mode 100644 index 8993233..0000000 --- a/tests/cli/example_output_debug.rdf +++ /dev/null @@ -1,10 +0,0 @@ - - - - - Cyber Domain Ontology - - diff --git a/tests/cli/example_output_debug.ttl b/tests/cli/example_output_debug.ttl deleted file mode 100644 index 8b8d038..0000000 --- a/tests/cli/example_output_debug.ttl +++ /dev/null @@ -1,7 +0,0 @@ -@prefix kb: . -@prefix uco-core: . -@prefix uco-identity: . - -kb:Organization-10639c31-bef6-57b7-9747-71171b669844 a uco-identity:Organization ; - uco-core:name "Cyber Domain Ontology" . - diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py deleted file mode 100644 index 7ce2422..0000000 --- a/tests/cli/test_cli.py +++ /dev/null @@ -1,86 +0,0 @@ -#!/usr/bin/env python3 - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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. - -from pathlib import Path -from typing import Set - -import pytest -from case_utils.namespace import NS_RDF, NS_UCO_IDENTITY -from rdflib import Graph, URIRef -from rdflib.query import ResultRow - - -@pytest.mark.parametrize( - ["filename"], - [ - ("example_output.jsonld",), - ("example_output.rdf",), - ("example_output.ttl",), - ("example_output_debug.jsonld",), - ("example_output_debug.rdf",), - ("example_output_debug.ttl",), - ], -) -def test_example_output_with_iterator(filename: str) -> None: - srcdir = Path(__file__).parent - graph = Graph() - graph.parse(srcdir / filename) - n_organizations: Set[URIRef] = set() - for n_subject in graph.subjects(NS_RDF.type, NS_UCO_IDENTITY.Organization): - assert isinstance(n_subject, URIRef) - n_organizations.add(n_subject) - assert len(n_organizations) == 1 - - -@pytest.mark.parametrize( - ["filename"], - [ - ("example_output.jsonld",), - ("example_output.rdf",), - ("example_output.ttl",), - ("example_output_debug.jsonld",), - ("example_output_debug.rdf",), - ("example_output_debug.ttl",), - ], -) -def test_example_output_with_sparql(filename: str) -> None: - srcdir = Path(__file__).parent - graph = Graph() - graph.parse(srcdir / filename) - - # This query includes a prefix statement that is typically provided - # by the data graph. However, some graph generators omit prefixes - # if they are never referenced in the triples. In that case, - # attempting to run this query without a PREFIX statement would fail - # due to an unbound prefix. While ultimately the test would be - # correct in failing, it would fail for a potentially confusing - # reason appearing to be a syntax error, rather than a real reason - # of the query having no data to find. - query = """\ -PREFIX uco-identity: -SELECT ?nOrganization -WHERE { - ?nOrganization - a uco-identity:Organization ; - . -} -""" - n_organizations: Set[URIRef] = set() - for result in graph.query(query): - assert isinstance(result, ResultRow) - assert isinstance(result[0], URIRef) - n_organizations.add(result[0]) - assert len(n_organizations) == 1 diff --git a/tests/package/Makefile b/tests/package/Makefile deleted file mode 100644 index 207a6d7..0000000 --- a/tests/package/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -#!/usr/bin/make -f - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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 - -top_srcdir := $(shell cd ../.. ; pwd) - -all: - -.PHONY: \ - check-pytest - -check: \ - check-pytest - -check-pytest: - source $(top_srcdir)/tests/venv/bin/activate \ - && pytest \ - --log-level=DEBUG - -clean: diff --git a/tests/package/test_package.py b/tests/package/test_package.py deleted file mode 100644 index 9dc5d33..0000000 --- a/tests/package/test_package.py +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env python3 - -# Portions of this file contributed by NIST are governed by the -# following statement: -# -# 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 within the United States. 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. - -from case_cli_example import foo - - -def test_package() -> None: - assert foo() == "x" diff --git a/tests/test_local_uuid.py b/tests/test_local_uuid.py new file mode 100644 index 0000000..b1ccecd --- /dev/null +++ b/tests/test_local_uuid.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 + +# Portions of this file contributed by NIST are governed by the +# following statement: +# +# 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 within the United States. 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. + +import pytest + +import cdo_local_uuid + + +def test_local_uuid_deprecation(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("DEMO_UUID_REQUESTING_NONRANDOM", "NONRANDOM_REQUESTED") + with pytest.warns(FutureWarning): + cdo_local_uuid.configure() + + +def test_local_uuid_nondirectory(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("CASE_DEMO_NONRANDOM_UUID_BASE", "/dev/null") + with pytest.warns(RuntimeWarning): + cdo_local_uuid.configure() + + +def test_local_uuid_nonexistent(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("CASE_DEMO_NONRANDOM_UUID_BASE", "/dev/nonexistent") + with pytest.warns(RuntimeWarning): + cdo_local_uuid.configure()