Merge pull request #53 from carlwgeorge/state_dir

support XDG_STATE_HOME

appdirs.py

@@ -311,6 +311,48 @@ def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True):
     return path
 
 
+def user_state_dir(appname=None, appauthor=None, version=None, roaming=False):
+    r"""Return full path to the user-specific state dir for this application.
+
+        "appname" is the name of application.
+            If None, just the system directory is returned.
+        "appauthor" (only used on Windows) is the name of the
+            appauthor or distributing body for this application. Typically
+            it is the owning company name. This falls back to appname. You may
+            pass False to disable it.
+        "version" is an optional version path element to append to the
+            path. You might want to use this if you want multiple versions
+            of your app to be able to run independently. If used, this
+            would typically be "<major>.<minor>".
+            Only applied when appname is present.
+        "roaming" (boolean, default False) can be set True to use the Windows
+            roaming appdata directory. That means that for users on a Windows
+            network setup for roaming profiles, this user data will be
+            sync'd on login. See
+            <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>
+            for a discussion of issues.
+
+    Typical user state directories are:
+        Mac OS X:  same as user_data_dir
+        Unix:      ~/.local/state/<AppName>   # or in $XDG_STATE_HOME, if defined
+        Win *:     same as user_data_dir
+
+    For Unix, we follow this Debian proposal <https://wiki.debian.org/XDGBaseDirectorySpecification#state>
+    to extend the XDG spec and support $XDG_STATE_HOME.
+
+    That means, by default "~/.local/state/<AppName>".
+    """
+    if system in ["win32", "darwin"]:
+        path = user_data_dir(appname, appauthor, None, roaming)
+    else:
+        path = os.getenv('XDG_STATE_HOME', os.path.expanduser("~/.local/state"))
+        if appname:
+            path = os.path.join(path, appname)
+    if appname and version:
+        path = os.path.join(path, version)
+    return path
+
+
 def user_log_dir(appname=None, appauthor=None, version=None, opinion=True):
     r"""Return full path to the user-specific log dir for this application.
 
@@ -397,6 +439,11 @@ def user_cache_dir(self):
         return user_cache_dir(self.appname, self.appauthor,
                               version=self.version)
 
+    @property
+    def user_state_dir(self):
+        return user_state_dir(self.appname, self.appauthor,
+                              version=self.version)
+
     @property
     def user_log_dir(self):
         return user_log_dir(self.appname, self.appauthor,
@@ -530,9 +577,13 @@ def _get_win_folder_with_jna(csidl_name):
     appname = "MyApp"
     appauthor = "MyCompany"
 
-    props = ("user_data_dir", "site_data_dir",
-             "user_config_dir", "site_config_dir",
-             "user_cache_dir", "user_log_dir")
+    props = ("user_data_dir",
+             "user_config_dir",
+             "user_cache_dir",
+             "user_state_dir",
+             "user_log_dir",
+             "site_data_dir",
+             "site_config_dir")
 
     print("-- app dirs %s --" % __version__)
 

test/test_api.py

@@ -24,6 +24,8 @@ def test_helpers(self):
             appdirs.site_data_dir('MyApp', 'MyCompany'), STRING_TYPE)
         self.assertIsInstance(
             appdirs.user_cache_dir('MyApp', 'MyCompany'), STRING_TYPE)
+        self.assertIsInstance(
+            appdirs.user_state_dir('MyApp', 'MyCompany'), STRING_TYPE)
         self.assertIsInstance(
             appdirs.user_log_dir('MyApp', 'MyCompany'), STRING_TYPE)
 
@@ -32,6 +34,7 @@ def test_dirs(self):
         self.assertIsInstance(dirs.user_data_dir, STRING_TYPE)
         self.assertIsInstance(dirs.site_data_dir, STRING_TYPE)
         self.assertIsInstance(dirs.user_cache_dir, STRING_TYPE)
+        self.assertIsInstance(dirs.user_state_dir, STRING_TYPE)
         self.assertIsInstance(dirs.user_log_dir, STRING_TYPE)
 
 if __name__ == "__main__":