0
# User Media Directories
1

2
Access to standard user media directories like Documents, Downloads, Pictures, Videos, Music, and Desktop. These provide system-appropriate locations for user content regardless of platform, following OS conventions for where users typically store their personal files.
3

4
## Capabilities
5

6
### Media Directory Functions
7

8
Simple functions that return standard user media directory paths. These directories are user-specific and don't require application identification since they represent standard system locations.
9

10
```python { .api }
11
def user_documents_dir() -> str:
12
    """
13
    Return documents directory tied to the user.
14
    
15
    Returns:
16
    Platform-appropriate user documents directory path
17
    
18
    Examples:
19
    - Unix: ~/Documents
20
    - Windows: %USERPROFILE%\Documents
21
    - macOS: ~/Documents
22
    """
23

24
def user_downloads_dir() -> str:
25
    """
26
    Return downloads directory tied to the user.
27
    
28
    Returns:
29
    Platform-appropriate user downloads directory path
30
    
31
    Examples:
32
    - Unix: ~/Downloads
33
    - Windows: %USERPROFILE%\Downloads  
34
    - macOS: ~/Downloads
35
    """
36

37
def user_pictures_dir() -> str:
38
    """
39
    Return pictures directory tied to the user.
40
    
41
    Returns:
42
    Platform-appropriate user pictures directory path
43
    
44
    Examples:
45
    - Unix: ~/Pictures
46
    - Windows: %USERPROFILE%\Pictures
47
    - macOS: ~/Pictures
48
    """
49

50
def user_videos_dir() -> str:
51
    """
52
    Return videos directory tied to the user.
53
    
54
    Returns:
55
    Platform-appropriate user videos directory path
56
    
57
    Examples:
58
    - Unix: ~/Videos
59
    - Windows: %USERPROFILE%\Videos
60
    - macOS: ~/Movies
61
    """
62

63
def user_music_dir() -> str:
64
    """
65
    Return music directory tied to the user.
66
    
67
    Returns:
68
    Platform-appropriate user music directory path
69
    
70
    Examples:
71
    - Unix: ~/Music
72
    - Windows: %USERPROFILE%\Music
73
    - macOS: ~/Music
74
    """
75

76
def user_desktop_dir() -> str:
77
    """
78
    Return desktop directory tied to the user.
79
    
80
    Returns:
81
    Platform-appropriate user desktop directory path
82
    
83
    Examples:
84
    - Unix: ~/Desktop
85
    - Windows: %USERPROFILE%\Desktop
86
    - macOS: ~/Desktop
87
    """
88
```
89

90
### Media Directory Path Functions
91

92
Path versions that return `pathlib.Path` objects instead of strings for advanced path manipulation.
93

94
```python { .api }
95
def user_documents_path() -> Path:
96
    """Return documents path tied to the user."""
97

98
def user_downloads_path() -> Path:
99
    """Return downloads path tied to the user."""
100

101
def user_pictures_path() -> Path:
102
    """Return pictures path tied to the user."""
103

104
def user_videos_path() -> Path:
105
    """Return videos path tied to the user."""
106

107
def user_music_path() -> Path:
108
    """Return music path tied to the user."""
109

110
def user_desktop_path() -> Path:
111
    """Return desktop path tied to the user."""
112
```
113

114
### Object-Oriented Access
115

116
Media directories are also available through PlatformDirs properties for consistency with the OOP interface.
117

