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

Implements tox-dev#3
papr · Jul 22, 2021 · 2cf6ffe · 2cf6ffe
1 parent 2f20866
commit 2cf6ffe
Show file tree

Hide file tree

Showing 4 changed files with 184 additions and 0 deletions.
diff --git a/src/platformdirs/__init__.py b/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 `roaming <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",
 ]
diff --git a/src/platformdirs/api.py b/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
@@ -97,3 +98,38 @@ 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"""
+        return Path(self.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)
diff --git a/tests/conftest.py b/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
diff --git a/tests/test_api.py b/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: