0
# Functional Directory API
1

2
Simple functions that return directory paths as strings for common use cases. This API provides a straightforward way to get platform-appropriate directories without creating objects, making it ideal for simple scripts and one-time directory lookups.
3

4
## Capabilities
5

6
### User Directory Functions
7

8
Functions for accessing user-specific directories where applications store data, configuration, cache, logs, and state information.
9

10
```python { .api }
11
def user_data_dir(
12
    appname: str | None = None,
13
    appauthor: str | Literal[False] | None = None,
14
    version: str | None = None,
15
    roaming: bool = False,
16
    ensure_exists: bool = False,
17
) -> str:
18
    """
19
    Return data directory tied to the user.
20
    
21
    Parameters:
22
    - appname: Name of application
23
    - appauthor: Name of app author or distributing body (defaults to appname, False to disable)
24
    - version: Optional version path element (typically "<major>.<minor>")
25
    - roaming: Whether to use roaming appdata directory on Windows
26
    - ensure_exists: Create directory if it doesn't exist
27
    
28
    Returns:
29
    Platform-appropriate user data directory path
30
    
31
    Examples:
32
    - Unix: ~/.local/share/$appname/$version
33
    - Windows: %USERPROFILE%\AppData\Local\$appauthor\$appname
34
    - macOS: ~/Library/Application Support/$appname/$version
35
    """
36

37
def user_config_dir(
38
    appname: str | None = None,
39
    appauthor: str | Literal[False] | None = None,
40
    version: str | None = None,
41
    roaming: bool = False,
42
    ensure_exists: bool = False,
43
) -> str:
44
    """
45
    Return config directory tied to the user.
46
    
47
    Parameters:
48
    - appname: Name of application
49
    - appauthor: Name of app author or distributing body
50
    - version: Optional version path element
51
    - roaming: Whether to use roaming appdata directory on Windows
52
    - ensure_exists: Create directory if it doesn't exist
53
    
54
    Returns:
55
    Platform-appropriate user config directory path
56
    
57
    Examples:
58
    - Unix: ~/.config/$appname/$version
59
    - Windows: %USERPROFILE%\AppData\Local\$appauthor\$appname
60
    - macOS: ~/Library/Application Support/$appname/$version
61
    """
62

63
def user_cache_dir(
64
    appname: str | None = None,
65
    appauthor: str | Literal[False] | None = None,
66
    version: str | None = None,
67
    opinion: bool = True,
68
    ensure_exists: bool = False,
69
) -> str:
70
    """
71
    Return cache directory tied to the user.
72
    
73
    Parameters:
74
    - appname: Name of application
75
    - appauthor: Name of app author or distributing body
76
    - version: Optional version path element
77
    - opinion: Flag indicating to use opinionated values
78
    - ensure_exists: Create directory if it doesn't exist
79
    
80
    Returns:
81
    Platform-appropriate user cache directory path
82
    
83
    Examples:
84
    - Unix: ~/.cache/$appname/$version
85
    - Windows: %USERPROFILE%\AppData\Local\$appauthor\$appname\Cache
86
    - macOS: ~/Library/Caches/$appname/$version
87
    """
88

89
def user_state_dir(
90
    appname: str | None = None,
91
    appauthor: str | Literal[False] | None = None,
92
    version: str | None = None,
93
    roaming: bool = False,
94
    ensure_exists: bool = False,
95
) -> str:
96
    """
97
    Return state directory tied to the user.
98
    
99
    Parameters:
100
    - appname: Name of application
101
    - appauthor: Name of app author or distributing body
102
    - version: Optional version path element
103
    - roaming: Whether to use roaming appdata directory on Windows
104
    - ensure_exists: Create directory if it doesn't exist
105
    
106
    Returns:
107
    Platform-appropriate user state directory path
108
    
109
    Examples:
110
    - Unix: ~/.local/state/$appname/$version
111
    - Windows: %USERPROFILE%\AppData\Local\$appauthor\$appname
112
    - macOS: ~/Library/Application Support/$appname/$version
113
    """
114

115
def user_log_dir(
116
    appname: str | None = None,
117
    appauthor: str | Literal[False] | None = None,
118
    version: str | None = None,
119
    opinion: bool = True,
120
    ensure_exists: bool = False,
121
) -> str:
122
    """
123
    Return log directory tied to the user.
124
    
125
    Parameters:
126
    - appname: Name of application
127
    - appauthor: Name of app author or distributing body
128
    - version: Optional version path element
129
    - opinion: Flag indicating to use opinionated values
130
    - ensure_exists: Create directory if it doesn't exist
131
    
132
    Returns:
133
    Platform-appropriate user log directory path
134
    
135
    Examples:
136
    - Unix: ~/.local/state/$appname/$version/log
137
    - Windows: %USERPROFILE%\AppData\Local\$appauthor\$appname\Logs
138
    - macOS: ~/Library/Logs/$appname/$version
139
    """
140

141
def user_runtime_dir(
142
    appname: str | None = None,
143
    appauthor: str | Literal[False] | None = None,
144
    version: str | None = None,
145
    opinion: bool = True,
146
    ensure_exists: bool = False,
147
) -> str:
148
    """
149
    Return runtime directory tied to the user.
150
    
151
    Parameters:
152
    - appname: Name of application
153
    - appauthor: Name of app author or distributing body
154
    - version: Optional version path element
155
    - opinion: Flag indicating to use opinionated values
156
    - ensure_exists: Create directory if it doesn't exist
157
    
158
    Returns:
159
    Platform-appropriate user runtime directory path
160
    
161
    Examples:
162
    - Unix: /run/user/$uid/$appname/$version
163
    - Windows: %USERPROFILE%\AppData\Local\Temp\$appauthor\$appname
164
    - macOS: ~/Library/Caches/TemporaryItems/$appname/$version
165
    """
166
```
167

