0
# File Operations
1

2
Comprehensive file and directory manipulation functions for environment setup, including copying, linking, and permission management with cross-platform compatibility.
3

4
## Capabilities
5

6
### Directory Operations
7

8
Functions for creating and removing directories with proper error handling and cross-platform support.
9

10
```python { .api }
11
def mkdir(at_path):
12
    """
13
    Create directory if it doesn't exist.
14
    
15
    Creates directory and any necessary parent directories. No-op if
16
    directory already exists. Handles permission errors gracefully.
17
    
18
    Parameters:  
19
    - at_path (str): Directory path to create
20
    
21
    Returns:
22
    None
23
    
24
    Raises:
25
    OSError: If directory creation fails due to permissions or other system error
26
    """
27

28
def rm_tree(folder):
29
    """
30
    Remove directory tree recursively.
31
    
32
    Removes directory and all contents recursively. Handles read-only files
33
    and permission issues by attempting to make files writable before deletion.
34
    Safe to call on non-existent directories.
35
    
36
    Parameters:
37
    - folder (str): Directory path to remove
38
    
39
    Returns:
40
    None
41
    
42
    Raises:
43
    OSError: If directory removal fails after permission adjustments
44
    """
45
```
46

47
**Usage Examples:**
48

49
```python
50
import virtualenv
51

52
# Create directory structure
53
virtualenv.mkdir('/path/to/new/directory')
54
virtualenv.mkdir('/path/to/nested/directory/structure')
55

56
# Remove directory tree
57
virtualenv.rm_tree('/path/to/unwanted/directory')
58
```
59

60
### File Copying and Linking
61

62
Functions for copying files and directories with support for symbolic linking and cross-platform compatibility.
63

64
```python { .api }
65
def copy_file_or_folder(src, dest, symlink=True):
66
    """
67
    Copy file or folder with symlink support.
68
    
69
    Copies files or directories from source to destination. Uses symbolic
70
    links when possible and supported by platform. Handles both files and
71
    directories recursively.
72
    
73
    Parameters:
74
    - src (str): Source file or directory path
75
    - dest (str): Destination file or directory path  
76
    - symlink (bool): Use symbolic links when possible instead of copying
77
    
78
    Returns:
79
    None
80
    
81
    Raises:
82
    OSError: If source doesn't exist or copy operation fails
83
    """
84

85
def copyfile(src, dest, symlink=True):
86
    """
87
    Copy a single file with symlink support.
88
    
89
    Copies individual file from source to destination. Creates symbolic
90
    link when possible and requested. Preserves file permissions and
91
    timestamps when copying.
92
    
93
    Parameters:
94
    - src (str): Source file path
95
    - dest (str): Destination file path
96
    - symlink (bool): Create symbolic link instead of copying if possible
97
    
98
    Returns:
99
    None
100
    
101
    Raises:
102
    OSError: If source file doesn't exist or copy fails
103
    IOError: If destination cannot be written
104
    """
105
```
106

107
**Usage Examples:**
108

109
```python
110
import virtualenv
111

112
# Copy file with automatic symlink detection
113
virtualenv.copyfile('/usr/bin/python3', '/path/to/env/bin/python')
114

115
# Copy directory tree
116
virtualenv.copy_file_or_folder('/usr/lib/python3.8', '/path/to/env/lib/python3.8')
117

118
# Force copying instead of symlinking
119
virtualenv.copyfile('/etc/hosts', '/path/to/backup/hosts', symlink=False)
120
```
121

122
### File Writing and Permissions
123

124
Functions for writing content to files and managing file permissions.
125

126
```python { .api }
127
def writefile(dest, content, overwrite=True):
128
    """
129
    Write content to a file.
130
    
131
    Writes string or bytes content to specified file path. Creates parent
132
    directories if they don't exist. Handles text encoding appropriately.
133
    
134
    Parameters:
135
    - dest (str): Destination file path
136
    - content (str/bytes): Content to write to file
137
    - overwrite (bool): Whether to overwrite existing files
138
    
139
    Returns:
140
    None
141
    
142
    Raises:
143
    OSError: If file cannot be created or written
144
    IOError: If file already exists and overwrite=False
145
    """
146

147
def make_exe(fn):
148
    """
149
    Make a file executable.
150
    
151
    Sets executable permissions on file for owner, group, and others
152
    as appropriate for the platform. On Windows, ensures file has
153
    appropriate extension or is marked executable.
154
    
155
    Parameters:
156
    - fn (str): File path to make executable
157
    
158
    Returns:
159
    None
160
    
161
    Raises:
162
    OSError: If file doesn't exist or permission change fails
163
    """
164
```
165

166
**Usage Examples:**
167

168
```python
169
import virtualenv
170

171
# Write activation script
172
script_content = "#!/bin/bash\nexport PATH=/path/to/env/bin:$PATH"
173
virtualenv.writefile('/path/to/env/bin/activate', script_content)
174

175
# Make script executable
176
virtualenv.make_exe('/path/to/env/bin/activate')
177

178
# Write without overwriting existing file
179
virtualenv.writefile('/path/to/config.ini', 'key=value', overwrite=False)
180
```
181

182
### Specialized Copy Operations
183

184
Functions for copying specific types of files and directories required for virtual environment setup.
185

