0
# Platform Directories
1

2
A small Python package for determining appropriate platform-specific directories for storing application data, configuration files, cache, logs, and other resources. This library serves as a modern replacement for the appdirs library, providing cross-platform directory management with support for the XDG Base Directory Specification on Linux, Apple guidelines on macOS, MSDN recommendations on Windows, and Android-specific conventions.
3

4
## Package Information
5

6
- **Package Name**: platformdirs
7
- **Language**: Python
8
- **Installation**: `pip install platformdirs`
9
- **Python Requirements**: >=3.9
10

11
## Core Imports
12

13
```python
14
import platformdirs
15
```
16

17
For functional API:
18

19
```python
20
from platformdirs import user_data_dir, user_config_dir, user_cache_dir
21
```
22

23
For object-oriented API:
24

25
```python
26
from platformdirs import PlatformDirs
27
```
28

29
For version information:
30

31
```python
32
from platformdirs import __version__, __version_info__
33
```
34

35
## Basic Usage
36

37
```python
38
from platformdirs import user_data_dir, user_config_dir, user_cache_dir, PlatformDirs
39

40
# Functional API - simple directory retrieval
41
app_data = user_data_dir("MyApp", "MyCompany")
42
app_config = user_config_dir("MyApp", "MyCompany") 
43
app_cache = user_cache_dir("MyApp", "MyCompany")
44

45
print(f"Data: {app_data}")
46
print(f"Config: {app_config}")
47
print(f"Cache: {app_cache}")
48

49
# Object-oriented API - more flexible
50
dirs = PlatformDirs("MyApp", "MyCompany", version="1.0")
51
print(f"Data: {dirs.user_data_dir}")
52
print(f"Config: {dirs.user_config_dir}")
53
print(f"Logs: {dirs.user_log_dir}")
54

55
# Ensure directories exist when accessed
56
dirs_auto = PlatformDirs("MyApp", ensure_exists=True)
57
data_path = dirs_auto.user_data_path  # Creates directory if missing
58

59
# Check version information
60
from platformdirs import __version__, __version_info__
61
print(f"platformdirs version: {__version__}")
62
print(f"Version info: {__version_info__}")
63
```
64

65
## Architecture
66

67
platformdirs uses a polymorphic architecture that automatically selects the appropriate platform implementation:
68

69
- **PlatformDirsABC**: Abstract base class defining the complete API interface
70
- **Platform Implementations**: Unix (XDG), Windows (CSIDL), macOS (Apple guidelines), Android
71
- **Automatic Detection**: Runtime platform detection with fallback to Unix implementation
72
- **Dual APIs**: Both functional (single-use) and object-oriented (reusable) interfaces
73

74
The design follows platform conventions while providing a unified API, making it suitable for both simple scripts and complex applications requiring extensive directory management.
75

76
## Capabilities
77

78
### Functional Directory API
79

80
Simple functions that return directory paths as strings for common use cases. Each function accepts optional parameters for app identification and behavior customization.
81

82
```python { .api }
83
def user_data_dir(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, ensure_exists: bool = False) -> str: ...
84
def user_config_dir(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, ensure_exists: bool = False) -> str: ...
85
def user_cache_dir(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, opinion: bool = True, ensure_exists: bool = False) -> str: ...
86
def site_data_dir(appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, multipath: bool = False, ensure_exists: bool = False) -> str: ...
87
```
88

89
[Functional API](./functional-api.md)
90

91
### Object-Oriented Directory API 
92

93
Object-based interface providing both string and Path object access to directories. Enables reusable configuration and advanced features like directory iteration.
94

95
```python { .api }
96
class PlatformDirs:
97
    def __init__(self, appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, multipath: bool = False, opinion: bool = True, ensure_exists: bool = False) -> None: ...
98
    
99
    @property
100
    def user_data_dir(self) -> str: ...
101
    @property 
102
    def user_data_path(self) -> Path: ...
103
```
104

105
[Object-Oriented API](./object-oriented-api.md)
106

107
### User Media Directories
108

109
Access to standard user media directories like Documents, Downloads, Pictures, Videos, Music, and Desktop. These provide system-appropriate locations regardless of platform.
110

111
```python { .api }
112
def user_documents_dir() -> str: ...
113
def user_downloads_dir() -> str: ...
114
def user_pictures_dir() -> str: ...
115
def user_videos_dir() -> str: ...
116
def user_music_dir() -> str: ...
117
def user_desktop_dir() -> str: ...
118
```
119

120
[User Media Directories](./user-media-directories.md)
121

122
## Types
123

124
```python { .api }
125
from typing import Literal
126
from pathlib import Path
127
from abc import ABC, abstractmethod
128
from collections.abc import Iterator
129
from platformdirs import PlatformDirsABC
130

131
class PlatformDirsABC(ABC):
132
    """Abstract base class for platform directories."""
133
    
134
    appname: str | None
135
    appauthor: str | Literal[False] | None  
136
    version: str | None
137
    roaming: bool
138
    multipath: bool
139
    opinion: bool
140
    ensure_exists: bool
141
    
142
    def __init__(self, appname: str | None = None, appauthor: str | Literal[False] | None = None, version: str | None = None, roaming: bool = False, multipath: bool = False, opinion: bool = True, ensure_exists: bool = False) -> None: ...
143

144
# Platform-specific implementations
145
class Unix(PlatformDirsABC): ...
146
class Windows(PlatformDirsABC): ...  
147
class MacOS(PlatformDirsABC): ...
148
class Android(PlatformDirsABC): ...
149

150
# Type aliases for backwards compatibility
151
AppDirs = PlatformDirs
152

153
# Version information
154
__version__: str
155
__version_info__: tuple[int, ...]
156
```