0
# PackageURL Python
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: packageurl-python
7
- **Language**: Python
8
- **Installation**: `pip install packageurl-python`
9

10
## Core Imports
11

12
```python
13
from packageurl import PackageURL
14
```
15

16
Additional components:
17

18
```python
19
from packageurl import normalize, normalize_qualifiers, quote, unquote
20
from packageurl.utils import get_golang_purl
21
from packageurl.contrib.url2purl import url2purl, purl_router
22
from packageurl.contrib.purl2url import get_repo_url, get_download_url
23
```
24

25
## Basic Usage
26

27
```python
28
from packageurl import PackageURL
29

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

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

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

44
# Create with qualifiers
45
purl_with_qualifiers = PackageURL(
46
    type="npm", 
47
    name="lodash", 
48
    version="4.17.21",
49
    qualifiers={"arch": "x64", "os": "linux"}
50
)
51
print(str(purl_with_qualifiers))
52
# pkg:npm/lodash@4.17.21?arch=x64&os=linux
53

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

59
## Architecture
60

61
The library follows a layered architecture:
62

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

68
## Capabilities
69

70
### Core PURL Operations
71

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

74
```python { .api }
75
class PackageURL:
76
    def __init__(self, type=None, namespace=None, name=None, version=None, qualifiers=None, subpath=None): ...
77
    @classmethod
78
    def from_string(cls, purl: str) -> 'PackageURL': ...
79
    def to_string(self, encode=True) -> str: ...
80
    def to_dict(self, encode=False, empty=None) -> dict: ...
81

82
def normalize(type, namespace, name, version, qualifiers, subpath, encode=True): ...
83
def normalize_qualifiers(qualifiers, encode=True): ...
84
```
85

86
[Core Operations](./core-operations.md)
87

88
### Framework Integrations
89

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

92
```python { .api }
93
# Django integration
94
class PackageURLMixin: ...
95
class PackageURLQuerySetMixin: ...
96

97
# SQLAlchemy integration  
98
class PackageURLMixin: ...
99
```
100

101
[Framework Integrations](./framework-integrations.md)
102

103
### URL Conversion Utilities
104

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

107
```python { .api }
108
def url2purl(url): ...
109
def get_repo_url(purl): ...
110
def get_download_url(purl): ...
111
def get_inferred_urls(purl): ...
112
```
113

114
[URL Conversion](./url-conversion.md)
115

116
### Ecosystem-Specific Utilities
117

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

120
```python { .api }
121
def get_golang_purl(go_package: str): ...
122
class Router: ...
123
```
124

125
[Ecosystem Utilities](./ecosystem-utilities.md)
126

127
## Types
128

129
```python { .api }
130
class PackageURL:
131
    """Package URL object representing a standardized package identifier."""
132
    type: str  # Package type (e.g., 'maven', 'npm', 'pypi')
133
    namespace: str | None  # Package namespace/group
134
    name: str  # Package name  
135
    version: str | None  # Package version
136
    qualifiers: dict[str, str]  # Additional qualifiers as key-value pairs
137
    subpath: str | None  # Subpath within package
138
    
139
    SCHEME: str = "pkg"  # PURL scheme constant
140
```