0
# Object-Oriented Directory API
1

2
Object-based interface providing both string and Path object access to directories. This API enables reusable configuration and advanced features like directory iteration, making it ideal for applications that need to access multiple directories or require more complex directory management.
3

4
## Capabilities
5

6
### PlatformDirs Class
7

8
The main class providing comprehensive directory access through properties and methods. Automatically selects the appropriate platform implementation (Unix, Windows, macOS, or Android).
9

10
```python { .api }
11
class PlatformDirs:
12
    """
13
    Platform-specific directory paths for applications.
14
    
15
    Automatically detects the current platform and uses appropriate
16
    directory conventions (XDG on Unix, CSIDL on Windows, Apple guidelines on macOS).
17
    """
18
    
19
    def __init__(
20
        self,
21
        appname: str | None = None,
22
        appauthor: str | Literal[False] | None = None,
23
        version: str | None = None,
24
        roaming: bool = False,
25
        multipath: bool = False,
26
        opinion: bool = True,
27
        ensure_exists: bool = False,
28
    ) -> None:
29
        """
30
        Create a new platform directory instance.
31
        
32
        Parameters:
33
        - appname: Name of application
34
        - appauthor: Name of app author or distributing body (defaults to appname, False to disable)
35
        - version: Optional version path element (typically "<major>.<minor>")
36
        - roaming: Whether to use roaming appdata directory on Windows
37
        - multipath: Return entire list of directories (colon-separated on Unix) vs first item only
38
        - opinion: Flag indicating to use opinionated values
39
        - ensure_exists: Create directories on access if they don't exist
40
        """
41
    
42
    # Configuration properties
43
    appname: str | None
44
    appauthor: str | Literal[False] | None
45
    version: str | None
46
    roaming: bool
47
    multipath: bool
48
    opinion: bool
49
    ensure_exists: bool
50
```
51

52
### User Directory Properties
53

54
Properties returning user-specific directories as strings and Path objects.
55

56
```python { .api }
57
class PlatformDirs:
58
    @property
59
    def user_data_dir(self) -> str:
60
        """Data directory tied to the user."""
61
    
62
    @property
63
    def user_data_path(self) -> Path:
64
        """Data path tied to the user."""
65
    
66
    @property 
67
    def user_config_dir(self) -> str:
68
        """Config directory tied to the user."""
69
    
70
    @property
71
    def user_config_path(self) -> Path:
72
        """Config path tied to the user."""
73
    
74
    @property
75
    def user_cache_dir(self) -> str:
76
        """Cache directory tied to the user."""
77
    
78
    @property
79
    def user_cache_path(self) -> Path:
80
        """Cache path tied to the user."""
81
    
82
    @property
83
    def user_state_dir(self) -> str:
84
        """State directory tied to the user."""
85
    
86
    @property
87
    def user_state_path(self) -> Path:
88
        """State path tied to the user."""
89
    
90
    @property
91
    def user_log_dir(self) -> str:
92
        """Log directory tied to the user."""
93
    
94
    @property
95
    def user_log_path(self) -> Path:
96
        """Log path tied to the user."""
97
    
98
    @property
99
    def user_runtime_dir(self) -> str:
100
        """Runtime directory tied to the user."""
101
    
102
    @property
103
    def user_runtime_path(self) -> Path:
104
        """Runtime path tied to the user."""
105
```
106

107
### Site Directory Properties
108

109
Properties returning system-wide directories shared by all users.
110

111
```python { .api }
112
class PlatformDirs:
113
    @property
114
    def site_data_dir(self) -> str:
115
        """Data directory shared by users."""
116
    
117
    @property
118
    def site_data_path(self) -> Path:
119
        """Data path shared by users."""
120
    
121
    @property
122
    def site_config_dir(self) -> str:
123
        """Config directory shared by users."""
124
    
125
    @property
126
    def site_config_path(self) -> Path:
127
        """Config path shared by users."""
128
    
129
    @property
130
    def site_cache_dir(self) -> str:
131
        """Cache directory shared by users."""
132
    
133
    @property
134
    def site_cache_path(self) -> Path:
135
        """Cache path shared by users."""
136
    
137
    @property
138
    def site_runtime_dir(self) -> str:
139
        """Runtime directory shared by users."""
140
    
141
    @property
142
    def site_runtime_path(self) -> Path:
143
        """Runtime path shared by users."""
144
```
145

146
### Directory Iterator Methods
147

148
Methods for iterating over multiple related directories, useful for searching configuration or data files across user and system locations.
149

