0
# Utility Functions
1

2
Cross-platform utility functions providing essential functionality for file operations, process execution, network requests, and system compatibility checks used throughout nodeenv.
3

4
## Capabilities
5

6
### File System Operations
7

8
Essential file system utilities for directory and file management with proper permissions and cross-platform compatibility.
9

10
```python { .api }
11
def mkdir(path):
12
    """
13
    Create directory with proper permissions.
14
    
15
    Parameters:
16
    path (str): Directory path to create
17
    
18
    Creates directory with appropriate permissions for the platform.
19
    Handles existing directories gracefully and ensures parent
20
    directories are created as needed.
21
    """
22

23
def make_executable(filename):
24
    """
25
    Make file executable on Unix-like systems.
26
    
27
    Parameters:
28
    filename (str): Path to file to make executable
29
    
30
    Sets executable permissions on Unix-like systems (Linux, macOS).
31
    No-op on Windows where executable permissions work differently.
32
    Used for shell scripts and binary files in environments.
33
    """
34

35
def writefile(dest, content, overwrite=True, append=False):
36
    """
37
    Write content to file with options.
38
    
39
    Parameters:
40
    dest (str): Destination file path
41
    content (str): Content to write
42
    overwrite (bool): Whether to overwrite existing files (default: True)
43
    append (bool): Whether to append to existing files (default: False)
44
    
45
    Writes content to file with control over overwrite behavior.
46
    Used for creating activation scripts, configuration files,
47
    and other text files in environments.
48
    
49
    Handles encoding properly and creates parent directories
50
    as needed.
51
    """
52
```
53

54
### Process Execution
55

56
Command execution utilities with logging, error handling, and cross-platform compatibility.
57

58
```python { .api }
59
def callit(cmd, show_stdout=True, in_shell=False, **kwargs):
60
    """
61
    Execute shell command with logging and error handling.
62
    
63
    Parameters:
64
    cmd (str or list): Command to execute
65
    show_stdout (bool): Whether to display command output (default: True)
66
    in_shell (bool): Whether to run command in shell (default: False)
67
    **kwargs: Additional arguments passed to subprocess
68
    
69
    Returns:
70
    int: Command exit code
71
    
72
    Executes commands with comprehensive logging and error handling:
73
    - Command logging with proper argument escaping
74
    - Output capture and display control
75
    - Cross-platform shell execution
76
    - Working directory and environment control
77
    - Timeout support for long-running commands
78
    
79
    Used for Node.js compilation, npm installation, and other
80
    system operations during environment creation.
81
    """
82
```
83

84
### Network Operations
85

86
Network utilities for downloading files and handling HTTP requests with SSL configuration.
87

88
```python { .api }
89
def urlopen(url):
90
    """
91
    Open URL with SSL certificate handling.
92
    
93
    Parameters:
94
    url (str): URL to open
95
    
96
    Returns:
97
    file-like object: Response object for reading data
98
    
99
    Opens HTTP/HTTPS URLs with proper SSL certificate handling:
100
    - Respects global ignore_ssl_certs setting
101
    - Handles SSL certificate validation
102
    - Provides consistent interface across Python versions
103
    - Used for downloading Node.js binaries and source code
104
    """
105
```
106

107
### File Operations
108

109
Enhanced file operation utilities providing additional functionality beyond standard library.
110

111
```python { .api }
112
def copytree(src, dst, symlinks=False, ignore=None):
113
    """
114
    Enhanced directory tree copying with better error handling.
115
    
116
    Parameters:
117
    src (str): Source directory path
118
    dst (str): Destination directory path  
119
    symlinks (bool): Whether to copy symlinks as symlinks (default: False)
120
    ignore (callable): Function to ignore certain files (default: None)
121
    
122
    Enhanced version of shutil.copytree with:
123
    - Better error handling and reporting
124
    - Cross-platform compatibility improvements
125
    - Proper handling of special files and permissions
126
    - Used for copying Node.js installations and directory structures
127
    """
128
```
129

130
### Text Processing
131

132
Text encoding and processing utilities for cross-platform compatibility.
133

134
```python { .api }
135
def to_utf8(text):
136
    """
137
    Convert text to UTF-8 encoding for cross-platform compatibility.
138
    
139
    Parameters:
140
    text (str or bytes): Text to convert
141
    
142
    Returns:
143
    str or bytes: UTF-8 encoded text
144
    
145
    Handles text encoding conversion with fallback strategies:
146
    - Unicode and ASCII text handling
147
    - UTF-8 encoding detection and conversion
148
    - Windows-specific encoding fallbacks (cp1252)
149
    - Graceful handling of encoding errors
150
    
151
    Used for processing text from various sources including
152
    downloads, configuration files, and command output.
153
    """
154
```
155

156
### Output Management
157

