Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Base API."""
3from __future__ import annotations
5import os
6from abc import ABC, abstractmethod
7from pathlib import Path
8from typing import TYPE_CHECKING
10if TYPE_CHECKING:
11 from collections.abc import Iterator
12 from typing import Literal
15class PlatformDirsABC(ABC): # noqa: PLR0904
16 """Abstract base class defining all platform directory properties, their :class:`~pathlib.Path` variants, and iterators.
18 Platform-specific subclasses (e.g. :class:`~platformdirs.windows.Windows`, :class:`~platformdirs.macos.MacOS`,
19 :class:`~platformdirs.unix.Unix`) implement the abstract properties to return the appropriate paths for each
20 operating system.
22 """
24 def __init__( # noqa: PLR0913, PLR0917
25 self,
26 appname: str | None = None,
27 appauthor: str | Literal[False] | None = None,
28 version: str | None = None,
29 roaming: bool = False, # noqa: FBT001, FBT002
30 multipath: bool = False, # noqa: FBT001, FBT002
31 opinion: bool = True, # noqa: FBT001, FBT002
32 ensure_exists: bool = False, # noqa: FBT001, FBT002
33 use_site_for_root: bool = False, # noqa: FBT001, FBT002
34 ) -> None:
35 """Create a new platform directory.
37 :param appname: See `appname`.
38 :param appauthor: See `appauthor`.
39 :param version: See `version`.
40 :param roaming: See `roaming`.
41 :param multipath: See `multipath`.
42 :param opinion: See `opinion`.
43 :param ensure_exists: See `ensure_exists`.
44 :param use_site_for_root: See `use_site_for_root`.
46 """
47 self.appname = appname #: The name of the application.
48 self.appauthor = appauthor
49 """The name of the app author or distributing body for this application.
51 Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
53 .. note::
55 On Windows, the directory structure is ``<base>/<appauthor>/<appname>``. When ``appauthor`` is ``None`` (the
56 default), it falls back to ``appname``, resulting in ``<base>/<appname>/<appname>`` (e.g.
57 ``AppData/Local/myapp/myapp``). Pass ``appauthor=False`` to omit the author directory entirely and get
58 ``<base>/<appname>``.
60 """
61 self.version = version
62 """An optional version path element to append to the path.
64 You might want to use this if you want multiple versions of your app to be able to run independently. If used,
65 this would typically be ``<major>.<minor>``.
67 """
68 self.roaming = roaming
69 """Whether to use the roaming appdata directory on Windows.
71 That means that for users on a Windows network setup for roaming profiles, this user data will be synced on
72 login (see `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
74 """
75 self.multipath = multipath
76 """An optional parameter which indicates that the entire list of data dirs should be returned.
78 By default, the first item would only be returned. Only affects ``site_data_dir`` and ``site_config_dir`` on
79 Unix and macOS.
81 """
82 self.opinion = opinion
83 """Whether to use opinionated values.
85 When enabled, appends an additional subdirectory for certain directories: e.g. ``Cache`` for cache and ``Logs``
86 for logs on Windows, ``log`` for logs on Unix.
88 """
89 self.ensure_exists = ensure_exists
90 """Optionally create the directory (and any missing parents) upon access if it does not exist.
92 By default, no directories are created.
94 """
95 self.use_site_for_root = use_site_for_root
96 """Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when running as root (uid 0).
98 Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment
99 variables (e.g. ``XDG_DATA_HOME``) are bypassed for the redirected directories.
101 """
103 def _append_app_name_and_version(self, *base: str) -> str:
104 params = list(base[1:])
105 if self.appname:
106 params.append(self.appname)
107 if self.version:
108 params.append(self.version)
109 path = os.path.join(base[0], *params) # noqa: PTH118
110 self._optionally_create_directory(path)
111 return path
113 def _optionally_create_directory(self, path: str) -> None:
114 if self.ensure_exists:
115 Path(path).mkdir(parents=True, exist_ok=True)
117 def _first_item_as_path_if_multipath(self, directory: str) -> Path:
118 if self.multipath:
119 # If multipath is True, the first path is returned.
120 directory = directory.partition(os.pathsep)[0]
121 return Path(directory)
123 @property
124 @abstractmethod
125 def user_data_dir(self) -> str:
126 """:returns: data directory tied to the user"""
128 @property
129 @abstractmethod
130 def site_data_dir(self) -> str:
131 """:returns: data directory shared by users"""
133 @property
134 def _site_data_dirs(self) -> list[str]:
135 raise NotImplementedError
137 @property
138 @abstractmethod
139 def user_config_dir(self) -> str:
140 """:returns: config directory tied to the user"""
142 @property
143 @abstractmethod
144 def site_config_dir(self) -> str:
145 """:returns: config directory shared by users"""
147 @property
148 def _site_config_dirs(self) -> list[str]:
149 raise NotImplementedError
151 @property
152 @abstractmethod
153 def user_cache_dir(self) -> str:
154 """:returns: cache directory tied to the user"""
156 @property
157 @abstractmethod
158 def site_cache_dir(self) -> str:
159 """:returns: cache directory shared by users"""
161 @property
162 @abstractmethod
163 def user_state_dir(self) -> str:
164 """:returns: state directory tied to the user"""
166 @property
167 @abstractmethod
168 def site_state_dir(self) -> str:
169 """:returns: state directory shared by users"""
171 @property
172 @abstractmethod
173 def user_log_dir(self) -> str:
174 """:returns: log directory tied to the user"""
176 @property
177 @abstractmethod
178 def site_log_dir(self) -> str:
179 """:returns: log directory shared by users"""
181 @property
182 @abstractmethod
183 def user_documents_dir(self) -> str:
184 """:returns: documents directory tied to the user"""
186 @property
187 @abstractmethod
188 def user_downloads_dir(self) -> str:
189 """:returns: downloads directory tied to the user"""
191 @property
192 @abstractmethod
193 def user_pictures_dir(self) -> str:
194 """:returns: pictures directory tied to the user"""
196 @property
197 @abstractmethod
198 def user_videos_dir(self) -> str:
199 """:returns: videos directory tied to the user"""
201 @property
202 @abstractmethod
203 def user_music_dir(self) -> str:
204 """:returns: music directory tied to the user"""
206 @property
207 @abstractmethod
208 def user_desktop_dir(self) -> str:
209 """:returns: desktop directory tied to the user"""
211 @property
212 @abstractmethod
213 def user_projects_dir(self) -> str:
214 """:returns: projects directory tied to the user"""
216 @property
217 @abstractmethod
218 def user_publicshare_dir(self) -> str:
219 """:returns: public share directory tied to the user"""
221 @property
222 @abstractmethod
223 def user_templates_dir(self) -> str:
224 """:returns: templates directory tied to the user"""
226 @property
227 @abstractmethod
228 def user_fonts_dir(self) -> str:
229 """:returns: fonts directory tied to the user"""
231 @property
232 @abstractmethod
233 def user_preference_dir(self) -> str:
234 """:returns: preference directory tied to the user"""
236 @property
237 @abstractmethod
238 def user_bin_dir(self) -> str:
239 """:returns: bin directory tied to the user"""
241 @property
242 @abstractmethod
243 def site_bin_dir(self) -> str:
244 """:returns: bin directory shared by users"""
246 @property
247 @abstractmethod
248 def user_applications_dir(self) -> str:
249 """:returns: applications directory tied to the user"""
251 @property
252 @abstractmethod
253 def site_applications_dir(self) -> str:
254 """:returns: applications directory shared by users"""
256 @property
257 def _site_applications_dirs(self) -> list[str]:
258 raise NotImplementedError
260 @property
261 @abstractmethod
262 def user_runtime_dir(self) -> str:
263 """:returns: runtime directory tied to the user"""
265 @property
266 @abstractmethod
267 def site_runtime_dir(self) -> str:
268 """:returns: runtime directory shared by users"""
270 @property
271 def user_data_path(self) -> Path:
272 """:returns: data path tied to the user"""
273 return Path(self.user_data_dir)
275 @property
276 def site_data_path(self) -> Path:
277 """:returns: data path shared by users"""
278 return Path(self.site_data_dir)
280 @property
281 def user_config_path(self) -> Path:
282 """:returns: config path tied to the user"""
283 return Path(self.user_config_dir)
285 @property
286 def site_config_path(self) -> Path:
287 """:returns: config path shared by users"""
288 return Path(self.site_config_dir)
290 @property
291 def user_cache_path(self) -> Path:
292 """:returns: cache path tied to the user"""
293 return Path(self.user_cache_dir)
295 @property
296 def site_cache_path(self) -> Path:
297 """:returns: cache path shared by users"""
298 return Path(self.site_cache_dir)
300 @property
301 def user_state_path(self) -> Path:
302 """:returns: state path tied to the user"""
303 return Path(self.user_state_dir)
305 @property
306 def site_state_path(self) -> Path:
307 """:returns: state path shared by users"""
308 return Path(self.site_state_dir)
310 @property
311 def user_log_path(self) -> Path:
312 """:returns: log path tied to the user"""
313 return Path(self.user_log_dir)
315 @property
316 def site_log_path(self) -> Path:
317 """:returns: log path shared by users"""
318 return Path(self.site_log_dir)
320 @property
321 def user_documents_path(self) -> Path:
322 """:returns: documents path tied to the user"""
323 return Path(self.user_documents_dir)
325 @property
326 def user_downloads_path(self) -> Path:
327 """:returns: downloads path tied to the user"""
328 return Path(self.user_downloads_dir)
330 @property
331 def user_pictures_path(self) -> Path:
332 """:returns: pictures path tied to the user"""
333 return Path(self.user_pictures_dir)
335 @property
336 def user_videos_path(self) -> Path:
337 """:returns: videos path tied to the user"""
338 return Path(self.user_videos_dir)
340 @property
341 def user_music_path(self) -> Path:
342 """:returns: music path tied to the user"""
343 return Path(self.user_music_dir)
345 @property
346 def user_desktop_path(self) -> Path:
347 """:returns: desktop path tied to the user"""
348 return Path(self.user_desktop_dir)
350 @property
351 def user_projects_path(self) -> Path:
352 """:returns: projects path tied to the user"""
353 return Path(self.user_projects_dir)
355 @property
356 def user_publicshare_path(self) -> Path:
357 """:returns: public share path tied to the user"""
358 return Path(self.user_publicshare_dir)
360 @property
361 def user_templates_path(self) -> Path:
362 """:returns: templates path tied to the user"""
363 return Path(self.user_templates_dir)
365 @property
366 def user_fonts_path(self) -> Path:
367 """:returns: fonts path tied to the user"""
368 return Path(self.user_fonts_dir)
370 @property
371 def user_preference_path(self) -> Path:
372 """:returns: preference path tied to the user"""
373 return Path(self.user_preference_dir)
375 @property
376 def user_bin_path(self) -> Path:
377 """:returns: bin path tied to the user"""
378 return Path(self.user_bin_dir)
380 @property
381 def site_bin_path(self) -> Path:
382 """:returns: bin path shared by users"""
383 return Path(self.site_bin_dir)
385 @property
386 def user_applications_path(self) -> Path:
387 """:returns: applications path tied to the user"""
388 return Path(self.user_applications_dir)
390 @property
391 def site_applications_path(self) -> Path:
392 """:returns: applications path shared by users"""
393 return Path(self.site_applications_dir)
395 @property
396 def user_runtime_path(self) -> Path:
397 """:returns: runtime path tied to the user"""
398 return Path(self.user_runtime_dir)
400 @property
401 def site_runtime_path(self) -> Path:
402 """:returns: runtime path shared by users"""
403 return Path(self.site_runtime_dir)
405 def iter_config_dirs(self) -> Iterator[str]:
406 """:yield: all user and site configuration directories."""
407 yield self.user_config_dir
408 yield self.site_config_dir
410 def iter_data_dirs(self) -> Iterator[str]:
411 """:yield: all user and site data directories."""
412 yield self.user_data_dir
413 yield self.site_data_dir
415 def iter_cache_dirs(self) -> Iterator[str]:
416 """:yield: all user and site cache directories."""
417 yield self.user_cache_dir
418 yield self.site_cache_dir
420 def iter_state_dirs(self) -> Iterator[str]:
421 """:yield: all user and site state directories."""
422 yield self.user_state_dir
423 yield self.site_state_dir
425 def iter_log_dirs(self) -> Iterator[str]:
426 """:yield: all user and site log directories."""
427 yield self.user_log_dir
428 yield self.site_log_dir
430 def iter_runtime_dirs(self) -> Iterator[str]:
431 """:yield: all user and site runtime directories."""
432 yield self.user_runtime_dir
433 yield self.site_runtime_dir
435 def iter_config_paths(self) -> Iterator[Path]:
436 """:yield: all user and site configuration paths."""
437 for path in self.iter_config_dirs():
438 yield Path(path)
440 def iter_data_paths(self) -> Iterator[Path]:
441 """:yield: all user and site data paths."""
442 for path in self.iter_data_dirs():
443 yield Path(path)
445 def iter_cache_paths(self) -> Iterator[Path]:
446 """:yield: all user and site cache paths."""
447 for path in self.iter_cache_dirs():
448 yield Path(path)
450 def iter_state_paths(self) -> Iterator[Path]:
451 """:yield: all user and site state paths."""
452 for path in self.iter_state_dirs():
453 yield Path(path)
455 def iter_log_paths(self) -> Iterator[Path]:
456 """:yield: all user and site log paths."""
457 for path in self.iter_log_dirs():
458 yield Path(path)
460 def iter_runtime_paths(self) -> Iterator[Path]:
461 """:yield: all user and site runtime paths."""
462 for path in self.iter_runtime_dirs():
463 yield Path(path)