150
```python { .api }
151
class PlatformDirs:
152
    def iter_config_dirs(self) -> Iterator[str]:
153
        """Yield all user and site configuration directories."""
154
    
155
    def iter_config_paths(self) -> Iterator[Path]:
156
        """Yield all user and site configuration paths."""
157
    
158
    def iter_data_dirs(self) -> Iterator[str]:
159
        """Yield all user and site data directories."""
160
    
161
    def iter_data_paths(self) -> Iterator[Path]:
162
        """Yield all user and site data paths."""
163
    
164
    def iter_cache_dirs(self) -> Iterator[str]:
165
        """Yield all user and site cache directories."""
166
    
167
    def iter_cache_paths(self) -> Iterator[Path]:
168
        """Yield all user and site cache paths."""
169
    
170
    def iter_runtime_dirs(self) -> Iterator[str]:
171
        """Yield all user and site runtime directories."""
172
    
173
    def iter_runtime_paths(self) -> Iterator[Path]:
174
        """Yield all user and site runtime paths."""
175
```
176

177
### Platform-Specific Classes
178

179
Direct access to platform-specific implementations for advanced use cases.
180

181
```python { .api }
182
from platformdirs.unix import Unix
183
from platformdirs.windows import Windows  
184
from platformdirs.macos import MacOS
185
from platformdirs.android import Android
186

187
class Unix(PlatformDirsABC):
188
    """Unix/Linux implementation following XDG Base Directory Specification."""
189

190
class Windows(PlatformDirsABC):
191
    """Windows implementation using CSIDL constants and MSDN guidelines."""
192

193
class MacOS(PlatformDirsABC):
194
    """macOS implementation following Apple developer guidelines."""
195

196
class Android(PlatformDirsABC):
197
    """Android implementation for Android-specific directory conventions."""
198
```
199

200
## Usage Examples
201

202
```python
203
from platformdirs import PlatformDirs
204
from pathlib import Path
205

206
# Basic usage
207
dirs = PlatformDirs("MyApp", "MyCompany")
208
print(f"Data: {dirs.user_data_dir}")
209
print(f"Config: {dirs.user_config_dir}")
210
print(f"Cache: {dirs.user_cache_dir}")
211

212
# With version and auto-creation
213
dirs = PlatformDirs("MyApp", "MyCompany", version="2.1", ensure_exists=True)
214
config_path = dirs.user_config_path  # Path object, directory created if needed
215
data_path = dirs.user_data_path
216

217
# Create configuration file
218
config_file = config_path / "settings.json"
219
with open(config_file, 'w') as f:
220
    f.write('{"theme": "dark"}')
221

222
# Iterate over all possible config locations  
223
dirs = PlatformDirs("MyApp")
224
for config_dir in dirs.iter_config_dirs():
225
    config_file = Path(config_dir) / "settings.json"
226
    if config_file.exists():
227
        print(f"Found config: {config_file}")
228
        break
229

230
# Using multipath for Unix systems
231
dirs = PlatformDirs("MyApp", multipath=True)
232
# On Unix, may return colon-separated paths like "/home/user/.local/share/MyApp:/usr/local/share/MyApp"
233
all_data_dirs = dirs.site_data_dir
234

235
# Platform-specific usage
236
from platformdirs.unix import Unix
237
unix_dirs = Unix("MyApp", "MyCompany")
238
xdg_data_home = unix_dirs.user_data_dir  # Always uses XDG spec
239

240
# Backwards compatibility
241
from platformdirs import AppDirs  # Alias for PlatformDirs
242
dirs = AppDirs("MyApp", "MyCompany")  # Same as PlatformDirs
243
```
244

245
## Advanced Configuration
246

247
```python
248
from platformdirs import PlatformDirs
249

250
# Windows roaming profiles
251
dirs = PlatformDirs("MyApp", "MyCompany", roaming=True)
252
# Uses %APPDATA% instead of %LOCALAPPDATA% on Windows
253

254
# Disable appauthor on Windows
255
dirs = PlatformDirs("MyApp", appauthor=False)
256
# Windows path: %LOCALAPPDATA%\MyApp instead of %LOCALAPPDATA%\MyCompany\MyApp
257

258
# Opinion flag affects some directory choices
259
dirs = PlatformDirs("MyApp", opinion=False)
260
# May affect cache/log directory selection on some platforms
261

262
# Multiple versions can coexist
263
dirs_v1 = PlatformDirs("MyApp", version="1.0")
264
dirs_v2 = PlatformDirs("MyApp", version="2.0") 
265
# Each version gets separate directories
266
```