Add API calls that return pathlib.Path instead of str objects

CHANGES.rst

@@ -1,6 +1,21 @@
 platformdirs Changelog
 ======================
 
+platformdirs 2.2.0
+------------------
+- [Issue 3] Add ``*_path`` API, returning :class:`pathlib.Path <pathlib.Path>` objects instead of :class:`str`
+  - by `@papr <https://github.com/papr/>`_
+
+  * **NEW** :func:`user_data_path <platformdirs.user_data_path>`
+  * **NEW** :func:`user_config_path <platformdirs.user_config_path>`
+  * **NEW** :func:`user_cache_path <platformdirs.user_cache_path>`
+  * **NEW** :func:`user_state_path <platformdirs.user_state_path>`
+  * **NEW** :func:`user_log_path <platformdirs.user_log_path>`
+  * **NEW** :func:`site_data_path <platformdirs.site_data_path>` (**Note:** Always returns first item, even if the
+    ``multipath`` argument is set to ``True``)
+  * **NEW** :func:`site_config_path <platformdirs.site_config_path>`
+  * **NEW** Add the according properties to :class:`PlatformDirsABC <platformdirs.api.PlatformDirsABC>`
+
 platformdirs 2.1.0
 ------------------
 - Add ``readthedocs.org`` documentation via Sphinx

docs/api.rst

@@ -10,26 +10,31 @@ User data directory
 -------------------
 
 .. autofunction:: platformdirs.user_data_dir
+.. autofunction:: platformdirs.user_data_path
 
 User config directory
 ---------------------
 
 .. autofunction:: platformdirs.user_config_dir
+.. autofunction:: platformdirs.user_config_path
 
 Cache directory
 -------------------
 
 .. autofunction:: platformdirs.user_cache_dir
+.. autofunction:: platformdirs.user_cache_path
 
 State directory
 -------------------
 
 .. autofunction:: platformdirs.user_state_dir
+.. autofunction:: platformdirs.user_state_path
 
 Logs directory
 -------------------
 
 .. autofunction:: platformdirs.user_log_dir
+.. autofunction:: platformdirs.user_log_path
 
 Shared directories
 ~~~~~~~~~~~~~~~~~~
@@ -40,11 +45,13 @@ Shared data directory
 ---------------------
 
 .. autofunction:: platformdirs.site_data_dir
+.. autofunction:: platformdirs.site_data_path
 
 Shared config directory
 -----------------------
 
 .. autofunction:: platformdirs.site_config_dir
+.. autofunction:: platformdirs.site_config_path
 
 Platforms
 ~~~~~~~~~

src/platformdirs/__init__.py

@@ -5,6 +5,7 @@
 import importlib
 import os
 import sys
+from pathlib import Path
 from typing import TYPE_CHECKING, Optional, Type, Union
 
 if TYPE_CHECKING:
