0
# Requirement Processing
1

2
The Requirement class is the core component for parsing, manipulating, and converting individual package requirements. It provides comprehensive support for all types of Python package requirements including named packages, VCS requirements, file/URL requirements, editable installs, environment markers, and package hashes.
3

4
## Capabilities
5

6
### Requirement Creation
7

8
Create Requirement objects from various sources including requirements.txt lines, Pipfile entries, pip InstallRequirement objects, and package metadata.
9

10
```python { .api }
11
class Requirement:
12
    def __init__(self, **kwargs):
13
        """
14
        Initialize requirement from various parameters.
15
        
16
        Parameters:
17
        - name: Package name
18
        - vcs: VCS type (git, hg, svn, bzr)
19
        - req: Internal requirement object
20
        - markers: Environment markers string
21
        - index: Package index name
22
        - editable: Whether package is editable install
23
        - hashes: Set of package hashes
24
        - extras: Package extras tuple
25
        """
26

27
    @classmethod
28
    def from_line(cls, line, parse_setup_info=True):
29
        """
30
        Parse requirement from requirements.txt line.
31
        
32
        Parameters:
33
        - line: Requirements.txt line string
34
        - parse_setup_info: Whether to parse setup.py information
35
        
36
        Returns:
37
        Requirement object
38
        """
39

40
    @classmethod
41
    def from_ireq(cls, ireq):
42
        """
43
        Create from pip InstallRequirement object.
44
        
45
        Parameters:
46
        - ireq: pip InstallRequirement instance
47
        
48
        Returns:
49
        Requirement object
50
        """
51

52
    @classmethod  
53
    def from_metadata(cls, name, version, extras, markers):
54
        """
55
        Create from metadata components.
56
        
57
        Parameters:
58
        - name: Package name
59
        - version: Version string
60
        - extras: Package extras
61
        - markers: Environment markers
62
        
63
        Returns:
64
        Requirement object
65
        """
66

67
    @classmethod
68
    def from_pipfile(cls, name, pipfile):
69
        """
70
        Create from Pipfile entry.
71
        
72
        Parameters:
73
        - name: Package name
74
        - pipfile: Pipfile entry data
75
        
76
        Returns:
77
        Requirement object
78
        """
79
```
80

81
### Core Fields
82

83
Pydantic fields that store requirement metadata and configuration.
84

85
```python { .api }
86
class Requirement:
87
    name: Optional[str]
88
        """Package name"""
89
    
90
    vcs: Optional[str] 
91
        """VCS type if VCS requirement"""
92
    
93
    req: Optional[Any]
94
        """Internal requirement object"""
95
    
96
    markers: Optional[str]
97
        """Environment markers string"""
98
    
99
    index: Optional[str]
100
        """Package index name"""
101
    
102
    editable: Optional[bool]
103
        """Whether package is editable install"""
104
    
105
    hashes: Set[str]
106
        """Set of package hashes"""
107
    
108
    extras: Tuple[str, ...]
109
        """Package extras tuple"""
110
```
111

112
### Computed Properties
113

114
Cached properties that compute derived information from the requirement fields.
115

116
```python { .api }
117
class Requirement:
118
    @property
119
    def requirement(self):
120
        """Packaging requirement object"""
121
    
122
    @property
123
    def normalized_name(self) -> str:
124
        """Canonicalized package name"""
125
    
126
    @property
127
    def specifiers(self):
128
        """Version specifiers string"""
129
    
130
    @property
131
    def extras_as_pip(self) -> str:
132
        """Formatted extras string for pip"""
133
    
134
    @property
135
    def get_specifiers(self) -> str:
136
        """Version specifiers string"""
137
    
138
    @property
139
    def get_markers(self):
140
        """Parsed environment markers"""
141
    
142
    @property
143
    def get_specifier(self):
144
        """Parsed specifier object"""
145
    
146
    @property
147
    def get_version(self):
148
        """Parsed version object"""
149
    
150
    @property
151
    def line_instance(self):
152
        """Line instance for this requirement"""
153
    
154
    @property  
155
    def ireq(self):
156
        """InstallRequirement object"""
157
    
158
    @property
159
    def is_vcs(self) -> bool:
160
        """Whether this is a VCS requirement"""
161
    
162
    @property
163
    def is_file_or_url(self) -> bool:
164
        """Whether this is file/URL requirement"""
165
    
166
    @property
167
    def is_named(self) -> bool:
168
        """Whether this is a named requirement"""
169
    
170
    @property
171
    def is_wheel(self) -> bool:
172
        """Whether this is a wheel file"""
173
    
174
    @property
175
    def is_direct_url(self) -> bool:
176
        """Whether this uses direct URL format"""
177
    
178
    @property
179
    def hashes_as_pip(self) -> str:
180
        """Formatted hashes string for pip"""
181
    
182
    @property
183
    def commit_hash(self) -> Optional[str]:
184
        """VCS commit hash if applicable"""
185
    
186
    @property
187
    def constraint_line(self) -> str:
188
        """Formatted constraint line"""
189
    
190
    @property
191
    def pipfile_entry(self) -> Tuple[str, Any]:
192
        """Pipfile format entry"""
193
```
194

195
### Format Conversion
196

197
Convert requirements between different formats while preserving all metadata.
198

