0
# File System Utilities
1

2
Cross-platform file path handling, normalization, and client-server path translation for remote debugging scenarios. These utilities ensure consistent file path handling across different operating systems and enable proper source file mapping between debugger client and server environments.
3

4
## Capabilities
5

6
### Path Normalization
7

8
Functions for normalizing and canonicalizing file paths across different platforms and debugging environments.
9

10
```python { .api }
11
def canonical_normalized_path(filename):
12
    """
13
    Get canonical normalized absolute path for cross-platform compatibility.
14
    
15
    Parameters:
16
    - filename (str): File path to normalize
17
    
18
    Returns:
19
    str: Canonical normalized absolute path
20
    """
21

22
def absolute_path(filename):
23
    """
24
    Convert relative path to absolute path.
25
    
26
    Parameters:
27
    - filename (str): File path to convert
28
    
29
    Returns:
30
    str: Absolute file path
31
    """
32

33
def normcase(s):
34
    """
35
    Normalize file path case for cross-platform compatibility.
36
    
37
    Parameters:
38
    - s (str): Path string to normalize
39
    
40
    Returns:
41
    str: Normalized path string
42
    """
43
```
44

45
### Path Information
46

47
Functions for extracting information from file paths and checking file existence.
48

49
```python { .api }
50
def basename(filename):
51
    """
52
    Extract basename from file path.
53
    
54
    Parameters:
55
    - filename (str): File path
56
    
57
    Returns:
58
    str: Base filename
59
    """
60

61
def exists(filename):
62
    """
63
    Check if file exists.
64
    
65
    Parameters:
66
    - filename (str): File path to check
67
    
68
    Returns:
69
    bool: True if file exists, False otherwise
70
    """
71
```
72

73
### Remote Debugging Path Translation
74

75
Functions for handling path translation between debugger client and server in remote debugging scenarios.
76

77
```python { .api }
78
def get_client_filename_source_reference(client_filename):
79
    """
80
    Get source reference identifier for client-side filename.
81
    
82
    Parameters:
83
    - client_filename (str): Client-side file path
84
    
85
    Returns:
86
    str: Source reference identifier
87
    """
88

89
def get_server_filename_from_source_reference(source_reference):
90
    """
91
    Get server filename from source reference identifier.
92
    
93
    Parameters:
94
    - source_reference (str): Source reference identifier
95
    
96
    Returns:
97
    str: Server-side file path
98
    """
99
```
100

101
### Configuration
102

103
Functions for configuring file system behavior in the debugger.
104

105
```python { .api }
106
def set_resolve_symlinks(resolve_symlinks):
107
    """
108
    Configure whether to resolve symbolic links in file paths.
109
    
110
    Parameters:
111
    - resolve_symlinks (bool): Whether to resolve symlinks
112
    
113
    Returns:
114
    None
115
    """
116
```
117

118
## Constants
119

120
```python { .api }
121
# Debug flag for path translation operations
122
DEBUG_CLIENT_SERVER_TRANSLATION: bool
123

124
# Cache container for normalized paths
125
NORM_PATHS_CONTAINER: dict
126
```
127

128
## Usage Examples
129

130
### Basic Path Operations
131

132
```python
133
import pydevd_file_utils
134

135
# Normalize paths for cross-platform compatibility
136
linux_path = "/home/user/project/src/main.py"
137
windows_path = "C:\\Users\\user\\project\\src\\main.py"
138

139
normalized_linux = pydevd_file_utils.canonical_normalized_path(linux_path)
140
normalized_windows = pydevd_file_utils.canonical_normalized_path(windows_path)
141

142
print(f"Normalized Linux: {normalized_linux}")
143
print(f"Normalized Windows: {normalized_windows}")
144

145
# Check file existence
146
if pydevd_file_utils.exists(normalized_linux):
147
    print(f"File exists: {pydevd_file_utils.basename(normalized_linux)}")
148
```
149

150
### Remote Debugging Path Mapping
151

152
```python
153
import pydevd_file_utils
154

155
# Configure symlink resolution
156
pydevd_file_utils.set_resolve_symlinks(True)
157

158
# Client-side path (e.g., in IDE)
159
client_path = "/local/workspace/myproject/app.py"
160

161
# Get source reference for remote debugging
162
source_ref = pydevd_file_utils.get_client_filename_source_reference(client_path)
163
print(f"Source reference: {source_ref}")
164

165
# On server side, get server path from reference
166
server_path = pydevd_file_utils.get_server_filename_from_source_reference(source_ref)
167
print(f"Server path: {server_path}")
168
```
169

170
### Cross-Platform Path Handling
171

172
```python
173
import pydevd_file_utils
174
import os
175

176
# Handle different path formats
177
paths = [
178
    "relative/path/to/file.py",
179
    "/absolute/unix/path.py",
180
    "C:\\Windows\\path\\file.py",
181
    "./current/dir/file.py",
182
    "../parent/dir/file.py"
183
]
184

185
for path in paths:
186
    # Normalize case (important on Windows)
187
    normalized_case = pydevd_file_utils.normcase(path)
188
    
189
    # Get absolute path
190
    abs_path = pydevd_file_utils.absolute_path(path)
191
    
192
    # Get canonical normalized path
193
    canonical = pydevd_file_utils.canonical_normalized_path(path)
194
    
195
    print(f"Original: {path}")
196
    print(f"Normalized case: {normalized_case}")
197
    print(f"Absolute: {abs_path}")
198
    print(f"Canonical: {canonical}")
199
    print(f"Basename: {pydevd_file_utils.basename(canonical)}")
200
    print(f"Exists: {pydevd_file_utils.exists(canonical)}")
201
    print("---")
202
```
203

204
### Debugging Path Translation Issues
205

206
```python
207
import pydevd_file_utils
208

209
# Enable debug mode for path translation
210
pydevd_file_utils.DEBUG_CLIENT_SERVER_TRANSLATION = True
211

212
# Example of debugging path mapping issues
213
client_file = "/workspace/project/src/module.py"
214
server_file = "/app/src/module.py"
215

216
# Get source reference
217
ref = pydevd_file_utils.get_client_filename_source_reference(client_file)
218

219
# This will show debug output if translation issues occur
220
mapped_server = pydevd_file_utils.get_server_filename_from_source_reference(ref)
221

222
print(f"Client: {client_file}")
223
print(f"Reference: {ref}")
224
print(f"Mapped server: {mapped_server}")
225

226
# Check cache contents
227
print(f"Path cache size: {len(pydevd_file_utils.NORM_PATHS_CONTAINER)}")
228
```
229

230
## Implementation Notes
231

232
- **Cross-Platform Compatibility**: All functions handle Windows, Linux, and macOS path formats
233
- **Caching**: Normalized paths are cached for performance in `NORM_PATHS_CONTAINER`
234
- **Remote Debugging**: Path translation enables debugging code running on different machines
235
- **Symlink Handling**: Configurable symlink resolution for different debugging scenarios
236
- **Case Sensitivity**: Proper case handling for Windows vs Unix filesystems