purl-tools - Helpful PackageURL functions

This library serves as a helper for various tasks around Package URL (purl).

Features

• Convert a PURL to ClearlyDefined coordinates
• Find certain metadata about a PURL for some types, e.g. latest available version and source code URL
• Convert a PURL to a URL (using packageurl-python)
• Convert a URL to a PURL (using packageurl-python)

Requirements

• Python 3.10+
• Internet connection for accessing the GitHub API, if a human-readable tag is requested

Installation

Install and run via pipx (Recommended)

pipx makes installing and running Python programs easier and avoids conflicts with other packages. Install it with

pip3 install pipx

The following one-liner both installs and runs this program from PyPI:

pipx run purl-tools

If you want to be able to use purl-tools without prepending it with pipx run every time, install it globally like so:

pipx install purl-tools

purl-tools will then be available in ~/.local/bin, which must be added to your $PATH.

After this, make sure that ~/.local/bin is in your $PATH. On Windows, the required path for your environment may look like %USERPROFILE%\AppData\Roaming\Python\Python310\Scripts, depending on the Python version you have installed.

To upgrade purl-tools to the newest available version, run this command:

pipx upgrade purl-tools

Other installation methods

You may also use pure pip or uv to install this package.

CLI Usage

purl-tools provides multiple commands to facilitate different tasks. Each command is invoked through the purl-tools command-line interface with specific options.

Depending on your exact installation method, this may be one of

# Run via pipx
pipx run purl-tools
# Installation via pipx or pip
purl-tools
# Run via uv
uv run purl-tools

In the following, we will just use purl-tools.

Command Structure

purl-tools <command> [subcommand-options]

Commands

Please run purl-tools --help to get an overview of the commands and global options.

For each command, you can get detailed options, e.g., purl-tools purl2cd --help.

Development and Contribution

We welcome contributions to improve this library. Please read CONTRIBUTING.md for all information.

License

The content of this repository is licensed under the Apache 2.0 license.

There may be components under different, but compatible licenses or from different copyright holders. The project is REUSE compliant which makes these portions transparent. You will find all used licenses in the LICENSES directory.

The project has been started by the OpenRail Association. You are welcome to contribute!