0
# Appdirs
1

2
A small Python module for determining appropriate platform-specific directories for storing application data, configuration files, cache data, and logs. It implements the XDG Base Directory Specification for Unix systems while providing native directory conventions for Windows and macOS.
3

4
## Package Information
5

6
- **Package Name**: appdirs
7
- **Language**: Python
8
- **Installation**: `pip install appdirs`
9

10
## Core Imports
11

12
```python
13
import appdirs
14
```
15

16
Or import specific functions:
17

18
```python
19
from appdirs import user_data_dir, user_config_dir, AppDirs
20
```
21

22
## Basic Usage
23

24
```python
25
import appdirs
26

27
# Get platform-appropriate directories for your app
28
data_dir = appdirs.user_data_dir("MyApp", "MyCompany")
29
config_dir = appdirs.user_config_dir("MyApp", "MyCompany") 
30
cache_dir = appdirs.user_cache_dir("MyApp", "MyCompany")
31

32
print(f"Data directory: {data_dir}")
33
print(f"Config directory: {config_dir}")
34
print(f"Cache directory: {cache_dir}")
35

36
# Using the convenience class
37
dirs = appdirs.AppDirs("MyApp", "MyCompany", version="1.0")
38
print(f"User data: {dirs.user_data_dir}")
39
print(f"User config: {dirs.user_config_dir}")
40
print(f"User cache: {dirs.user_cache_dir}")
41
```
42

43
## Capabilities
44

45
### User Data Directory
46

47
Returns the user-specific data directory path for an application, following platform conventions.
48

49
```python { .api }
50
def user_data_dir(appname=None, appauthor=None, version=None, roaming=False):
51
    """
52
    Return full path to the user-specific data dir for this application.
53

54
    Args:
55
        appname (str, optional): Name of application. If None, just the system directory is returned.
56
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only). 
57
                                 Typically the owning company name. Falls back to appname. 
58
                                 You may pass False to disable it.
59
        version (str, optional): Optional version path element to append to the path.
60
                               Typically "<major>.<minor>". Only applied when appname is present.
61
        roaming (bool): Can be set True to use the Windows roaming appdata directory.
62

63
    Returns:
64
        str: Full path to user data directory
65

66
    Platform examples:
67
        Mac OS X: ~/Library/Application Support/<AppName>
68
        Unix: ~/.local/share/<AppName> (or in $XDG_DATA_HOME, if defined)
69
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>
70
    """
71
```
72

73
### Site Data Directory  
74

75
Returns the system-wide shared data directory path for an application.
76

77
```python { .api }
78
def site_data_dir(appname=None, appauthor=None, version=None, multipath=False):
79
    """
80
    Return full path to the user-shared data dir for this application.
81

82
    Args:
83
        appname (str, optional): Name of application. If None, just the system directory is returned.
84
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
85
        version (str, optional): Optional version path element to append to the path.
86
        multipath (bool): Parameter only applicable to *nix which indicates that the entire 
87
                         list of data dirs should be returned. By default, the first item 
88
                         from XDG_DATA_DIRS is returned.
89

90
    Returns:
91
        str: Full path to site data directory (or path separator-joined paths if multipath=True)
92

93
    Platform examples:
94
        Mac OS X: /Library/Application Support/<AppName>
95
        Unix: /usr/local/share/<AppName> or /usr/share/<AppName>
96
        Windows: C:\\ProgramData\\<AppAuthor>\\<AppName>
97
        
98
    Warning:
99
        Do not use this on Windows. See Vista compatibility issues in documentation.
100
    """
101
```
102

103
### User Config Directory
104

105
Returns the user-specific config directory path for an application.
106

107
```python { .api }
108
def user_config_dir(appname=None, appauthor=None, version=None, roaming=False):
109
    """
110
    Return full path to the user-specific config dir for this application.
111

112
    Args:
113
        appname (str, optional): Name of application. If None, just the system directory is returned.
114
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
115
        version (str, optional): Optional version path element to append to the path.
116
        roaming (bool): Can be set True to use the Windows roaming appdata directory.
117

118
    Returns:
119
        str: Full path to user config directory
120

121
    Platform examples:
122
        Mac OS X: same as user_data_dir
123
        Unix: ~/.config/<AppName> (or in $XDG_CONFIG_HOME, if defined)
124
        Windows: same as user_data_dir
125
    """
126
```
127

128
### Site Config Directory
129

130
Returns the system-wide shared config directory path for an application.
131