@@ -143,6 +144,118 @@ def user_log_dir(
     return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_dir
 
 
+def user_data_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    roaming: bool = False,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
+    :returns: data directory tied to the user
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_data_path
+
+
+def site_data_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    multipath: bool = False,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
+    :returns: data directory shared by users
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_data_path
+
+
+def user_config_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    roaming: bool = False,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
+    :returns: config directory tied to the user
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_config_path
+
+
+def site_config_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    multipath: bool = False,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
+    :returns: config directory shared by the users
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_path
+
+
+def user_cache_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    opinion: bool = True,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+    :returns: cache directory tied to the user
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_path
+
+
+def user_state_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    roaming: bool = False,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
+    :returns: state directory tied to the user
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_state_path
+
+
+def user_log_path(
+    appname: Optional[str] = None,
+    appauthor: Union[str, None, "Literal[False]"] = None,
+    version: Optional[str] = None,
+    opinion: bool = True,
+) -> Path:
+    """
+    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+    :returns: log directory tied to the user
+    """
+    return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_path
+
+
 __all__ = [
     "__version__",
     "__version_info__",
@@ -156,4 +269,11 @@ def user_log_dir(
     "user_log_dir",
     "site_data_dir",
     "site_config_dir",
+    "user_data_path",
+    "user_config_path",
+    "user_cache_path",
+    "user_state_path",
+    "user_log_path",
+    "site_data_path",
+    "site_config_path",
 ]

src/platformdirs/api.py

@@ -1,6 +1,7 @@
 import os
 import sys
 from abc import ABC, abstractmethod
+from pathlib import Path
 from typing import Optional, Union
 
 if sys.version_info >= (3, 8):  # pragma: no branch
@@ -51,7 +52,10 @@ def __init__(
         self.multipath = multipath
         """
         An optional parameter only applicable to Unix/Linux which indicates that the entire list of data dirs should be
-        returned. By default, the first item would only be returned.
+        returned. By default, the first item would only be returned. This parameter does not affect the
+        :class:`pathlib.Path <pathlib.Path>`-returning methods, e.g. :meth:`platformdirs.site_data_path`. These always
+        return the first item. See `platformdirs/platformdirs#24
+        <https://github.com/platformdirs/platformdirs/issues/24>`_ for a discussion.
         """
         self.opinion = opinion  #: A flag to indicating to use opinionated values.
 
@@ -97,3 +101,43 @@ def user_state_dir(self) -> str:
     @abstractmethod
     def user_log_dir(self) -> str:
         """:return: log directory tied to the user"""
+
+    @property
+    def user_data_path(self) -> Path:
+        """:return: data directory tied to the user"""
+        return Path(self.user_data_dir)
+
+    @property
+    def site_data_path(self) -> Path:
+        """:return: data directory shared by users"""
+        site_data_dir = self.site_data_dir
+        if self.multipath:
+            # If multipath is True, the first path is returned. See
+            # https://github.com/platformdirs/platformdirs/issues/24 for a discussion.
+            site_data_dir = site_data_dir.split(os.pathsep)[0]
+        return Path(site_data_dir)
+
+    @property
+    def user_config_path(self) -> Path:
+        """:return: config directory tied to the user"""
+        return Path(self.user_config_dir)
+
+    @property
+    def site_config_path(self) -> Path:
+        """:return: config directory shared by the users"""
+        return Path(self.site_config_dir)
+
+    @property
+    def user_cache_path(self) -> Path:
+        """:return: cache directory tied to the user"""
+        return Path(self.user_cache_dir)
+
+    @property
+    def user_state_path(self) -> Path:
+        """:return: state directory tied to the user"""
+        return Path(self.user_state_dir)
+
+    @property
+    def user_log_path(self) -> Path:
+        """:return: log directory tied to the user"""
+        return Path(self.user_log_dir)

tests/conftest.py

@@ -13,12 +13,27 @@
     "site_config_dir",
 )
 
+PROPS_PATH = (
+    "user_data_path",
+    "user_config_path",
+    "user_cache_path",
+    "user_state_path",
+    "user_log_path",
+    "site_data_path",
+    "site_config_path",
+)
+
 
 @pytest.fixture(params=PROPS)
 def func(request: SubRequest) -> str:
     return cast(str, request.param)
 
 
+@pytest.fixture(params=PROPS_PATH)
+def func_path(request: SubRequest) -> str:
+    return cast(str, request.param)
+
+
 @pytest.fixture()
 def props() -> Tuple[str, ...]:
     return PROPS

tests/test_api.py

@@ -1,3 +1,4 @@
+from pathlib import Path
 from typing import Optional
 
 import pytest
@@ -24,6 +25,18 @@ def test_property_result_is_str(func: str) -> None:
     assert isinstance(result, str)
 
 
+def test_method_result_is_path(func_path: str) -> None:
+    method = getattr(platformdirs, func_path)
+    result = method("MyApp", "MyCompany")
+    assert isinstance(result, Path)
+
+
+def test_property_result_is_path(func_path: str) -> None:
+    dirs = platformdirs.PlatformDirs("MyApp", "MyCompany", version="1.0")
+    result = getattr(dirs, func_path)
+    assert isinstance(result, Path)
+
+
 @pytest.mark.parametrize("root", ["A", "/system", None])
 @pytest.mark.parametrize("data", ["D", "/data", None])
 def test_android_active(monkeypatch: MonkeyPatch, root: Optional[str], data: Optional[str]) -> None:

whitelist.txt

@@ -23,6 +23,7 @@ normpath
 ord
 param
 params
+pathlib
 pathsep
 platformdirs
 pyjnius