From 0930e96c384a915344c05f59cc9b40f5bc9e5641 Mon Sep 17 00:00:00 2001 From: "John M. Horan" Date: Thu, 30 May 2024 12:45:00 -0700 Subject: [PATCH 1/2] Update purldb-toolkit and related README files #249 Reference: https://github.com/nexB/purldb/issues/249 Signed-off-by: John M. Horan --- README.rst | 4 +- docs/scripts/sphinx_build_link_check.sh | 0 purldb-toolkit/README.rst | 513 ++++++++++++++++++++++-- 3 files changed, 490 insertions(+), 27 deletions(-) mode change 100644 => 100755 docs/scripts/sphinx_build_link_check.sh diff --git a/README.rst b/README.rst index 90eef783..608ed94c 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ The purldb ========== -This repo consists of four main tools: +This repo consists of these main tools: - PackageDB that is the reference model (based on ScanCode toolkit) that contains package data with purl (Package URLs) being a first @@ -10,6 +10,8 @@ This repo consists of four main tools: matching - MatchCode.io that provides package matching functionalities for codebases - ClearCode that contains utilities to mine Clearlydefined for package data +- purldb-toolkit CLI utility and library to use the PurlDB, its API and various + related libraries. These are designed to be used first for reference such that one can query for packages by purl and validate purl existence. diff --git a/docs/scripts/sphinx_build_link_check.sh b/docs/scripts/sphinx_build_link_check.sh old mode 100644 new mode 100755 diff --git a/purldb-toolkit/README.rst b/purldb-toolkit/README.rst index 4ac94a98..12abfd9b 100644 --- a/purldb-toolkit/README.rst +++ b/purldb-toolkit/README.rst @@ -1,12 +1,17 @@ purldb-toolkit ============== +.. contents:: :local: + :depth: 3 + + + purldb-toolkit is command line utility and library to use the PurlDB, its API and various related libraries. The ``purlcli`` command acts as a client to the PurlDB REST API end point(s) to expose PURL services. It serves both as a tool, as a library and as an example on how to use the services programmatically. - + Installation ------------ @@ -20,84 +25,541 @@ Use this command to get basic help:: $ purlcli --help Usage: purlcli [OPTIONS] COMMAND [ARGS]... - + Return information from a PURL. - + Options: --help Show this message and exit. - + Commands: metadata Given one or more PURLs, for each PURL, return a mapping of... urls Given one or more PURLs, for each PURL, return a list of all... - validate Check the syntax of one or more PURLs. + validate Check the syntax and upstream repo status of one or more PURLs. versions Given one or more PURLs, return a list of all known versions... And the following subcommands: -- Validate a PURL:: +'validate' -- validate a PURL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none $ purlcli validate --help Usage: purlcli validate [OPTIONS] - - Check the syntax of one or more PURLs. - + + Check the syntax and upstream repo status of one or more PURLs. + Options: --purl TEXT PackageURL or PURL. --output FILENAME Write validation output as JSON to FILE. [required] --file FILENAME Read a list of PURLs from a FILE, one per line. --help Show this message and exit. +Examples +######## + +**Submit multiple PURLs using the command line:** + +.. code-block:: none + + purlcli validate --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --output + +*Sample output:* + +.. code-block:: console + + { + "headers": [ + { + "tool_name": "purlcli", + "tool_version": "0.2.0", + "options": { + "command": "validate", + "--purl": [ + "pkg:npm/canonical-path@1.0.0", + "pkg:nginx/nginx@0.8.9" + ], + "--file": null, + "--output": "" + }, + "errors": [], + "warnings": [ + "'check_existence' is not supported for 'pkg:nginx/nginx@0.8.9'" + ] + } + ], + "packages": [ + { + "purl": "pkg:npm/canonical-path@1.0.0", + "valid": true, + "exists": true, + "message": "The provided Package URL is valid, and the package exists in the upstream repo." + }, + { + "purl": "pkg:nginx/nginx@0.8.9", + "valid": true, + "exists": null, + "message": "The provided PackageURL is valid, but `check_existence` is not supported for this package type." + } + ] + } + + +**Submit multiple PURLs using a .txt file:** + +.. code-block:: none + + purlcli validate --file --output + +*Sample input.txt:* + +.. code-block:: console + + pkg:npm/canonical-path@1.0.0 + pkg:nginx/nginx@0.8.9 + + +Notes +####### + +``validate`` calls the ``public.purldb.io/api/validate/`` endpoint. + + +---- + + +'versions' -- collect package versions for a PURL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none -- Collect package versions for a PURL:: - $ purlcli versions --help Usage: purlcli versions [OPTIONS] - + Given one or more PURLs, return a list of all known versions for each PURL. - - Version information is not needed in submitted PURLs and if included will be - removed before processing. - + Options: --purl TEXT PackageURL or PURL. --output FILENAME Write versions output as JSON to FILE. [required] --file FILENAME Read a list of PURLs from a FILE, one per line. --help Show this message and exit. +Examples +######## + +**Submit multiple PURLs using the command line:** + +.. code-block:: none + + purlcli versions --purl pkg:npm/canonical-path --purl pkg:nginx/nginx --output + +*Sample output:* + +.. code-block:: console + + { + "headers": [ + { + "tool_name": "purlcli", + "tool_version": "0.2.0", + "options": { + "command": "versions", + "--purl": [ + "pkg:npm/canonical-path", + "pkg:nginx/nginx" + ], + "--file": null, + "--output": "" + }, + "errors": [], + "warnings": [ + "'pkg:nginx/nginx' not supported with `versions` command" + ] + } + ], + "packages": [ + { + "purl": "pkg:npm/canonical-path@0.0.1", + "version": "0.0.1", + "release_date": "2013-12-19" + }, + { + "purl": "pkg:npm/canonical-path@0.0.2", + "version": "0.0.2", + "release_date": "2013-12-19" + }, + { + "purl": "pkg:npm/canonical-path@1.0.0", + "version": "1.0.0", + "release_date": "2018-10-24" + } + ] + } + -- Collect package metadata for a PURL:: +Notes +####### + +``versions`` calls ``versions()`` from `fetchcode/package_versions.py `__. + +Version information is not needed in submitted PURLs and, if included, will be removed before processing. + + +---- + + +'metadata' -- collect package metadata for a PURL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console $ purlcli metadata --help Usage: purlcli metadata [OPTIONS] - + Given one or more PURLs, for each PURL, return a mapping of metadata fetched from the fetchcode package.py info() function. - + Options: --purl TEXT PackageURL or PURL. --output FILENAME Write meta output as JSON to FILE. [required] --file FILENAME Read a list of PURLs from a FILE, one per line. - --unique Return data only for unique PURLs. --help Show this message and exit. - -- Collect package URLs for a PURL:: +Examples +######## + +**Submit multiple PURLs using the command line:** + +.. code-block:: none + + purlcli metadata --purl pkg:openssl/openssl@3.0.6 --purl pkg:nginx/nginx@0.8.9 --purl pkg:gnu/glibc@2.38 --output + +*Sample output:* + +.. code-block:: console + + { + "headers": [ + { + "tool_name": "purlcli", + "tool_version": "0.2.0", + "options": { + "command": "metadata", + "--purl": [ + "pkg:openssl/openssl@3.0.6", + "pkg:nginx/nginx@0.8.9", + "pkg:gnu/glibc@2.38" + ], + "--file": null, + "--output": "" + }, + "errors": [], + "warnings": [ + "'check_existence' is not supported for 'pkg:openssl/openssl@3.0.6'", + "'pkg:nginx/nginx@0.8.9' not supported with `metadata` command", + "'check_existence' is not supported for 'pkg:gnu/glibc@2.38'" + ] + } + ], + "packages": [ + { + "purl": "pkg:openssl/openssl@3.0.6", + "type": "openssl", + "namespace": null, + "name": "openssl", + "version": "3.0.6", + "qualifiers": {}, + "subpath": null, + "primary_language": "C", + "description": null, + "release_date": "2022-10-11T12:39:09", + "parties": [], + "keywords": [], + "homepage_url": "https://www.openssl.org", + "download_url": "https://github.com/openssl/openssl/archive/refs/tags/openssl-3.0.6.tar.gz", + "api_url": "https://api.github.com/repos/openssl/openssl", + "size": null, + "sha1": null, + "md5": null, + "sha256": null, + "sha512": null, + "bug_tracking_url": "https://github.com/openssl/openssl/issues", + "code_view_url": "https://github.com/openssl/openssl", + "vcs_url": "git://github.com/openssl/openssl.git", + "copyright": null, + "license_expression": null, + "declared_license": "Apache-2.0", + "notice_text": null, + "root_path": null, + "dependencies": [], + "contains_source_code": null, + "source_packages": [], + "repository_homepage_url": null, + "repository_download_url": null, + "api_data_url": null + }, + { + "purl": "pkg:gnu/glibc@2.38", + "type": "gnu", + "namespace": null, + "name": "glibc", + "version": "2.38", + "qualifiers": {}, + "subpath": null, + "primary_language": null, + "description": null, + "release_date": "2023-07-31T17:34:00", + "parties": [], + "keywords": [], + "homepage_url": "https://ftp.gnu.org/pub/gnu/glibc/", + "download_url": "https://ftp.gnu.org/pub/gnu/glibc/glibc-2.38.tar.gz", + "api_url": null, + "size": null, + "sha1": null, + "md5": null, + "sha256": null, + "sha512": null, + "bug_tracking_url": null, + "code_view_url": null, + "vcs_url": null, + "copyright": null, + "license_expression": null, + "declared_license": null, + "notice_text": null, + "root_path": null, + "dependencies": [], + "contains_source_code": null, + "source_packages": [], + "repository_homepage_url": null, + "repository_download_url": null, + "api_data_url": null + } + ] + } + + +Notes +####### + +``metadata`` calls ``info()`` from `fetchcode/package.py `__. + +The intended output for each PURL type supported by the ``metadata`` command is + +- an input PURL with a version: output the metadata for the input version +- an input PURL with no version: output a list of the metadata for all versions + +The output of the various PURL types currently supported in `fetchcode/package.py `__ varies from type to type at the moment -- the underlying functions will be updated as needed so that all produce the intended output for input PURLs with and without a version. + + +---- + + +'urls' -- collect package URLs for a PURL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console $ purlcli urls --help Usage: purlcli urls [OPTIONS] - + Given one or more PURLs, for each PURL, return a list of all known URLs fetched from the packageurl-python purl2url.py code. - + Options: --purl TEXT PackageURL or PURL. --output FILENAME Write urls output as JSON to FILE. [required] --file FILENAME Read a list of PURLs from a FILE, one per line. - --unique Return data only for unique PURLs. --head Validate each URL's existence with a head request. --help Show this message and exit. +Examples +######## + +**Submit multiple PURLs using the command line:** + +.. code-block:: none + + purlcli urls --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --purl pkg:rubygems/rails@7.0.0 --output + +*Sample output:* + +.. code-block:: console + + { + "headers": [ + { + "tool_name": "purlcli", + "tool_version": "0.2.0", + "options": { + "command": "urls", + "--purl": [ + "pkg:npm/canonical-path@1.0.0", + "pkg:nginx/nginx@0.8.9", + "pkg:rubygems/rails@7.0.0" + ], + "--file": null, + "--output": "" + }, + "errors": [], + "warnings": [ + "'pkg:nginx/nginx@0.8.9' not supported with `urls` command", + "'check_existence' is not supported for 'pkg:rubygems/rails@7.0.0'" + ] + } + ], + "packages": [ + { + "purl": "pkg:npm/canonical-path@1.0.0", + "download_url": "http://registry.npmjs.org/canonical-path/-/canonical-path-1.0.0.tgz", + "inferred_urls": [ + "https://www.npmjs.com/package/canonical-path/v/1.0.0", + "http://registry.npmjs.org/canonical-path/-/canonical-path-1.0.0.tgz" + ], + "repository_download_url": null, + "repository_homepage_url": "https://www.npmjs.com/package/canonical-path/v/1.0.0" + }, + { + "purl": "pkg:rubygems/rails@7.0.0", + "download_url": "https://rubygems.org/downloads/rails-7.0.0.gem", + "inferred_urls": [ + "https://rubygems.org/gems/rails/versions/7.0.0", + "https://rubygems.org/downloads/rails-7.0.0.gem" + ], + "repository_download_url": null, + "repository_homepage_url": "https://rubygems.org/gems/rails/versions/7.0.0" + } + ] + } + + +**Include head and get requests:** + +``--head`` + +.. code-block:: none + + purlcli urls --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --purl pkg:rubygems/rails@7.0.0 --output --head + +*Sample output:* + +.. code-block:: console + + { + "headers": [ + { + "tool_name": "purlcli", + "tool_version": "0.2.0", + "options": { + "command": "urls", + "--purl": [ + "pkg:npm/canonical-path@1.0.0", + "pkg:nginx/nginx@0.8.9", + "pkg:rubygems/rails@7.0.0" + ], + "--file": null, + "--head": true, + "--output": "" + }, + "errors": [], + "warnings": [ + "'pkg:nginx/nginx@0.8.9' not supported with `urls` command", + "'check_existence' is not supported for 'pkg:rubygems/rails@7.0.0'" + ] + } + ], + "packages": [ + { + "purl": "pkg:npm/canonical-path@1.0.0", + "download_url": { + "url": "http://registry.npmjs.org/canonical-path/-/canonical-path-1.0.0.tgz", + "get_request_status_code": 200, + "head_request_status_code": 301 + }, + "inferred_urls": [ + { + "url": "https://www.npmjs.com/package/canonical-path/v/1.0.0", + "get_request_status_code": 200, + "head_request_status_code": 200 + }, + { + "url": "http://registry.npmjs.org/canonical-path/-/canonical-path-1.0.0.tgz", + "get_request_status_code": 200, + "head_request_status_code": 301 + } + ], + "repository_download_url": { + "url": null, + "get_request_status_code": "N/A", + "head_request_status_code": "N/A" + }, + "repository_homepage_url": { + "url": "https://www.npmjs.com/package/canonical-path/v/1.0.0", + "get_request_status_code": 200, + "head_request_status_code": 200 + } + }, + { + "purl": "pkg:rubygems/rails@7.0.0", + "download_url": { + "url": "https://rubygems.org/downloads/rails-7.0.0.gem", + "get_request_status_code": 200, + "head_request_status_code": 200 + }, + "inferred_urls": [ + { + "url": "https://rubygems.org/gems/rails/versions/7.0.0", + "get_request_status_code": 200, + "head_request_status_code": 200 + }, + { + "url": "https://rubygems.org/downloads/rails-7.0.0.gem", + "get_request_status_code": 200, + "head_request_status_code": 200 + } + ], + "repository_download_url": { + "url": null, + "get_request_status_code": "N/A", + "head_request_status_code": "N/A" + }, + "repository_homepage_url": { + "url": "https://rubygems.org/gems/rails/versions/7.0.0", + "get_request_status_code": 200, + "head_request_status_code": 200 + } + } + ] + } + + +Notes +####### + +- None atm. + + +Testing +------- + +Run all purldb tests: + +.. code-block:: none + + make test + +Run all purlcli non-live tests (i.e., no live network calls): + +.. code-block:: none + + DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli.py + +Run all purlcli live tests (i.e., check actual API endpoints etc.) + +.. code-block:: none + + DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli_live.py --run_live_fetch + Funding ------- @@ -132,4 +594,3 @@ See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license tex See https://github.com/nexB/purldb for support or download. See https://aboutcode.org for more information about nexB OSS projects. - From e19f5ccd5d51c586c824d461581d764db900c4d7 Mon Sep 17 00:00:00 2001 From: "John M. Horan" Date: Fri, 31 May 2024 13:17:58 -0700 Subject: [PATCH 2/2] Update PURLdb RTD #249 Reference: https://github.com/nexB/purldb/issues/249 Signed-off-by: John M. Horan --- README.rst | 34 ----- docs/source/getting-started/contribute.rst | 4 +- docs/source/how-to-guides/index.rst | 5 +- docs/source/index.rst | 10 ++ docs/source/miscellaneous/funding.rst | 11 ++ docs/source/miscellaneous/index.rst | 9 ++ docs/source/miscellaneous/license.rst | 20 +++ docs/source/miscellaneous/testing.rst | 31 +++++ purldb-toolkit/README.rst | 139 +++++++-------------- 9 files changed, 127 insertions(+), 136 deletions(-) create mode 100644 docs/source/miscellaneous/funding.rst create mode 100644 docs/source/miscellaneous/index.rst create mode 100644 docs/source/miscellaneous/license.rst create mode 100644 docs/source/miscellaneous/testing.rst diff --git a/README.rst b/README.rst index 608ed94c..9db5c8bd 100644 --- a/README.rst +++ b/README.rst @@ -193,37 +193,3 @@ To run PurlDB and Matchcode.io with Docker: docker compose -f docker-compose.yml up -d docker compose -f docker-compose.matchcodeio.yml up -d - -Funding -------- - -This project was funded through the NGI Assure Fund https://nlnet.nl/assure, a -fund established by NLnet https://nlnet.nl/ with financial support from the -European Commission's Next Generation Internet programme, under the aegis of DG -Communications Networks, Content and Technology under grant agreement No 957073. - -This project is also funded through grants from the Google Summer of Code -program, continuing support and sponsoring from nexB Inc. and generous -donations from multiple sponsors. - - -License -------- - -Copyright (c) nexB Inc. and others. All rights reserved. - -purldb is a trademark of nexB Inc. - -SPDX-License-Identifier: Apache-2.0 AND CC-BY-SA-4.0 - -purldb software is licensed under the Apache License version 2.0. - -purldb data is licensed collectively under CC-BY-SA-4.0. - -See https://www.apache.org/licenses/LICENSE-2.0 for the license text. - -See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license text. - -See https://github.com/nexB/purldb for support or download. - -See https://aboutcode.org for more information about nexB OSS projects. diff --git a/docs/source/getting-started/contribute.rst b/docs/source/getting-started/contribute.rst index 1eedd60a..8f79b6e6 100644 --- a/docs/source/getting-started/contribute.rst +++ b/docs/source/getting-started/contribute.rst @@ -1,5 +1,5 @@ -Contirbute -=========== +Contribute +========== Documentation to support code and documentation contributions to purldb. diff --git a/docs/source/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst index 47d33636..96414eb6 100644 --- a/docs/source/how-to-guides/index.rst +++ b/docs/source/how-to-guides/index.rst @@ -2,10 +2,7 @@ How-To-Guides ============= Here are the various how-to guides across various purldb projects to guide you -thourgh specifica use cases: - -- Code matching with Matchcode -- Getting symbols from a package (or a PURL) +through specific use cases: .. toctree:: :maxdepth: 2 diff --git a/docs/source/index.rst b/docs/source/index.rst index 910f1208..927c1b06 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -65,6 +65,16 @@ How-To documents explain how to accomplish specific tasks. ---- +Miscellaneous +------------- + +.. toctree:: + :maxdepth: 2 + + miscellaneous/index + +---- + Indices and tables ================== diff --git a/docs/source/miscellaneous/funding.rst b/docs/source/miscellaneous/funding.rst new file mode 100644 index 00000000..2b269bb5 --- /dev/null +++ b/docs/source/miscellaneous/funding.rst @@ -0,0 +1,11 @@ +Funding +======= + +This project was funded through the NGI Assure Fund https://nlnet.nl/assure, a +fund established by NLnet https://nlnet.nl/ with financial support from the +European Commission's Next Generation Internet programme, under the aegis of DG +Communications Networks, Content and Technology under grant agreement No 957073. + +This project is also funded through grants from the Google Summer of Code +program, continuing support and sponsoring from nexB Inc. and generous +donations from multiple sponsors. diff --git a/docs/source/miscellaneous/index.rst b/docs/source/miscellaneous/index.rst new file mode 100644 index 00000000..b5a22d52 --- /dev/null +++ b/docs/source/miscellaneous/index.rst @@ -0,0 +1,9 @@ +Miscellaneous +============= + +.. toctree:: + :maxdepth: 2 + + testing + funding + license diff --git a/docs/source/miscellaneous/license.rst b/docs/source/miscellaneous/license.rst new file mode 100644 index 00000000..62dd2645 --- /dev/null +++ b/docs/source/miscellaneous/license.rst @@ -0,0 +1,20 @@ +License +======= + +Copyright (c) nexB Inc. and others. All rights reserved. + +purldb is a trademark of nexB Inc. + +SPDX-License-Identifier: Apache-2.0 AND CC-BY-SA-4.0 + +purldb software is licensed under the Apache License version 2.0. + +purldb data is licensed collectively under CC-BY-SA-4.0. + +See https://www.apache.org/licenses/LICENSE-2.0 for the license text. + +See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license text. + +See https://github.com/nexB/purldb for support or download. + +See https://aboutcode.org for more information about nexB OSS projects. diff --git a/docs/source/miscellaneous/testing.rst b/docs/source/miscellaneous/testing.rst new file mode 100644 index 00000000..1d972a6d --- /dev/null +++ b/docs/source/miscellaneous/testing.rst @@ -0,0 +1,31 @@ +Testing +======= + +PURLdb +------ + +Run all PURLdb tests +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + make test + + +purldb-toolkit +-------------- + +Run all purldb-toolkit non-live tests (i.e., no live network calls) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli.py + + +Run all purldb-toolkit live tests (i.e., check actual API endpoints etc.) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli_live.py --run_live_fetch diff --git a/purldb-toolkit/README.rst b/purldb-toolkit/README.rst index 12abfd9b..07ed9bf0 100644 --- a/purldb-toolkit/README.rst +++ b/purldb-toolkit/README.rst @@ -4,46 +4,48 @@ purldb-toolkit .. contents:: :local: :depth: 3 - - -purldb-toolkit is command line utility and library to use the PurlDB, its API and various related libraries. +purldb-toolkit is a command line utility and library to use the PurlDB, its API and various related libraries. The ``purlcli`` command acts as a client to the PurlDB REST API end point(s) to expose PURL services. -It serves both as a tool, as a library and as an example on how to use the services programmatically. +It serves as a tool, a library and an example of how to use the services programmatically. Installation ------------ +.. code-block:: console + pip install purldb-toolkit Usage ----- -Use this command to get basic help:: +Use this command to get basic help: + +.. code-block:: console $ purlcli --help Usage: purlcli [OPTIONS] COMMAND [ARGS]... - Return information from a PURL. + Return information from a PURL. Options: - --help Show this message and exit. + --help Show this message and exit. Commands: - metadata Given one or more PURLs, for each PURL, return a mapping of... - urls Given one or more PURLs, for each PURL, return a list of all... - validate Check the syntax and upstream repo status of one or more PURLs. - versions Given one or more PURLs, return a list of all known versions... + metadata Given one or more PURLs, for each PURL, return a mapping of... + urls Given one or more PURLs, for each PURL, return a list of all... + validate Check the syntax and upstream repo status of one or more PURLs. + versions Given one or more PURLs, return a list of all known versions... And the following subcommands: -'validate' -- validate a PURL +``validate``: validate a PURL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: none +.. code-block:: console $ purlcli validate --help Usage: purlcli validate [OPTIONS] @@ -61,13 +63,13 @@ Examples **Submit multiple PURLs using the command line:** -.. code-block:: none +.. code-block:: console purlcli validate --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --output *Sample output:* -.. code-block:: console +.. code-block:: json { "headers": [ @@ -108,31 +110,33 @@ Examples **Submit multiple PURLs using a .txt file:** -.. code-block:: none +.. code-block:: console purlcli validate --file --output *Sample input.txt:* -.. code-block:: console +.. code-block:: text pkg:npm/canonical-path@1.0.0 pkg:nginx/nginx@0.8.9 -Notes +Details ####### -``validate`` calls the ``public.purldb.io/api/validate/`` endpoint. +``validate`` calls the ``validate/`` endpoint of the `purldb API `_. + +See also https://public.purldb.io/api/docs/#/validate. ---- -'versions' -- collect package versions for a PURL +``versions``: collect package versions for a PURL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: none +.. code-block:: console $ purlcli versions --help Usage: purlcli versions [OPTIONS] @@ -150,13 +154,13 @@ Examples **Submit multiple PURLs using the command line:** -.. code-block:: none +.. code-block:: console purlcli versions --purl pkg:npm/canonical-path --purl pkg:nginx/nginx --output *Sample output:* -.. code-block:: console +.. code-block:: json { "headers": [ @@ -198,10 +202,10 @@ Examples } -Notes +Details ####### -``versions`` calls ``versions()`` from `fetchcode/package_versions.py `__. +``versions`` calls ``versions()`` from `fetchcode/package_versions.py`. Version information is not needed in submitted PURLs and, if included, will be removed before processing. @@ -209,7 +213,7 @@ Version information is not needed in submitted PURLs and, if included, will be r ---- -'metadata' -- collect package metadata for a PURL +``metadata``: collect package metadata for a PURL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console @@ -231,13 +235,13 @@ Examples **Submit multiple PURLs using the command line:** -.. code-block:: none +.. code-block:: console purlcli metadata --purl pkg:openssl/openssl@3.0.6 --purl pkg:nginx/nginx@0.8.9 --purl pkg:gnu/glibc@2.38 --output *Sample output:* -.. code-block:: console +.. code-block:: json { "headers": [ @@ -339,23 +343,23 @@ Examples } -Notes +Details ####### -``metadata`` calls ``info()`` from `fetchcode/package.py `__. +``metadata`` calls ``info()`` from `fetchcode/package.py`. The intended output for each PURL type supported by the ``metadata`` command is - an input PURL with a version: output the metadata for the input version -- an input PURL with no version: output a list of the metadata for all versions +- an input PURL without a version: output a list of the metadata for all versions -The output of the various PURL types currently supported in `fetchcode/package.py `__ varies from type to type at the moment -- the underlying functions will be updated as needed so that all produce the intended output for input PURLs with and without a version. +The output of the various PURL types currently supported in `fetchcode/package.py` varies from type to type at the moment -- the underlying functions will be updated as needed so that all produce the intended output for input PURLs with and without a version. ---- -'urls' -- collect package URLs for a PURL +``urls``: collect package URLs for a PURL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console @@ -378,13 +382,13 @@ Examples **Submit multiple PURLs using the command line:** -.. code-block:: none +.. code-block:: console purlcli urls --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --purl pkg:rubygems/rails@7.0.0 --output *Sample output:* -.. code-block:: console +.. code-block:: json { "headers": [ @@ -437,13 +441,13 @@ Examples ``--head`` -.. code-block:: none +.. code-block:: console purlcli urls --purl pkg:npm/canonical-path@1.0.0 --purl pkg:nginx/nginx@0.8.9 --purl pkg:rubygems/rails@7.0.0 --output --head *Sample output:* -.. code-block:: console +.. code-block:: json { "headers": [ @@ -533,64 +537,7 @@ Examples } -Notes +Details ####### -- None atm. - - -Testing -------- - -Run all purldb tests: - -.. code-block:: none - - make test - -Run all purlcli non-live tests (i.e., no live network calls): - -.. code-block:: none - - DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli.py - -Run all purlcli live tests (i.e., check actual API endpoints etc.) - -.. code-block:: none - - DJANGO_SETTINGS_MODULE=purldb_project.settings pytest -vvs purldb-toolkit/tests/test_purlcli_live.py --run_live_fetch - - -Funding -------- - -This project was funded through the NGI Assure Fund https://nlnet.nl/assure, a -fund established by NLnet https://nlnet.nl/ with financial support from the -European Commission's Next Generation Internet programme, under the aegis of DG -Communications Networks, Content and Technology under grant agreement No 957073. - -This project is also funded through grants from the Google Summer of Code -program, continuing support and sponsoring from nexB Inc. and generous -donations from multiple sponsors. - - -License -------- - -Copyright (c) nexB Inc. and others. All rights reserved. - -purldb is a trademark of nexB Inc. - -SPDX-License-Identifier: Apache-2.0 AND CC-BY-SA-4.0 - -purldb software is licensed under the Apache License version 2.0. - -purldb data is licensed collectively under CC-BY-SA-4.0. - -See https://www.apache.org/licenses/LICENSE-2.0 for the license text. - -See https://creativecommons.org/licenses/by-sa/4.0/legalcode for the license text. - -See https://github.com/nexB/purldb for support or download. - -See https://aboutcode.org for more information about nexB OSS projects. +None atm.