186
```python { .api }
187
def copy_required_modules(dst_prefix, symlink):
188
    """
189
    Copy required Python modules to virtual environment.
190
    
191
    Copies essential Python standard library modules that are needed
192
    for virtual environment functionality. Handles platform-specific
193
    module requirements and dependencies.
194
    
195
    Parameters:
196
    - dst_prefix (str): Destination prefix path for virtual environment
197
    - symlink (bool): Use symbolic links when possible
198
    
199
    Returns:
200
    None
201
    
202
    Raises:
203
    OSError: If required modules cannot be found or copied
204
    """
205

206
def copy_required_files(src_dir, lib_dir, symlink):
207
    """
208
    Copy required files for virtual environment.
209
    
210
    Copies platform-specific files needed for Python environment
211
    functionality including shared libraries, configuration files,
212
    and platform-specific resources.
213
    
214
    Parameters:
215
    - src_dir (str): Source directory containing Python installation
216
    - lib_dir (str): Target library directory in virtual environment
217
    - symlink (bool): Use symbolic links when possible
218
    
219
    Returns:
220
    None
221
    
222
    Raises:
223
    OSError: If required files cannot be copied
224
    """
225

226
def copy_include_dir(include_src, include_dest, symlink):
227
    """
228
    Copy Python include directory for C extension compilation.
229
    
230
    Copies Python header files needed for compiling C extensions
231
    in the virtual environment. Essential for packages that include
232
    native code components.
233
    
234
    Parameters:
235
    - include_src (str): Source include directory
236
    - include_dest (str): Destination include directory
237
    - symlink (bool): Use symbolic links when possible  
238
    
239
    Returns:
240
    None
241
    
242
    Raises:
243
    OSError: If include directory cannot be copied
244
    """
245
```
246

247
**Usage Examples:**
248

249
```python
250
import virtualenv
251

252
# Copy required modules during environment setup
253
virtualenv.copy_required_modules('/path/to/env', symlink=True)
254

255
# Copy required files from Python installation
256
virtualenv.copy_required_files('/usr/lib/python3.8', '/path/to/env/lib', True)
257

258
# Copy include directory for C extensions
259
virtualenv.copy_include_dir('/usr/include/python3.8', '/path/to/env/include', True)
260
```
261

262
### File System Fixes and Adjustments
263

264
Functions for adjusting file system layout and fixing common virtual environment issues.
265

266
```python { .api }
267
def fix_local_scheme(home_dir, symlink=True):
268
    """
269
    Fix local installation scheme for virtual environment.
270
    
271
    Adjusts Python installation scheme to work properly in virtual
272
    environment context. Handles platform-specific path adjustments
273
    and ensures proper package installation behavior.
274
    
275
    Parameters:
276
    - home_dir (str): Virtual environment home directory
277
    - symlink (bool): Use symbolic links when adjusting paths
278
    
279
    Returns:
280
    None
281
    
282
    Raises:
283
    OSError: If scheme adjustments cannot be applied
284
    """
285

286
def fix_lib64(lib_dir, symlink=True):
287
    """
288
    Fix lib64 directory issues on 64-bit systems.
289
    
290
    Creates or adjusts lib64 symbolic link to lib directory on systems
291
    that expect lib64 for 64-bit libraries. Common requirement on
292
    Linux systems for proper library discovery.
293
    
294
    Parameters:
295
    - lib_dir (str): Library directory path in virtual environment
296
    - symlink (bool): Create symbolic link (vs. copy) for lib64
297
    
298
    Returns:
299
    None
300
    
301
    Raises:
302
    OSError: If lib64 link cannot be created
303
    """
304

305
def fixup_pth_and_egg_link(home_dir, sys_path=None):
306
    """
307
    Fix .pth and .egg-link files for virtual environment.
308
    
309
    Adjusts path files (.pth) and egg-link files to use correct paths
310
    for virtual environment. Essential for proper package discovery
311
    and import behavior in isolated environments.
312
    
313
    Parameters:
314
    - home_dir (str): Virtual environment home directory
315
    - sys_path (list, optional): Python sys.path for path resolution
316
    
317
    Returns:
318
    None
319
    
320
    Raises:
321
    OSError: If path files cannot be fixed
322
    """
323
```
324

325
**Usage Examples:**
326

327
```python
328
import virtualenv
329
import sys
330

331
# Fix installation scheme
332
virtualenv.fix_local_scheme('/path/to/env')
333

334
# Fix lib64 on 64-bit systems  
335
virtualenv.fix_lib64('/path/to/env/lib')
336

337
# Fix path files with custom sys.path
338
virtualenv.fixup_pth_and_egg_link('/path/to/env', sys_path=sys.path)
339
```
340

341
### Script and Configuration Management
342

343
Functions for managing activation scripts and configuration files within virtual environments.
344

345
```python { .api }
346
def fixup_scripts(_, bin_dir):
347
    """
348
    Fix script shebangs and paths in virtual environment.
349
    
350
    Updates shebang lines in executable scripts to point to virtual
351
    environment Python interpreter. Ensures scripts use isolated
352
    environment rather than system Python.
353
    
354
    Parameters:
355
    - _ (unused): Legacy parameter, ignored
356
    - bin_dir (str): Binary directory containing scripts to fix
357
    
358
    Returns:
359
    None
360
    
361
    Raises:
362
    OSError: If scripts cannot be read or modified
363
    """
364

365
def relative_script(lines):
366
    """
367
    Convert script to use relative paths.
368
    
369
    Modifies script lines to use relative paths instead of absolute
370
    paths, making scripts relocatable with their virtual environment.
371
    
372
    Parameters:
373
    - lines (list): List of script lines to modify
374
    
375
    Returns:
376
    list: Modified script lines with relative paths
377
    """
378
```
379

380
**Usage Examples:**
381

382
```python
383
import virtualenv
384

385
# Fix scripts in virtual environment
386
virtualenv.fixup_scripts(None, '/path/to/env/bin')
387

388
# Make script relocatable
389
with open('/path/to/script.py', 'r') as f:
390
    lines = f.readlines()
391
    
392
relative_lines = virtualenv.relative_script(lines)
393

394
with open('/path/to/script.py', 'w') as f:
395
    f.writelines(relative_lines)
396
```