118
```python { .api }
119
class PlatformDirs:
120
    @property
121
    def user_documents_dir(self) -> str:
122
        """Documents directory tied to the user."""
123
    
124
    @property
125
    def user_documents_path(self) -> Path:
126
        """Documents path tied to the user."""
127
    
128
    @property
129
    def user_downloads_dir(self) -> str:
130
        """Downloads directory tied to the user."""
131
    
132
    @property
133
    def user_downloads_path(self) -> Path:
134
        """Downloads path tied to the user."""
135
    
136
    @property
137
    def user_pictures_dir(self) -> str:
138
        """Pictures directory tied to the user."""
139
    
140
    @property
141
    def user_pictures_path(self) -> Path:
142
        """Pictures path tied to the user."""
143
    
144
    @property
145
    def user_videos_dir(self) -> str:
146
        """Videos directory tied to the user."""
147
    
148
    @property
149
    def user_videos_path(self) -> Path:
150
        """Videos path tied to the user."""
151
    
152
    @property
153
    def user_music_dir(self) -> str:
154
        """Music directory tied to the user."""
155
    
156
    @property
157
    def user_music_path(self) -> Path:
158
        """Music path tied to the user."""
159
    
160
    @property
161
    def user_desktop_dir(self) -> str:
162
        """Desktop directory tied to the user."""
163
    
164
    @property
165
    def user_desktop_path(self) -> Path:
166
        """Desktop path tied to the user."""
167
```
168

169
## Usage Examples
170

171
```python
172
from platformdirs import (
173
    user_documents_dir, user_downloads_dir, user_pictures_dir,
174
    user_videos_dir, user_music_dir, user_desktop_dir,
175
    user_documents_path, PlatformDirs
176
)
177
from pathlib import Path
178

179
# Functional API - get standard user directories
180
docs = user_documents_dir()
181
downloads = user_downloads_dir()  
182
pictures = user_pictures_dir()
183
videos = user_videos_dir()
184
music = user_music_dir()
185
desktop = user_desktop_dir()
186

187
print(f"Documents: {docs}")
188
print(f"Downloads: {downloads}")
189
print(f"Pictures: {pictures}")
190

191
# Using Path objects for file operations
192
docs_path = user_documents_path()
193
my_file = docs_path / "MyDocument.txt"
194
with open(my_file, 'w') as f:
195
    f.write("Hello, World!")
196

197
# Object-oriented access
198
dirs = PlatformDirs()  # No app name needed for media dirs
199
downloads_path = dirs.user_downloads_path
200
pictures_path = dirs.user_pictures_path
201

202
# Organize files by type
203
def organize_downloads():
204
    downloads = user_downloads_path()
205
    pictures = user_pictures_path()
206
    videos = user_videos_path()
207
    music = user_music_path()
208
    
209
    for file in downloads.iterdir():
210
        if file.suffix.lower() in ['.jpg', '.png', '.gif', '.bmp']:
211
            file.rename(pictures / file.name)
212
        elif file.suffix.lower() in ['.mp4', '.avi', '.mkv', '.mov']:
213
            file.rename(videos / file.name)
214
        elif file.suffix.lower() in ['.mp3', '.wav', '.flac', '.ogg']:
215
            file.rename(music / file.name)
216

217
# Create a desktop shortcut file (Windows .lnk, Unix .desktop)
218
desktop_path = user_desktop_path()
219
if desktop_path.exists():
220
    shortcut = desktop_path / "MyApp.txt"
221
    with open(shortcut, 'w') as f:
222
        f.write("Link to my application")
223
```
224

225
## Platform Behavior
226

227
### Unix/Linux
228
- Follows XDG user directories specification when available
229
- Falls back to common home directory subdirectories
230
- Respects `$XDG_*_DIR` environment variables when set
231

232
### Windows  
233
- Uses Windows Known Folders (CSIDL constants)
234
- Typically located under `%USERPROFILE%`
235
- Localizes directory names based on system language
236

237
### macOS
238
- Follows Apple File System Programming Guide
239
- Uses appropriate directories under user home
240
- Videos directory maps to ~/Movies following macOS convention
241

242
### Android
243
- Maps to appropriate Android storage directories
244
- Considers both internal and external storage locations
245
- Handles Android permission model appropriately
246

247
## Notes
248

249
- Media directories are user-specific and don't require application parameters
250
- These directories typically exist by default on most systems
251
- Some directories may not exist on minimal/server installations
252
- Always check for directory existence before assuming it's available
253
- Consider using `ensure_exists=True` with PlatformDirs if you need to create parent directories