From 7ce2ab4661e9107c5f2cd316daaa638bd43179ff Mon Sep 17 00:00:00 2001 From: Casper Welzel Andersen <43357585+CasperWA@users.noreply.github.com> Date: Fri, 26 Apr 2024 10:50:42 +0200 Subject: [PATCH] Update README with pre-commit and CLI info (#134) Also, add acknowledgements for MEDIATE and MatCHMaker projects. Ensure the README pre-commit rev value is updated. Ensure it follows the package version. Co-authored-by: Treesa Joseph <Treesa.Joseph@sintef.no> --- .github/workflows/cd_release.yml | 4 ++ README.md | 70 ++++++++++++++++++++++++++++++-- 2 files changed, 71 insertions(+), 3 deletions(-) diff --git a/.github/workflows/cd_release.yml b/.github/workflows/cd_release.yml index 51ec7eea..202ab14c 100644 --- a/.github/workflows/cd_release.yml +++ b/.github/workflows/cd_release.yml @@ -24,6 +24,10 @@ jobs: build_libs: flit build_cmd: "flit build" changelog_exclude_labels: skip_changelog,duplicate,question,invalid,wontfix + version_update_changes_separator: "," + version_update_changes: | + {package_dir}/__init__.py,__version__ *= *(?:'|\").*(?:'|\"),__version__ = \"{version}\" + README.md,rev: v[0-9]+.*$,rev: v{version} publish_on_pypi: false # Documentation diff --git a/README.md b/README.md index e1efe0f7..d8a39fcf 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,16 @@ -# Service for serving entities +# Entities Service + +> REST API service for serving entities This is a FastAPI-based REST API service running on onto-ns.com. It's purpose is to serve entities from an underlying database. +Other than the REST API service, the repository also contains a CLI for validating and uploading entities to the service, as well as create and manipulate the service' configuration file. +See the [CLI documentation](#cli) for more information. + +The repository also contains a [pre-commit](https://pre-commit.com/) hook `validate-entities`, which may be used externally to validate entities before committing them a repository. +See the [pre-commit hook documentation](#pre-commit-hook-validate-entities) for more information. + ## Install the service First, download and install the Python package from GitHub: @@ -135,9 +143,57 @@ For using it locally, no changes are needed, as the service will automatically c For using it with Docker, use the `--env-file .env` argument when calling `docker run` or `docker compose up`. +## CLI + +The CLI is a command-line interface for interacting with the Entities Service. +It can be used to validate and upload entities to the service, as well as create and manipulate the service' configuration file. + +To see the available commands and options, run: + +```shell +entities-service --help +``` + +## pre-commit hook `validate-entities` + +The `validate-entities` [pre-commit](https://pre-commit.com) hook runs the CLI command `entities-service validate` on all files that are about to be committed. +This is to ensure that all entities are valid before committing them to the repository. + +By default it runs with the `--verbose` flag, which will print out detailed differences if an entity already exists externally and differs in its content. +Furthermore, it will run such that all supported file formats (currently JSON and YAML/YML) will be validated. + +**Important**: Add the `.[cli]` entry to the `additional_dependencies` argument. + +It is also advisable to focus in which directories or files the hook should run for, by adding the `files` argument. + +Here is an example of how to add the `validate-entities` pre-commit hook to your `.pre-commit-config.yaml` file, given a repository that contains entities in the `entities` directory in the root of the repository: + +```yaml +repos: +# ... +- repo: https://github.com/SINTEF/entities-service + rev: v0.4.0 + hooks: + - id: validate-entities + additional_dependencies: [".[cli]"] + files: ^entities/.*\.(json|yaml|yml)$ +``` + +This will run for all JSON, YAML, and YML files in the `entities` directory and its subdirectories. + +Note, you can add the `--no-external-calls` argument if you wish to not make external calls to the Entities Service when validating entities. +This is useful when running the pre-commit hook in an environment where the Entities Service is not available, or when you wish to only validate the entities locally. + +```yaml +# ... + args: ['--no-external-calls'] +# ... +``` + ## Testing -The service is tested using `pytest` and can be tested against a local MongoDB server and Entities Service instance or against a mock MongoDB server and Entities Service instance utilizing [Starlette's TestClient](https://fastapi.tiangolo.com/reference/testclient/#test-client-testclient). +The repository code is tested using `pytest`. +For the service, it can be tested against a local MongoDB server and Entities Service instance or against a mock MongoDB server and Entities Service instance utilizing [Starlette's TestClient](https://fastapi.tiangolo.com/reference/testclient/#test-client-testclient). To run the tests, first install the test dependencies: @@ -190,7 +246,7 @@ export ENTITIES_SERVICE_HOST=${ENTITIES_SERVICE_BASE_URL} docker compose up -d # Upload entities using the CLI -entities-service upload -f my_entities.yaml --format=yaml +entities-service upload my_entities.yaml --format=yaml ``` The `my_entities.yaml` file should contain one or more entities with `uri` values of the form `http://localhost:8000/...`. @@ -239,3 +295,11 @@ The fixture is available for all tests. All files in this repository are [MIT licensed](LICENSE). Copyright by [Casper Welzel Andersen](https://github.com/CasperWA), [SINTEF](https://www.sintef.no). + +## Acknowledgements + +This project is made possible by funding from: + +- MEDIATE (2022-2025) that receives funding from the RCN, Norway, FNR, Luxembourg, and SMWK, Germany via the M-ERA.NET programme, project9557. + M-ERA.NET 2 and M-ERA.NET 3 have received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreements No 685451 and No 958174. +- [MatCHMaker](https://he-matchmaker.eu) (2022-2026) that receives funding from the European Union’s Horizon Europe research and innovation programme under grant agreement No 101091687.