199
```python { .api }
200
class Requirement:
201
    def as_line(self, sources=None, include_hashes=True, include_extras=True, include_markers=True, as_list=False):
202
        """
203
        Format as requirements.txt line.
204
        
205
        Parameters:
206
        - sources: Package sources for index URLs
207
        - include_hashes: Whether to include package hashes
208
        - include_extras: Whether to include package extras
209
        - include_markers: Whether to include environment markers
210
        - as_list: Return as list instead of string
211
        
212
        Returns:
213
        Requirements.txt formatted string or list
214
        """
215

216
    def as_pipfile(self):
217
        """
218
        Format as Pipfile entry.
219
        
220
        Returns:
221
        Dict containing Pipfile entry data
222
        """
223

224
    def as_ireq(self):
225
        """
226
        Convert to pip InstallRequirement.
227
        
228
        Returns:
229
        pip InstallRequirement object
230
        """
231

232
    def get_requirement(self):
233
        """
234
        Get packaging requirement object.
235
        
236
        Returns:
237
        packaging.requirements.Requirement object
238
        """
239
```
240

241
### Hash Management
242

243
Add and format package hashes for integrity verification.
244

245
```python { .api }
246
class Requirement:
247
    def add_hashes(self, hashes: set):
248
        """
249
        Add hash values to requirement (modifies in place).
250
        
251
        Parameters:
252
        - hashes: Set of hash strings
253
        """
254

255
    def get_hashes_as_pip(self, as_list: bool = False):
256
        """
257
        Format hashes for pip.
258
        
259
        Parameters:
260
        - as_list: Return as list instead of string
261
        
262
        Returns:
263
        Formatted hashes string or list
264
        """
265
```
266

267
### Advanced Operations
268

269
Advanced functionality for working with requirement metadata and dependencies.
270

271
```python { .api }
272
class Requirement:
273
    def update_name_from_path(self, path: str) -> None:
274
        """
275
        Update name from filesystem path.
276
        
277
        Parameters:
278
        - path: Filesystem path to package
279
        """
280

281
    def get_line_instance(self):
282
        """
283
        Get Line instance for this requirement.
284
        
285
        Returns:
286
        Line object
287
        """
288

289
    def get_version_from_setup_info(self):
290
        """
291
        Extract version from setup information.
292
        
293
        Returns:
294
        Tuple of (version_string, is_dynamic)
295
        """
296

297
    def run_requires(self, sources=None, finder=None):
298
        """
299
        Get requirement dependencies.
300
        
301
        Parameters:
302
        - sources: Package sources
303
        - finder: Package finder instance
304
        
305
        Returns:
306
        Dict containing dependency information
307
        """
308

309
    def merge_markers(self, markers):
310
        """
311
        Merge environment markers.
312
        
313
        Parameters:
314
        - markers: Additional markers to merge
315
        
316
        Returns:
317
        New Requirement object with merged markers
318
        """
319
```
320

321
## Usage Examples
322

323
### Basic Requirement Parsing
324

325
```python
326
from requirementslib import Requirement
327

328
# Parse simple named requirement
329
req = Requirement.from_line("requests>=2.25.0")
330
print(req.name)           # "requests"
331
print(req.specifiers)     # ">=2.25.0"
332

333
# Parse requirement with extras and markers
334
req = Requirement.from_line("requests[security]>=2.25.0; python_version>='3.6'")
335
print(req.extras)         # ("security",)
336
print(req.markers)        # "python_version>='3.6'"
337

338
# Parse VCS requirement
339
req = Requirement.from_line("git+https://github.com/requests/requests.git@v2.25.0#egg=requests")
340
print(req.is_vcs)         # True
341
print(req.vcs)            # "git"
342
print(req.commit_hash)    # "v2.25.0"
343

344
# Parse editable requirement
345
req = Requirement.from_line("-e ./local-package")
346
print(req.editable)       # True
347
```
348

349
### Format Conversion
350

351
```python
352
from requirementslib import Requirement
353

354
# Create requirement and convert between formats
355
req = Requirement.from_line("requests[security]>=2.25.0")
356

357
# Convert to Pipfile format
358
pipfile_entry = req.as_pipfile()
359
# {"requests": {"version": ">=2.25.0", "extras": ["security"]}}
360

361
# Convert back to requirements.txt format
362
line = req.as_line()
363
# "requests[security]>=2.25.0"
364

365
# Convert to pip InstallRequirement
366
ireq = req.as_ireq()
367
print(type(ireq).__name__)  # "InstallRequirement"
368
```
369

370
### Hash Management
371

372
```python
373
from requirementslib import Requirement
374

375
# Create requirement and add hashes
376
req = Requirement.from_line("requests==2.25.0")
377
hashes = {
378
    "sha256:e786e8c8b9b5e9c8f1d6a9b8c7d6e5f4a3b2c1d0e9f8g7h6i5j4k3l2m1n0",
379
    "sha256:f9f8e7d6c5b4a3b2c1d0e9f8g7h6i5j4k3l2m1n0e786e8c8b9b5e9c8f1d6"
380
}
381

382
# Add hashes (modifies req in place)
383
req.add_hashes(hashes)
384

385
# Format with hashes for pip
386
line_with_hashes = req.as_line()
387
print(line_with_hashes)
388
# "requests==2.25.0 --hash=sha256:e786e8c8b9b5e9c8f1d6a9b8c7d6e5f4a3b2c1d0e9f8g7h6i5j4k3l2m1n0 --hash=sha256:f9f8e7d6c5b4a3b2c1d0e9f8g7h6i5j4k3l2m1n0e786e8c8b9b5e9c8f1d6"
389
```