0
# Lockfile Operations
1
2
The Lockfile class provides comprehensive functionality for working with Pipfile.lock files to ensure reproducible dependency resolution. It supports loading existing lockfiles, creating new ones from Pipfiles, accessing locked dependencies, and converting to requirements.txt format.
3
4
## Capabilities
5
6
### Lockfile Loading and Creation
7
8
Load existing lockfiles or create new ones from Pipfiles and raw data.
9
10
```python { .api }
11
class Lockfile:
12
def __init__(self, path=None, projectfile=None, lockfile=None, **kwargs):
13
"""
14
Initialize Lockfile object.
15
16
Parameters:
17
- path: Path to Pipfile.lock
18
- projectfile: ProjectFile instance
19
- lockfile: Internal lockfile object
20
"""
21
22
@classmethod
23
def load(cls, path, create=True):
24
"""
25
Load lockfile from path.
26
27
Parameters:
28
- path: Path to Pipfile.lock
29
- create: Whether to create if not exists
30
31
Returns:
32
Lockfile object
33
"""
34
35
@classmethod
36
def create(cls, path, create=True):
37
"""
38
Create new lockfile.
39
40
Parameters:
41
- path: Path for new lockfile
42
- create: Whether to create if not exists
43
44
Returns:
45
Lockfile object
46
"""
47
48
@classmethod
49
def from_data(cls, path, data, meta_from_project=True):
50
"""
51
Create from data dictionary.
52
53
Parameters:
54
- path: Path for lockfile
55
- data: Lockfile data dictionary
56
- meta_from_project: Use project metadata
57
58
Returns:
59
Lockfile object
60
"""
61
62
@classmethod
63
def lockfile_from_pipfile(cls, pipfile_path):
64
"""
65
Create lockfile from Pipfile.
66
67
Parameters:
68
- pipfile_path: Path to Pipfile
69
70
Returns:
71
Lockfile object
72
"""
73
74
@classmethod
75
def read_projectfile(cls, path):
76
"""
77
Read project file from path.
78
79
Parameters:
80
- path: Path to project file
81
82
Returns:
83
ProjectFile object
84
"""
85
86
@classmethod
87
def load_projectfile(cls, path=None, create=True, data=None):
88
"""
89
Load project file.
90
91
Parameters:
92
- path: Path to project file
93
- create: Whether to create if not exists
94
- data: Project file data
95
96
Returns:
97
ProjectFile object
98
"""
99
```
100
101
### Core Properties
102
103
Access lockfile metadata, paths, and section information.
104
105
```python { .api }
106
class Lockfile:
107
@property
108
def path(self) -> Path:
109
"""Path to lockfile"""
110
111
@property
112
def projectfile(self) -> ProjectFile:
113
"""Project file instance"""
114
115
@property
116
def lockfile(self) -> lockfiles.Lockfile:
117
"""Internal lockfile object"""
118
119
@property
120
def newlines(self) -> str:
121
"""Line ending style"""
122
123
@property
124
def section_keys(self) -> set:
125
"""Available section keys (excluding _meta)"""
126
127
@property
128
def extended_keys(self) -> List:
129
"""Extended section keys"""
130
131
@property
132
def develop(self) -> Dict:
133
"""Development dependencies section"""
134
135
@property
136
def default(self) -> Dict:
137
"""Default dependencies section"""
138
```
139
140
### Dependency Access
141
142
Access locked dependencies and convert them to Requirement objects.
143
144
```python { .api }
145
class Lockfile:
146
def get_requirements(self, dev: bool = True, only: bool = False, categories: Optional[List[str]] = None):
147
"""
148
Get requirements iterator.
149
150
Parameters:
151
- dev: Include development dependencies
152
- only: Only return specified categories
153
- categories: Specific categories to include
154
155
Returns:
156
Iterator[Requirement]: Requirements iterator
157
"""
158
159
def requirements_list(self, category: str):
160
"""
161
Get requirements as list.
162
163
Parameters:
164
- category: Category name ("default" or "develop")
165
166
Returns:
167
List[Dict]: Requirements data list
168
"""
169
170
def get_deps(self, dev=False, only=True):
171
"""
172
Get dependencies dictionary.
173
174
Parameters:
175
- dev: Include development dependencies
176
- only: Only return specified category
177
178
Returns:
179
Dict: Dependencies dictionary
180
"""
181
182
def get_section(self, name: str):
183
"""
184
Get named section.
185
186
Parameters:
187
- name: Section name
188
189
Returns:
190
Optional[Dict]: Section data or None
191
"""
192
```
193
194
### Format Conversion
195
196
Convert lockfile dependencies to requirements.txt format and write lockfiles to disk.
197
198
```python { .api }
199
class Lockfile:
200
def as_requirements(self, category: str, include_hashes=False):
201
"""
202
Format as requirements.txt lines.
203
204
Parameters:
205
- category: Category name ("default" or "develop")
206
- include_hashes: Whether to include package hashes
207
208
Returns:
209
List[str]: Requirements.txt formatted lines
210
"""
211
212
def write(self) -> None:
213
"""Write lockfile to disk."""
214
```
215
216
### Data Access
217
218
Access lockfile data using dictionary-like interface.
219
220
```python { .api }
221
class Lockfile:
222
def get(self, k):
223
"""
224
Get item by key.
225
226
Parameters:
227
- k: Key to retrieve
228
229
Returns:
230
Value for key
231
"""
232
233
def __contains__(self, k):
234
"""
235
Check if key exists.
236
237
Parameters:
238
- k: Key to check
239
240
Returns:
241
bool: True if key exists
242
"""
243
244
def __getitem__(self, k, *args, **kwargs):
245
"""
246
Get item by key using bracket notation.
247
248
Parameters:
249
- k: Key to retrieve
250
251
Returns:
252
Value for key
253
"""
254
255
def __setitem__(self, k, v):
256
"""
257
Set item by key using bracket notation.
258
259
Parameters:
260
- k: Key to set
261
- v: Value to set
262
"""
263
264
def __getattr__(self, k, *args, **kwargs):
265
"""
266
Get attribute by name.
267
268
Parameters:
269
- k: Attribute name
270
271
Returns:
272
Attribute value
273
"""
274
```
275
276
## Usage Examples
277
278
### Loading Lockfiles
279
280
```python
281
from requirementslib import Lockfile
282
283
# Load existing lockfile
284
lockfile = Lockfile.load("./Pipfile.lock")
285
286
# Load lockfile with creation if missing
287
lockfile = Lockfile.load("./Pipfile.lock", create=True)
288
289
# Create lockfile from Pipfile
290
lockfile = Lockfile.lockfile_from_pipfile("./Pipfile")
291
292
# Create from data dictionary
293
lockfile_data = {
294
"default": {
295
"requests": {
296
"version": "==2.25.0",
297
"hashes": ["sha256:..."]
298
}
299
},
300
"develop": {},
301
"_meta": {
302
"requires": {"python_version": "3.8"}
303
}
304
}
305
lockfile = Lockfile.from_data("./Pipfile.lock", lockfile_data)
306
```
307
308
### Accessing Dependencies
309
310
```python
311
from requirementslib import Lockfile
312
313
# Load lockfile
314
lockfile = Lockfile.load("./Pipfile.lock")
315
316
# Get all requirements (production and development)
317
for req in lockfile.get_requirements():
318
print(f"{req.name}: {req.specifiers}")
319
320
# Get only production requirements
321
for req in lockfile.get_requirements(dev=False, only=True):
322
print(f"Production: {req.name} {req.specifiers}")
323
324
# Get only development requirements
325
for req in lockfile.get_requirements(dev=True, only=True):
326
print(f"Development: {req.name} {req.specifiers}")
327
328
# Access raw dependency data
329
default_deps = lockfile.default
330
develop_deps = lockfile.develop
331
332
print("Default dependencies:", default_deps)
333
print("Development dependencies:", develop_deps)
334
```
335
336
### Converting to Requirements.txt
337
338
```python
339
from requirementslib import Lockfile
340
341
# Load lockfile
342
lockfile = Lockfile.load("./Pipfile.lock")
343
344
# Convert production dependencies to requirements.txt format
345
prod_requirements = lockfile.as_requirements("default")
346
for line in prod_requirements:
347
print(line)
348
349
# Convert with hashes for integrity verification
350
prod_requirements_with_hashes = lockfile.as_requirements("default", include_hashes=True)
351
for line in prod_requirements_with_hashes:
352
print(line)
353
354
# Convert development dependencies
355
dev_requirements = lockfile.as_requirements("develop")
356
for line in dev_requirements:
357
print(line)
358
359
# Write to files
360
with open("requirements.txt", "w") as f:
361
f.write("\n".join(lockfile.as_requirements("default")))
362
363
with open("requirements-dev.txt", "w") as f:
364
f.write("\n".join(lockfile.as_requirements("develop")))
365
```
366
367
### Working with Sections
368
369
```python
370
from requirementslib import Lockfile
371
372
# Load lockfile
373
lockfile = Lockfile.load("./Pipfile.lock")
374
375
# Access available sections
376
print("Available sections:", lockfile.section_keys)
377
378
# Get specific section
379
default_section = lockfile.get_section("default")
380
develop_section = lockfile.get_section("develop")
381
382
print("Default section data:", default_section)
383
print("Develop section data:", develop_section)
384
385
# Access metadata
386
if "_meta" in lockfile:
387
meta = lockfile["_meta"]
388
print("Lockfile metadata:", meta)
389
390
if "requires" in meta:
391
python_version = meta["requires"].get("python_version")
392
print(f"Required Python version: {python_version}")
393
```
394
395
### Modifying and Writing Lockfiles
396
397
```python
398
from requirementslib import Lockfile
399
400
# Load lockfile
401
lockfile = Lockfile.load("./Pipfile.lock")
402
403
# Modify lockfile data (if needed)
404
lockfile["default"]["new-package"] = {
405
"version": "==1.0.0",
406
"hashes": ["sha256:abcd1234..."]
407
}
408
409
# Write modified lockfile back to disk
410
lockfile.write()
411
412
# Access requirements after modification
413
for req in lockfile.get_requirements():
414
print(f"Updated lockfile contains: {req.name} {req.specifiers}")
415
```
416
417
### Working with Hashes
418
419
```python
420
from requirementslib import Lockfile
421
422
# Load lockfile
423
lockfile = Lockfile.load("./Pipfile.lock")
424
425
# Check for packages with hashes
426
for req in lockfile.get_requirements():
427
if req.hashes:
428
print(f"{req.name} has {len(req.hashes)} hashes")
429
for hash_val in req.hashes:
430
print(f" {hash_val}")
431
432
# Convert to requirements.txt with hashes for verification
433
requirements_with_hashes = lockfile.as_requirements("default", include_hashes=True)
434
print("Requirements with hashes:")
435
for line in requirements_with_hashes:
436
print(line)
437
```