0
# pip-upgrader
1

2
An interactive command-line tool for upgrading pip requirements files. It automatically detects requirements files, queries PyPI for available updates, presents an interactive interface for selecting packages to upgrade, and updates both the installed packages and version numbers in requirements files.
3

4
## Package Information
5

6
- **Package Name**: pip-upgrader
7
- **Language**: Python
8
- **Installation**: `pip install pip-upgrader`
9
- **Console Command**: `pip-upgrade`
10

11
## Core Imports
12

13
```python
14
import pip_upgrader
15
from pip_upgrader import __version__
16
```
17

18
For programmatic usage:
19

20
```python
21
from pip_upgrader.cli import main, get_options
22
from pip_upgrader.packages_detector import PackagesDetector
23
from pip_upgrader.requirements_detector import RequirementsDetector
24
from pip_upgrader.packages_status_detector import PackagesStatusDetector
25
from pip_upgrader.packages_interactive_selector import PackageInteractiveSelector, user_input
26
from pip_upgrader.packages_upgrader import PackagesUpgrader
27
from pip_upgrader.virtualenv_checker import check_for_virtualenv, is_virtualenv
28
```
29

30
## Basic Usage
31

32
### Command Line Usage
33

34
```bash
35
# Auto-discover requirements files and upgrade interactively
36
pip-upgrade
37

38
# Specify requirements files explicitly
39
pip-upgrade requirements.txt
40
pip-upgrade requirements/dev.txt requirements/production.txt
41

42
# Pre-select specific packages to upgrade
43
pip-upgrade requirements.txt -p django -p celery
44

45
# Upgrade all available packages without prompting
46
pip-upgrade requirements.txt -p all
47

48
# Dry run (simulate without actual changes)
49
pip-upgrade requirements.txt --dry-run
50

51
# Skip virtualenv check
52
pip-upgrade requirements.txt --skip-virtualenv-check
53

54
# Only update requirements files, don't install packages
55
pip-upgrade requirements.txt --skip-package-installation
56

57
# Include prerelease versions
58
pip-upgrade requirements.txt --prerelease
59

60
# Use default PyPI index instead of custom indexes
61
pip-upgrade requirements.txt --use-default-index
62
```
63

64
### Programmatic Usage
65

66
```python
67
from pip_upgrader.cli import main
68
from pip_upgrader.requirements_detector import RequirementsDetector
69
from pip_upgrader.packages_detector import PackagesDetector
70
from pip_upgrader.packages_status_detector import PackagesStatusDetector
71

72
# Auto-detect requirements files
73
detector = RequirementsDetector(None)  # None for auto-detection
74
filenames = detector.get_filenames()
75

76
# Parse packages from requirements files
77
packages_detector = PackagesDetector(filenames)
78
packages = packages_detector.get_packages()
79

80
# Check for available upgrades
81
status_detector = PackagesStatusDetector(packages)
82
options = {'--prerelease': False, '-p': []}
83
packages_status_map = status_detector.detect_available_upgrades(options)
84

85
# Run the complete upgrade process programmatically
86
main()  # Uses command-line arguments
87
```
88

89
## Architecture
90

91
The pip-upgrader follows a modular pipeline architecture with clear separation of concerns:
92

93
1. **Requirements Detection**: Discovers and validates requirements files in the current directory or from explicit paths
94
2. **Package Parsing**: Extracts package names and versions from requirements files, handling various formats and options
95
3. **Status Detection**: Queries PyPI (or custom indexes) to check for available package upgrades
96
4. **Interactive Selection**: Presents upgrade options in a formatted table and handles user input
97
5. **Package Upgrading**: Installs new packages via pip and updates version numbers in requirements files
98
6. **Environment Validation**: Ensures proper virtual environment setup throughout the process
99

100
## Capabilities
101

102
### CLI Interface
103

104
Main command-line interface providing the `pip-upgrade` console command with comprehensive options for interactive and automated requirements file upgrading.
105

106
```python { .api }
107
def main(): ...
108
def get_options(): ...
109
```
110

111
[CLI Interface](./cli-interface.md)
112

113
### Requirements File Detection
114

115
Automatic discovery and validation of requirements files in the current directory, with support for explicit file specification and recursive inclusion handling.
116

117
```python { .api }
118
class RequirementsDetector:
119
    def __init__(self, requirements_arg): ...
120
    def get_filenames(self): ...
121
    def autodetect_files(self): ...
122
```
123

124
[Requirements Detection](./requirements-detection.md)
125

126
### Package Parsing
127

128
Extraction and parsing of package specifications from requirements files, handling various formats including extras, comments, and pip options.
129

130
```python { .api }
131
class PackagesDetector:
132
    def __init__(self, requirements_files): ...
133
    def get_packages(self): ...
134
    def detect_packages(self, requirements_files): ...
135
```
136

137
[Package Parsing](./package-parsing.md)
138

139
### Upgrade Status Detection
140

141
PyPI API integration for checking package upgrade availability, supporting both JSON API and simple HTML formats, with custom index URL handling.
142

143
```python { .api }
144
class PackagesStatusDetector:
145
    def __init__(self, packages, use_default_index=False): ...
146
    def detect_available_upgrades(self, options): ...
147
```
148

149
[Status Detection](./status-detection.md)
150

151
### Interactive Package Selection
152

153
User interface for selecting packages to upgrade, presenting upgrade information in formatted tables with interactive prompts and pre-selection options.
154

155
```python { .api }
156
class PackageInteractiveSelector:
157
    def __init__(self, packages_map, options): ...
158
    def get_packages(self): ...
159
    def ask_for_packages(self): ...
160
```
161

162
[Interactive Selection](./interactive-selection.md)
163

164
### Package Installation and Requirements Updating
165

166
Package installation via pip and atomic updating of version numbers in requirements files, with dry-run support and error handling.
167

168
```python { .api }
169
class PackagesUpgrader:
170
    def __init__(self, selected_packages, requirements_files, options): ...
171
    def do_upgrade(self): ...
172
```
173

174
[Package Upgrading](./package-upgrading.md)
175

176
### Environment Validation
177

178
Virtual environment detection and validation to ensure packages are installed in the appropriate environment.
179

180
```python { .api }
181
def is_virtualenv(): ...
182
def check_for_virtualenv(options): ...
183
```
184

185
[Environment Validation](./environment-validation.md)
186

187
## Types
188

189
```python { .api }
190
# Package status dictionary returned by PackagesStatusDetector
191
PackageStatus = {
192
    'name': str,                    # Package name
193
    'current_version': Version,     # Current version from requirements
194
    'latest_version': Version,      # Latest available version
195
    'upgrade_available': bool,      # Whether upgrade is available
196
    'upload_time': str             # Upload timestamp of latest version
197
}
198

199
# Options dictionary from command-line parsing
200
Options = {
201
    '<requirements_file>': list,    # List of requirements file paths
202
    '--prerelease': bool,           # Include prerelease versions
203
    '-p': list,                     # Pre-selected packages
204
    '--dry-run': bool,              # Simulate without changes
205
    '--skip-virtualenv-check': bool, # Skip environment validation
206
    '--skip-package-installation': bool, # Only update files
207
    '--use-default-index': bool     # Use default PyPI index
208
}
209
```