or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-operations.mdecosystem-utilities.mdframework-integrations.mdindex.mdurl-conversion.md
tile.json

tessl/pypi-packageurl-python

A purl aka. Package URL parser and builder

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/packageurl-python@0.17.x

To install, run

npx @tessl/cli install tessl/pypi-packageurl-python@0.17.0

index.mddocs/

PackageURL Python

A comprehensive Python library for parsing and building Package URLs (PURLs) - standardized identifiers for software packages across different ecosystems. This library provides robust parsing, validation, and construction of PURLs according to the official specification, with additional utilities for framework integration and URL inference.

Package Information

  • Package Name: packageurl-python
  • Language: Python
  • Installation: pip install packageurl-python

Core Imports

from packageurl import PackageURL

Additional components:

from packageurl import normalize, normalize_qualifiers, quote, unquote
from packageurl.utils import get_golang_purl
from packageurl.contrib.url2purl import url2purl, purl_router
from packageurl.contrib.purl2url import get_repo_url, get_download_url

Basic Usage

from packageurl import PackageURL

# Parse a PURL string
purl = PackageURL.from_string("pkg:maven/org.apache.commons/io@1.3.4")
print(purl.to_dict())
# {'type': 'maven', 'namespace': 'org.apache.commons', 'name': 'io', 'version': '1.3.4', 'qualifiers': {}, 'subpath': None}

# Create a PURL object directly
purl = PackageURL(type="pypi", name="django", version="3.2.0")
print(str(purl))
# pkg:pypi/django@3.2.0

# Convert back to string
print(purl.to_string())
# pkg:pypi/django@3.2.0

# Create with qualifiers
purl_with_qualifiers = PackageURL(
    type="npm", 
    name="lodash", 
    version="4.17.21",
    qualifiers={"arch": "x64", "os": "linux"}
)
print(str(purl_with_qualifiers))
# pkg:npm/lodash@4.17.21?arch=x64&os=linux

# Convert to dictionary
print(purl.to_dict())
# {'type': 'pypi', 'namespace': None, 'name': 'django', 'version': '3.2.0', 'qualifiers': {}, 'subpath': None}

Architecture

The library follows a layered architecture:

  • Core PackageURL Class: Main PURL object with parsing, construction, and serialization
  • Normalization Functions: Component-wise validation and normalization
  • Utilities: Helper functions for specific ecosystems (Go, etc.)
  • Contrib Modules: Framework integrations and URL conversion utilities

Capabilities

Core PURL Operations

Essential PackageURL parsing, construction, and manipulation functionality. Includes the main PackageURL class and normalization functions for building and validating package identifiers.

class PackageURL:
    def __init__(self, type=None, namespace=None, name=None, version=None, qualifiers=None, subpath=None): ...
    @classmethod
    def from_string(cls, purl: str) -> 'PackageURL': ...
    def to_string(self, encode=True) -> str: ...
    def to_dict(self, encode=False, empty=None) -> dict: ...

def normalize(type, namespace, name, version, qualifiers, subpath, encode=True): ...
def normalize_qualifiers(qualifiers, encode=True): ...

Core Operations

Framework Integrations

Database model mixins and query utilities for Django and SQLAlchemy frameworks, enabling seamless integration of PackageURL fields into web applications and ORM models.

# Django integration
class PackageURLMixin: ...
class PackageURLQuerySetMixin: ...

# SQLAlchemy integration  
class PackageURLMixin: ...

Framework Integrations

URL Conversion Utilities

Bidirectional conversion between arbitrary URLs and PackageURLs, including repository URL inference and download URL generation for various package ecosystems.

def url2purl(url): ...
def get_repo_url(purl): ...
def get_download_url(purl): ...
def get_inferred_urls(purl): ...

URL Conversion

Ecosystem-Specific Utilities

Helper functions for specific package ecosystems and specialized use cases, including Go module handling and custom routing functionality.

def get_golang_purl(go_package: str): ...
class Router: ...

Ecosystem Utilities

Types

class PackageURL:
    """Package URL object representing a standardized package identifier."""
    type: str  # Package type (e.g., 'maven', 'npm', 'pypi')
    namespace: str | None  # Package namespace/group
    name: str  # Package name  
    version: str | None  # Package version
    qualifiers: dict[str, str]  # Additional qualifiers as key-value pairs
    subpath: str | None  # Subpath within package
    
    SCHEME: str = "pkg"  # PURL scheme constant