purl-validator

purl-validator is a Python library for validating Package URLs (PURLs). It works fully offline, including in air-gapped or restricted environments, and answers one key question: Does the package this PURL represents actually exist?

How Does It Work?

purl-validator is shipped with a pre-built FST (Finite State Transducer), a set of compact automata containing latest Package URLs mined by the MineCode¹. Library uses this FST to perform lookups and confirm whether the base PURL² exists.

Currently Supported Ecosystems

• apk
• cargo
• composer
• conan
• cpan
• cran
• debian
• maven
• npm
• nuget
• pypi
• swift

Usage

Add purl-validator to your Python dependencies

pypi install purl-validator

Use it in your code like this:

from purl_validator import PurlValidator

validator = PurlValidator()

PurlValidator.validate_purl("pkg:nuget/FluentValidation")
>>> True

PurlValidator.validate_purl("pkg:nuget/non-existent-foo-bar")
>>> False

The validator accepts a PURL string or a packageurl.PackageURL object:

from packageurl import PackageURL
from purl_validator import PurlValidator

validator = PurlValidator()
purl = PackageURL(type="npm", namespace="@angular", name="core")

exists = validator.validate_purl(purl)
print(exists)

Only the base PURL is used for queries (e.g., oonly package type/namespace/name.) Version, qualifiers, and subpath are not part of the query:

from purl_validator import create_purl_map_entry

assert create_purl_map_entry("pkg:pypi/django@5.0.0") == b"pypi/django"

You can also build and load a custom index for tests or experiments:

from purl_validator import PurlValidator
from purl_validator import create_purl_map

purl_map_location = create_purl_map([
    "pkg:pypi/django",
    "pkg:npm/%40angular/core",
])

validator = PurlValidator(purl_map_location)
assert validator.validate_purl("pkg:pypi/django") is True
assert validator.validate_purl("pkg:pypi/not-a-real-package-name") is False

Use one PurlValidator instance for many lookups. Creating the instance loads the packaged map, while each validation is an exact membership check.

Contribution

We welcome contributions from the community! If you find a bug or have an idea for a new feature, please open an issue on the GitHub repository. If you want to contribute code, you can fork the repository, make your changes, and submit a pull request.

• Please try to write a good commit message, see good commit message wiki.
• Add DCO Sign Off to your commits.

Development Setup

Run these commands, starting from a git clone of https://github.com/aboutcode-org/purl-validator.git

Run tests:

make test

Fix formatting and linting:

make valid

License

SPDX-License-Identifier: Apache-2.0

purl-validator is licensed under Apache License version 2.0.

You may not use this software except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Footnotes

1. MineCode continuously collects package metadata from various package ecosystems to maintain an up-to-date catalog of known packages. ↩

2. A Base Package URL is a Package URL without a version, qualifiers, or subpath. ↩