0
# PUR (pip-update-requirements)
1

2
PUR is a Python library and command-line tool that updates packages in a requirements.txt file to their latest versions. It safely parses requirements files, checks PyPI for latest versions, and updates version constraints while preserving the original file format and comments.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
from pur import update_requirements
14
```
15

16
For CLI usage:
17
```bash
18
pur -r requirements.txt
19
```
20

21
## Basic Usage
22

23
### Command Line Interface
24

25
```bash
26
# Update requirements.txt to latest versions
27
pur -r requirements.txt
28

29
# Interactive mode with prompts for each package
30
pur --interactive
31

32
# Dry run to preview changes without modifying files
33
pur --dry-run
34

35
# Update only specific packages
36
pur --only numpy,pandas
37

38
# Skip certain packages from updates
39
pur --skip tensorflow,torch
40

41
# Limit updates to minor versions only
42
pur --minor "*"
43

44
# Limit updates to patch versions only
45
pur --patch numpy,scipy
46

47
# Allow pre-release versions for specific packages
48
pur --pre "numpy,*"
49

50
# Use custom PyPI index
51
pur --index-url https://pypi.example.com/simple/
52

53
# Output to different file
54
pur -r requirements.txt -o updated-requirements.txt
55
```
56

57
### Programmatic Interface
58

59
```python
60
from pur import update_requirements
61

62
# Basic usage - update requirements.txt
63
updates = update_requirements(input_file='requirements.txt')
64

65
# With specific options
66
updates = update_requirements(
67
    input_file='requirements.txt',
68
    output_file='updated-requirements.txt',
69
    dry_run=True,
70
    skip=['tensorflow'],
71
    only=['numpy', 'pandas']
72
)
73

74
# Process update results
75
for package_name, update_list in updates.items():
76
    for update_info in update_list:
77
        print(f"Package: {update_info['package']}")
78
        print(f"Current: {update_info['current']}")
79
        print(f"Latest: {update_info['latest']}")
80
        print(f"Updated: {update_info['updated']}")
81
        print(f"Message: {update_info['message']}")
82
```
83

84
## Architecture
85

86
PUR operates through a multi-layered architecture:
87

88
- **CLI Layer**: Click-based command-line interface with comprehensive options
89
- **Core Logic**: Requirements file parsing, package discovery, and version resolution
90
- **Pip Integration**: Uses vendored pip internals for requirements file parsing and PyPI queries
91
- **Version Management**: Sophisticated version constraint handling and update policies
92

93
The tool preserves the exact format of requirements files, including comments, spacing, and nested requirements, while safely updating only the version specifications.
94

95
## Capabilities
96

97
### Requirements File Processing
98

99
Core functionality for parsing, analyzing, and updating Python requirements files with full support for pip's requirements file format.
100

101
```python { .api }
102
def update_requirements(
103
    input_file=None,
104
    output_file=None,
105
    force=False,
106
    interactive=False,
107
    skip=[],
108
    only=[],
109
    dry_run=False,
110
    minor=[],
111
    patch=[],
112
    pre=[],
113
    no_recursive=False,
114
    echo=False,
115
    index_urls=[],
116
    cert=None,
117
    no_ssl_verify=False
118
):
119
    """
120
    Update a requirements file to latest package versions.
121
    
122
    Parameters:
123
    - input_file (str, optional): Path to requirements.txt file (default: 'requirements.txt')
124
    - output_file (str, optional): Output file path (default: overwrites input_file)
125
    - force (bool): Update packages without version constraints (default: False)
126
    - interactive (bool): Prompt before each update (default: False)
127
    - skip (list): Package names to skip updating (default: [])
128
    - only (list): Only update these packages, ignore others (default: [])
129
    - dry_run (bool): Preview changes without writing files (default: False)
130
    - minor (list): Packages limited to minor version updates (default: [])
131
    - patch (list): Packages limited to patch version updates (default: [])
132
    - pre (list): Packages allowing pre-release versions (default: [])
133
    - no_recursive (bool): Don't update nested requirements files (default: False)
134
    - echo (bool): Print update messages to stdout (default: False)
135
    - index_urls (list): Custom PyPI index URLs (default: [])
136
    - cert (str, optional): Path to CA certificate bundle (default: None)
137
    - no_ssl_verify (bool): Disable SSL certificate verification (default: False)
138
    
139
    Returns:
140
    dict: Package update information grouped by package name. Each package
141
          maps to a list of update dictionaries containing:
142
          - 'package': Package name
143
          - 'current': Current version string
144
          - 'latest': Latest available version string  
145
          - 'updated': Boolean indicating if package was updated
146
          - 'message': Human-readable update message
147
    """
148
```
149

150
### Command Line Interface
151

152
Complete CLI with extensive options for flexible requirements file updating workflows.
153

154
```python { .api }
155
def pur(**options):
156
    """
157
    Command line entry point for pur CLI tool.
158
    
159
    Command Line Options:
160
    --requirement, -r PATH: Requirements file path (default: requirements.txt)
161
    --output, -o PATH: Output file path (default: overwrites input file)
162
    --interactive: Interactive prompts for each package update
163
    --force, -f: Force update packages without version constraints
164
    --dry-run, -d: Preview changes without writing files
165
    --no-recursive, -n: Skip nested requirements files
166
    --skip TEXT: Comma-separated list of packages to skip
167
    --only TEXT: Comma-separated list of packages to update exclusively
168
    --minor TEXT: Packages limited to minor version updates (use "*" for all)
169
    --patch TEXT: Packages limited to patch version updates (use "*" for all)
170
    --pre TEXT: Packages allowing pre-release versions (use "*" for all)
171
    --index-url TEXT: Custom PyPI index URLs (can be specified multiple times)
172
    --cert PATH: Path to CA certificate bundle
173
    --no-ssl-verify: Disable verifying the server's TLS certificate
174
    --nonzero-exit-code, -z: Use exit codes 10 (up-to-date) or 11 (updated)
175
    --version: Show version and exit
176
    --help: Show help message and exit
177
    
178
    Returns:
179
    None: Exits with status code 0 on success, non-zero on failure
180
    """
181
```
182

183
## Exception Classes
184

185
```python { .api }
186
class StopUpdating(Exception):
187
    """
188
    Exception that may be raised during interactive updates.
189
    
190
    This exception is raised when a user chooses to quit during
191
    interactive mode. It's primarily an internal exception but 
192
    may be encountered when extending pur's functionality.
193
    """
194
```
195

196
## Return Value Structure
197

198
The `update_requirements` function returns a dictionary with the following structure:
199

200
```python
201
{
202
    "package_name": [
203
        {
204
            "package": "package_name",
205
            "current": "1.0.0",  # Current version or "Unknown"
206
            "latest": "2.0.0",   # Latest available version
207
            "updated": True,     # Whether update was applied
208
            "message": "Updated package_name: 1.0.0 -> 2.0.0"
209
        }
210
    ]
211
}
212
```