0
# Path Management
1

2
Cross-platform directory discovery and path utilities for managing Jupyter configuration, data, and runtime directories. Provides standardized access to user-level, environment-level, and system-wide Jupyter installations with full support for virtual environments and platform-specific conventions.
3

4
## Capabilities
5

6
### Core Directory Functions
7

8
Primary functions for discovering standard Jupyter directories across different platforms and installation contexts.
9

10
```python { .api }
11
def jupyter_config_dir() -> str:
12
    """Get the Jupyter config directory for this platform and user.
13
    
14
    Returns JUPYTER_CONFIG_DIR if defined, otherwise the appropriate
15
    directory for the platform.
16
    
17
    Returns:
18
        str: Path to Jupyter config directory
19
    """
20

21
def jupyter_data_dir() -> str:
22
    """Get the config directory for Jupyter data files for this platform and user.
23
    
24
    These are non-transient, non-configuration files.
25
    
26
    Returns JUPYTER_DATA_DIR if defined, else a platform-appropriate path.
27
    
28
    Returns:
29
        str: Path to Jupyter data directory
30
    """
31

32
def jupyter_runtime_dir() -> str:
33
    """Return the runtime dir for transient jupyter files.
34
    
35
    Returns JUPYTER_RUNTIME_DIR if defined.
36
    The default is now (data_dir)/runtime on all platforms.
37
    
38
    Returns:
39
        str: Path to Jupyter runtime directory
40
    """
41
```
42

43
**Usage Example:**
44

45
```python
46
from jupyter_core.paths import (
47
    jupyter_config_dir, jupyter_data_dir, jupyter_runtime_dir
48
)
49

50
# Get standard Jupyter directories
51
config_dir = jupyter_config_dir()    # ~/.jupyter
52
data_dir = jupyter_data_dir()        # ~/.local/share/jupyter  
53
runtime_dir = jupyter_runtime_dir()  # ~/.local/share/jupyter/runtime
54

55
print(f"Config: {config_dir}")
56
print(f"Data: {data_dir}")
57
print(f"Runtime: {runtime_dir}")
58
```
59

60
### Search Path Functions
61

62
Functions for discovering search paths that include user, environment, and system-wide locations for Jupyter files and configuration.
63

64
```python { .api }
65
def jupyter_path(*subdirs: str) -> list[str]:
66
    """Return a list of directories to search for data files.
67
    
68
    There are four sources of paths to search:
69
    - $JUPYTER_PATH environment variable (always highest priority)
70
    - user directories (e.g. ~/.local/share/jupyter)
71
    - environment directories (e.g. {sys.prefix}/share/jupyter)
72
    - system-wide paths (e.g. /usr/local/share/jupyter)
73
    
74
    Args:
75
        *subdirs: Optional subdirectory path components to append
76
        
77
    Returns:
78
        list[str]: Ordered list of directories to search
79
    """
80

81
def jupyter_config_path() -> list[str]:
82
    """Return the search path for Jupyter config files as a list.
83
    
84
    Searches user, environment, and system config directories in priority order.
85
    
86
    Returns:
87
        list[str]: Ordered list of config directories to search
88
    """
89
```
90

91
**Usage Example:**
92

93
```python
94
from jupyter_core.paths import jupyter_path, jupyter_config_path
95

96
# Get search paths for data files
97
data_paths = jupyter_path()
98
print("Data search paths:", data_paths)
99

100
# Get search paths for kernel specifications
101
kernel_paths = jupyter_path("kernels")
102
print("Kernel search paths:", kernel_paths)
103

104
# Get search paths for config files
105
config_paths = jupyter_config_path()
106
print("Config search paths:", config_paths)
107
```
108

109
### Path Configuration Functions
110

111
Functions for determining path behavior based on environment variables and system configuration.
112

113
```python { .api }
114
def use_platform_dirs() -> bool:
115
    """Determine if platformdirs should be used for system-specific paths.
116
    
117
    Returns the value of JUPYTER_PLATFORM_DIRS environment variable.
118
    
119
    Returns:
120
        bool: True if platformdirs should be used
121
    """
122

123
def prefer_environment_over_user() -> bool:
124
    """Determine if environment-level paths should take precedence over user-level paths.
125
    
126
    Returns True if:
127
    - JUPYTER_PREFER_ENV_PATH is set to a truthy value, OR
128
    - We detect a Python virtual environment and the user owns sys.prefix, OR
129
    - We detect a conda environment (not base) and the user owns sys.prefix
130
    
131
    Returns:
132
        bool: True if environment paths should be preferred
133
    """
134

135
def envset(name: str, default: bool | None = False) -> bool | None:
136
    """Return the boolean value of a given environment variable.
137
    
138
    An environment variable is considered set if it is assigned to a value
139
    other than 'no', 'n', 'false', 'off', '0', or '0.0' (case insensitive).
140
    
141
    Args:
142
        name: Environment variable name
143
        default: Default value if not defined
144
        
145
    Returns:
146
        bool | None: Boolean value of environment variable
147
    """
148
```
149

150
### File Utility Functions
151

152
Utilities for file and directory operations with cross-platform compatibility and security considerations.
153

154
```python { .api }
155
def get_home_dir() -> str:
156
    """Get the real path of the home directory
157
    
158
    Returns:
159
        str: Resolved home directory path
160
    """
161

162
def exists(path: str) -> bool:
163
    """Replacement for `os.path.exists` which works for host mapped volumes
164
    on Windows containers
165
    
166
    Args:
167
        path: Path to check
168
        
169
    Returns:
170
        bool: True if path exists
171
    """
172

173
def is_hidden(abs_path: str, abs_root: str = "") -> bool:
174
    """Is a file hidden or contained in a hidden directory?
175
    
176
    Checks if a path is hidden based on name (starts with '.') or 
177
    platform-specific hidden flags.
178
    
179
    Args:
180
        abs_path: Absolute path to check
181
        abs_root: Root directory for relative hidden checks
182
        
183
    Returns:
184
        bool: True if file/directory is hidden
185
    """
186
```
187

