Release purldb toolkit

purldb-toolkit/CHANGELOG.rst

@@ -0,0 +1,8 @@
+Changelog
+=========
+
+v0.5.0
+------------
+
+- Initial release
+

purldb-toolkit/CODE_OF_CONDUCT.rst

@@ -0,0 +1,86 @@
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our
+project and our community a harassment-free experience for everyone,
+regardless of age, body size, disability, ethnicity, gender identity and
+expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+-  Using welcoming and inclusive language
+-  Being respectful of differing viewpoints and experiences
+-  Gracefully accepting constructive criticism
+-  Focusing on what is best for the community
+-  Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+-  The use of sexualized language or imagery and unwelcome sexual
+   attention or advances
+-  Trolling, insulting/derogatory comments, and personal or political
+   attacks
+-  Public or private harassment
+-  Publishing others’ private information, such as a physical or
+   electronic address, without explicit permission
+-  Other conduct which could reasonably be considered inappropriate in a
+   professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of
+acceptable behavior and are expected to take appropriate and fair
+corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that they
+deem inappropriate, threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies both within project spaces and in public
+spaces when an individual is representing the project or its community.
+Examples of representing a project or community include using an
+official project e-mail address, posting via an official social media
+account, or acting as an appointed representative at an online or
+offline event. Representation of a project may be further defined and
+clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported by contacting the project team at pombredanne@gmail.com
+or on the Gitter chat channel at https://gitter.im/aboutcode-org/discuss .
+All complaints will be reviewed and investigated and will result in a
+response that is deemed necessary and appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to
+the reporter of an incident. Further details of specific enforcement
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in
+good faith may face temporary or permanent repercussions as determined
+by other members of the project’s leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor Covenant`_ ,
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+.. _Contributor Covenant: https://www.contributor-covenant.org

purldb-toolkit/NOTICE

@@ -0,0 +1,12 @@
+#
+# 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.
+#

purldb-toolkit/README.rst

@@ -1,14 +1,100 @@
 PurlDB toolkit
 ==============
-[To come.]
 
+PurlDB is toolkit and library to use the PurlDB and its API.
+
+The ``purlcli`` command acts as a client to the PurlDB REST API end point(s) to expose various
+PURL services. It serves both as a tool, as a library and as an example on how to use the services
+programmatically.
+
+
 Installation
 ------------
 
-[To come.]
+    pip install purldb-toolkit
 
 
 Usage
 -----
 
-[To come.]
+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.
+      versions  Given one or more PURLs, return a list of all known versions...
+
+
+And the following subcommands:
+
+- Validate a PURL::
+
+    $ purlcli validate --help
+    Usage: purlcli validate [OPTIONS]
+
+      Check the syntax 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.
+
+
+- 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.
+
+
+- Collect package metadata for a PURL::
+
+    $ 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::
+
+    $ 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.