158
Terminal output utilities for controlling display and formatting.
159

160
```python { .api }
161
def clear_output(out):
162
    """
163
    Clear terminal output line.
164
    
165
    Parameters:
166
    out (file-like): Output stream to clear
167
    
168
    Clears the current terminal line for progress updates and
169
    dynamic output display. Used for showing download progress
170
    and build status updates.
171
    """
172

173
def remove_env_bin_from_path(env, env_bin_dir):
174
    """
175
    Remove environment bin directory from PATH.
176
    
177
    Parameters:
178
    env (str): PATH environment variable string
179
    env_bin_dir (str): Environment bin directory path
180
    
181
    Returns:
182
    str: Updated PATH string with environment bin directory removed
183
    
184
    Removes the environment's bin directory from PATH variable
185
    to prevent conflicts during environment setup and cleanup.
186
    """
187
```
188

189
### Platform Detection
190

191
System and platform detection utilities for cross-platform compatibility.
192

193
```python { .api }
194
def is_x86_64_musl():
195
    """
196
    Detect x86_64 musl systems (Alpine Linux, etc.).
197
    
198
    Returns:
199
    bool: True if running on x86_64 musl system
200
    
201
    Detects musl-based Linux distributions that require
202
    unofficial Node.js builds for compatibility.
203
    """
204

205
def is_riscv64():
206
    """
207
    Detect RISC-V 64-bit architecture.
208
    
209
    Returns:
210
    bool: True if running on RISC-V 64-bit system
211
    
212
    Detects RISC-V architecture that requires special
213
    Node.js build handling and unofficial builds.
214
    """
215
```
216

217
### Archive Handling
218

219
Enhanced archive extraction utilities with better error handling.
220

221
```python { .api }
222
def tarfile_open(*args, **kwargs):
223
    """
224
    Enhanced tarfile.open with better error handling.
225
    
226
    Parameters:
227
    *args: Arguments passed to tarfile.open
228
    **kwargs: Keyword arguments passed to tarfile.open
229
    
230
    Returns:
231
    tarfile.TarFile: Opened tar file object
232
    
233
    Wrapper around tarfile.open with enhanced error handling:
234
    - Better error messages for corrupted archives
235
    - Handling of incomplete downloads
236
    - Cross-platform compatibility improvements
237
    - Used for extracting Node.js source and binary archives
238
    """
239
```
240

241
## Usage Examples
242

243
### File System Operations
244

245
```python
246
import nodeenv
247

248
# Create directory structure
249
nodeenv.mkdir('/path/to/environment/bin')
250
nodeenv.mkdir('/path/to/environment/lib')
251

252
# Write activation script
253
script_content = """#!/bin/bash
254
export NODE_VIRTUAL_ENV="/path/to/environment"
255
export PATH="$NODE_VIRTUAL_ENV/bin:$PATH"
256
"""
257

258
nodeenv.writefile('/path/to/environment/bin/activate', script_content)
259
nodeenv.make_executable('/path/to/environment/bin/activate')
260
```
261

262
### Process Execution
263

264
```python
265
import nodeenv
266

267
# Execute build command
268
exit_code = nodeenv.callit(['make', '-j4'], show_stdout=True)
269
if exit_code != 0:
270
    print(f"Build failed with exit code: {exit_code}")
271

272
# Execute with custom environment
273
exit_code = nodeenv.callit(
274
    ['npm', 'install', '-g', 'express'],
275
    show_stdout=True,
276
    env={'NODE_PATH': '/path/to/node_modules'}
277
)
278
```
279

280
### Network Operations
281

282
```python
283
import nodeenv
284

285
# Download file with SSL handling
286
try:
287
    response = nodeenv.urlopen('https://nodejs.org/dist/v18.17.0/node-v18.17.0.tar.gz')
288
    data = response.read()
289
    with open('node-source.tar.gz', 'wb') as f:
290
        f.write(data)
291
except Exception as e:
292
    print(f"Download failed: {e}")
293
```
294

295
### Text Processing
296

297
```python
298
import nodeenv
299

300
# Handle text encoding
301
text_data = "Some text with special characters: café, naïve"
302
utf8_text = nodeenv.to_utf8(text_data)
303
print(f"UTF-8 encoded: {utf8_text}")
304
```
305

306
### Platform Detection
307

308
```python
309
import nodeenv
310

311
# Check platform capabilities
312
if nodeenv.is_x86_64_musl():
313
    print("Using unofficial builds for musl system")
314
    
315
if nodeenv.is_riscv64():
316
    print("Using unofficial builds for RISC-V system")
317
    
318
# Use platform flags
319
print(f"Python 3: {nodeenv.is_PY3}")
320
print(f"Windows: {nodeenv.is_WIN}")
321
print(f"Cygwin: {nodeenv.is_CYGWIN}")
322
```