132
```python { .api }
133
def site_config_dir(appname=None, appauthor=None, version=None, multipath=False):
134
    """
135
    Return full path to the user-shared config dir for this application.
136

137
    Args:
138
        appname (str, optional): Name of application. If None, just the system directory is returned.
139
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
140
        version (str, optional): Optional version path element to append to the path.
141
        multipath (bool): Parameter only applicable to *nix which indicates that the entire 
142
                         list of config dirs should be returned.
143

144
    Returns:
145
        str: Full path to site config directory (or path separator-joined paths if multipath=True)
146

147
    Platform examples:
148
        Mac OS X: same as site_data_dir
149
        Unix: /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName>
150
        Windows: same as site_data_dir
151
        
152
    Warning:
153
        Do not use this on Windows. See Vista compatibility issues in documentation.
154
    """
155
```
156

157
### User Cache Directory
158

159
Returns the user-specific cache directory path for an application.
160

161
```python { .api }
162
def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True):
163
    """
164
    Return full path to the user-specific cache dir for this application.
165

166
    Args:
167
        appname (str, optional): Name of application. If None, just the system directory is returned. 
168
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
169
        version (str, optional): Optional version path element to append to the path.
170
        opinion (bool): Can be False to disable the appending of "Cache" to the base app 
171
                       data dir for Windows.
172

173
    Returns:
174
        str: Full path to user cache directory
175

176
    Platform examples:
177
        Mac OS X: ~/Library/Caches/<AppName>
178
        Unix: ~/.cache/<AppName> (XDG default)
179
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>\\Cache
180
    """
181
```
182

183
### User State Directory
184

185
Returns the user-specific state directory path for an application.
186

187
```python { .api }
188
def user_state_dir(appname=None, appauthor=None, version=None, roaming=False):
189
    """
190
    Return full path to the user-specific state dir for this application.
191

192
    Args:
193
        appname (str, optional): Name of application. If None, just the system directory is returned.
194
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).
195
        version (str, optional): Optional version path element to append to the path.
196
        roaming (bool): Can be set True to use the Windows roaming appdata directory.
197

198
    Returns:
199
        str: Full path to user state directory
200

201
    Platform examples:
202
        Mac OS X: same as user_data_dir
203
        Unix: ~/.local/state/<AppName> (or in $XDG_STATE_HOME, if defined)
204
        Windows: same as user_data_dir
205
    """
206
```
207

208
### User Log Directory
209

210
Returns the user-specific log directory path for an application.
211

212
```python { .api }
213
def user_log_dir(appname=None, appauthor=None, version=None, opinion=True):
214
    """
215
    Return full path to the user-specific log dir for this application.
216

217
    Args:
218
        appname (str, optional): Name of application. If None, just the system directory is returned.
219
        appauthor (str, optional): Name of the appauthor or distributing body (Windows only).  
220
        version (str, optional): Optional version path element to append to the path.
221
        opinion (bool): Can be False to disable the appending of "Logs" to the base app 
222
                       data dir for Windows, and "log" to the base cache dir for Unix.
223

224
    Returns:
225
        str: Full path to user log directory
226

227
    Platform examples:
228
        Mac OS X: ~/Library/Logs/<AppName>
229
        Unix: ~/.cache/<AppName>/log (or under $XDG_CACHE_HOME if defined)
230
        Windows: C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\<AppName>\\Logs
231
    """
232
```
233

234
### AppDirs Class
235

236
Convenience wrapper class for getting application directories with consistent configuration.
237

238
```python { .api }
239
class AppDirs:
240
    """
241
    Convenience wrapper for getting application dirs.
242
    
243
    Args:
244
        appname (str, optional): Application name
245
        appauthor (str, optional): Application author/company  
246
        version (str, optional): Version path element
247
        roaming (bool): Use Windows roaming profiles
248
        multipath (bool): Return all paths on Unix systems
249
    """
250
    
251
    def __init__(self, appname=None, appauthor=None, version=None, roaming=False, multipath=False):
252
        """Initialize AppDirs with application metadata."""
253
    
254
    @property
255
    def user_data_dir(self):
256
        """User data directory path."""
257
    
258
    @property  
259
    def site_data_dir(self):
260
        """Site data directory path."""
261
    
262
    @property
263
    def user_config_dir(self):
264
        """User config directory path."""
265
    
266
    @property
267
    def site_config_dir(self):
268
        """Site config directory path."""
269
    
270
    @property
271
    def user_cache_dir(self):
272
        """User cache directory path."""
273
    
274
    @property
275
    def user_state_dir(self):
276
        """User state directory path."""
277
    
278
    @property
279
    def user_log_dir(self):
280
        """User log directory path."""
281
```
282

283
## Version Information
284

285
```python { .api }
286
__version__: str  # Package version string (e.g., "1.4.4")
287
__version_info__: tuple  # Version info as tuple of integers
288
```
289

290
## Platform Constants
291

292
```python { .api }
293
PY3: bool  # True if running Python 3, False otherwise
294
system: str  # Platform identifier string (win32, darwin, linux2, etc.)
295
```