188
### File Security Functions
189

190
Functions for creating files with appropriate security permissions, especially important for configuration and credential files.
191

192
```python { .api }
193
def secure_write(fname: str, binary: bool = False):
194
    """Context manager that opens a file with restricted permissions (0o0600).
195
    
196
    Creates files that are readable/writable only by the owner.
197
    On Windows, uses platform-specific security restrictions.
198
    
199
    Args:
200
        fname: Path to file to create
201
        binary: Whether to open in binary mode
202
        
203
    Yields:
204
        file: Opened file handle with secure permissions
205
    """
206

207
def win32_restrict_file_to_user(fname: str) -> None:
208
    """Secure a windows file to read-only access for the user.
209
    
210
    Uses Windows security APIs to restrict file access to current user
211
    and administrators only.
212
    
213
    Args:
214
        fname: Path to file to secure
215
    """
216

217
def get_file_mode(fname: str) -> int:
218
    """Retrieves the file mode in a filesystem-tolerant manner.
219
    
220
    Some filesystems auto-enable execute bits, so this function
221
    masks out problematic permission bits for validation.
222
    
223
    Args:
224
        fname: Path to file
225
        
226
    Returns:
227
        int: Masked file mode suitable for permission checking
228
    """
229

230
def issue_insecure_write_warning() -> None:
231
    """Issue an insecure write warning when JUPYTER_ALLOW_INSECURE_WRITES is set."""
232
```
233

234
**Usage Example:**
235

236
```python
237
from jupyter_core.paths import secure_write
238

239
# Create a config file with secure permissions
240
config_data = {"key": "secret_value"}
241

242
with secure_write("/path/to/config.json") as f:
243
    import json
244
    json.dump(config_data, f)
245
    
246
# File is created with 0o0600 permissions (user read/write only)
247
```
248

249
### Platform Constants
250

251
Platform-specific constants and paths used throughout the Jupyter ecosystem.
252

253
```python { .api }
254
# Application name for directory paths ("Jupyter" on Windows/macOS, "jupyter" on Linux) 
255
APPNAME: str
256

257
# System-wide Jupyter data paths
258
SYSTEM_JUPYTER_PATH: list[str]
259

260
# Environment-level Jupyter data paths  
261
ENV_JUPYTER_PATH: list[str]
262

263
# System-wide Jupyter config paths
264
SYSTEM_CONFIG_PATH: list[str]
265

266
# Environment-level Jupyter config paths
267
ENV_CONFIG_PATH: list[str]
268

269
# Global flag for allowing insecure writes
270
allow_insecure_writes: bool
271

272
# BSD hidden file flag constant  
273
UF_HIDDEN: int  # Value: 32768, used for BSD hidden file detection
274
```
275

276
## Environment Variables
277

278
The path management system respects numerous environment variables for customization:
279

280
### Directory Override Variables
281
- **JUPYTER_CONFIG_DIR**: Override the default config directory
282
- **JUPYTER_DATA_DIR**: Override the default data directory  
283
- **JUPYTER_RUNTIME_DIR**: Override the default runtime directory
284

285
### Search Path Variables
286
- **JUPYTER_PATH**: Prepend additional directories to data search path
287
- **JUPYTER_CONFIG_PATH**: Prepend additional directories to config search path
288

289
### Behavior Control Variables
290
- **JUPYTER_NO_CONFIG**: Disable config file loading entirely
291
- **JUPYTER_PLATFORM_DIRS**: Use platformdirs for directory discovery
292
- **JUPYTER_PREFER_ENV_PATH**: Prefer environment over user directories
293
- **JUPYTER_USE_PROGRAMDATA**: Use PROGRAMDATA directory on Windows
294
- **JUPYTER_ALLOW_INSECURE_WRITES**: Allow insecure file permissions
295

296
### System Integration Variables
297
- **IPYTHONDIR**: IPython directory location (for migration)
298
- **CONDA_PREFIX**: Conda environment detection
299
- **CONDA_DEFAULT_ENV**: Conda environment name detection
300

301
## Platform-Specific Behavior
302

303
### Windows
304
- Uses `%APPDATA%\jupyter` for config by default
305
- Uses `%APPDATA%\jupyter` for data by default  
306
- Supports PROGRAMDATA for system-wide installations (opt-in)
307
- Implements Windows-specific file security via ACLs
308
- Handles executable resolution differences
309

310
### macOS  
311
- Uses `~/Library/Jupyter` for data directory
312
- Uses `~/.jupyter` for config directory
313
- Detects Homebrew installations for appropriate naming
314
- Uses BSD hidden file flags
315

316
### Linux/Unix
317
- Follows XDG Base Directory specification when JUPYTER_PLATFORM_DIRS=1
318
- Uses `~/.local/share/jupyter` for data
319
- Uses `~/.jupyter` for config  
320
- Uses `~/.local/share/jupyter/runtime` for runtime files
321
- Supports standard Unix file permissions and hidden files
322

323
## Virtual Environment Support
324

325
Automatic detection and appropriate handling of:
326

327
- **Python venv**: Detects via `sys.prefix != sys.base_prefix`
328
- **Conda environments**: Detects via CONDA_PREFIX environment variable
329
- **Custom environments**: Respects JUPYTER_PREFER_ENV_PATH override
330

331
When in a virtual environment, environment-level paths take precedence over user-level paths by default, ensuring isolated package installations work correctly.