168
### Site Directory Functions
169

170
Functions for accessing system-wide directories shared by all users, typically used for application data, configuration, and cache that should be available system-wide.
171

172
```python { .api }
173
def site_data_dir(
174
    appname: str | None = None,
175
    appauthor: str | Literal[False] | None = None,
176
    version: str | None = None,
177
    multipath: bool = False,
178
    ensure_exists: bool = False,
179
) -> str:
180
    """
181
    Return data directory shared by users.
182
    
183
    Parameters:
184
    - appname: Name of application
185
    - appauthor: Name of app author or distributing body
186
    - version: Optional version path element
187
    - multipath: Return entire list of data dirs (colon-separated on Unix)
188
    - ensure_exists: Create directory if it doesn't exist
189
    
190
    Returns:
191
    Platform-appropriate site data directory path
192
    
193
    Examples:
194
    - Unix: /usr/local/share/$appname/$version
195
    - Windows: %ALLUSERSPROFILE%\$appauthor\$appname
196
    - macOS: /Library/Application Support/$appname/$version
197
    """
198

199
def site_config_dir(
200
    appname: str | None = None,
201
    appauthor: str | Literal[False] | None = None,
202
    version: str | None = None,
203
    multipath: bool = False,
204
    ensure_exists: bool = False,
205
) -> str:
206
    """
207
    Return config directory shared by users.
208
    
209
    Parameters:
210
    - appname: Name of application
211
    - appauthor: Name of app author or distributing body
212
    - version: Optional version path element
213
    - multipath: Return entire list of config dirs (colon-separated on Unix)
214
    - ensure_exists: Create directory if it doesn't exist
215
    
216
    Returns:
217
    Platform-appropriate site config directory path
218
    
219
    Examples:
220
    - Unix: /etc/$appname/$version
221
    - Windows: %ALLUSERSPROFILE%\$appauthor\$appname
222
    - macOS: /Library/Application Support/$appname/$version
223
    """
224

225
def site_cache_dir(
226
    appname: str | None = None,
227
    appauthor: str | Literal[False] | None = None,
228
    version: str | None = None,
229
    opinion: bool = True,
230
    ensure_exists: bool = False,
231
) -> str:
232
    """
233
    Return cache directory shared by users.
234
    
235
    Parameters:
236
    - appname: Name of application
237
    - appauthor: Name of app author or distributing body
238
    - version: Optional version path element
239
    - opinion: Flag indicating to use opinionated values
240
    - ensure_exists: Create directory if it doesn't exist
241
    
242
    Returns:
243
    Platform-appropriate site cache directory path
244
    
245
    Examples:
246
    - Unix: /var/cache/$appname/$version
247
    - Windows: %ALLUSERSPROFILE%\$appauthor\$appname\Cache
248
    - macOS: /Library/Caches/$appname/$version
249
    """
250

251
def site_runtime_dir(
252
    appname: str | None = None,
253
    appauthor: str | Literal[False] | None = None,
254
    version: str | None = None,
255
    opinion: bool = True,
256
    ensure_exists: bool = False,
257
) -> str:
258
    """
259
    Return runtime directory shared by users.
260
    
261
    Parameters:
262
    - appname: Name of application
263
    - appauthor: Name of app author or distributing body
264
    - version: Optional version path element
265
    - opinion: Flag indicating to use opinionated values
266
    - ensure_exists: Create directory if it doesn't exist
267
    
268
    Returns:
269
    Platform-appropriate site runtime directory path
270
    
271
    Examples:
272
    - Unix: /run/$appname/$version
273
    - Windows: %ALLUSERSPROFILE%\$appauthor\$appname
274
    - macOS: /var/run/$appname/$version
275
    """
276
```
277

278
### Path Versions
279

280
Each directory function has a corresponding path version that returns a `pathlib.Path` object instead of a string:
281

282
```python { .api }
283
def user_data_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, ensure_exists: bool = False) -> Path: ...
284
def user_config_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, ensure_exists: bool = False) -> Path: ...
285
def user_cache_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> Path: ...
286
def user_state_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, ensure_exists: bool = False) -> Path: ...
287
def user_log_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> Path: ...
288
def user_runtime_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> Path: ...
289
def site_data_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, multipath: bool = False, ensure_exists: bool = False) -> Path: ...
290
def site_config_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, multipath: bool = False, ensure_exists: bool = False) -> Path: ...
291
def site_cache_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> Path: ...
292
def site_runtime_path(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> Path: ...
293
```
294

295
## Usage Examples
296

297
```python
298
from platformdirs import user_data_dir, user_config_dir, site_data_dir
299

300
# Simple usage with just app name
301
data_dir = user_data_dir("MyApp")
302
config_dir = user_config_dir("MyApp")
303

304
# With app author for Windows compatibility
305
data_dir = user_data_dir("MyApp", "MyCompany")
306

307
# With version for multiple versions
308
data_dir = user_data_dir("MyApp", "MyCompany", version="2.1")
309

310
# Ensure directory exists when accessed
311
data_dir = user_data_dir("MyApp", ensure_exists=True)
312

313
# Get site-wide directories  
314
site_data = site_data_dir("MyApp", "MyCompany")
315

316
# Using Path objects for advanced path operations
317
from platformdirs import user_data_path
318
data_path = user_data_path("MyApp")
319
config_file = data_path / "config.json"
320
```