Wrap four g_get_user_*_dir() functions

Wrap g_get_user_cache_dir(), g_get_user_config_dir(),
g_get_user_data_dir(), g_get_user_special_dir() and the constants
required for the latter.  Document all new functions and constants.
(Bug #575999).

3 files changed, 294 insertions, 0 deletions

diff --git a/docs/reference/pyglib-constants.xml b/docs/reference/pyglib-constants.xml
index a8791719..0f1bf8d6 100644
--- a/docs/reference/pyglib-constants.xml
+++ b/docs/reference/pyglib-constants.xml
@@ -15,6 +15,7 @@
 <xref linkend="glib-io-condition-constants" endterm="glib-io-condition-constants-title"></xref>
 <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref>
 <xref linkend="glib-spawn-flag-constants" endterm="glib-spawn-flag-constants-title"></xref>
+<xref linkend="glib-user-directory-constants" endterm="glib-user-directory-constants-title"></xref>
 <xref linkend="glib-version-constants" endterm="glib-version-constants-title"></xref>
 </programlisting>
 
@@ -192,6 +193,65 @@ of <parameter>argv</parameter> to the child.</simpara>
 
     </refsect2>
 
+    <refsect2 id="glib-user-directory-constants">
+      <title id="glib-user-directory-constants-title">Glib User Directory Constants</title>
+
+      <para>The User Directory constants are integer values that are currently used only as arguments to
+        <link linkend="function-glib--get-user-special-dir"><function>glib.get_user_special_dir</function>()</link>
+        function.  See function documentation for details.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_DESKTOP</literal></term>
+	  <listitem>
+	    <simpara>the user's Desktop directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_DOCUMENTS</literal></term>
+	  <listitem>
+	    <simpara>the user's Documents directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_DOWNLOAD</literal></term>
+	  <listitem>
+	    <simpara>the user's Downloads directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_MUSIC</literal></term>
+	  <listitem>
+	    <simpara>the user's Music directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_PICTURES</literal></term>
+	  <listitem>
+	    <simpara>the user's Pictures directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_PUBLIC_SHARE</literal></term>
+	  <listitem>
+	    <simpara>the user's shared directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_TEMPLATES</literal></term>
+	  <listitem>
+	    <simpara>the user's Templates directory</simpara>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><literal>glib.USER_DIRECTORY_VIDEOS</literal></term>
+	  <listitem>
+	    <simpara>the user's Movies directory</simpara>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </refsect2>
+
     <refsect2 id="glib-version-constants">
       <title id="glib-version-constants-title">Glib Version Constants</title>
       <para>The Version constants specify the version of
diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml
index 59a590dc..358fa832 100644
--- a/docs/reference/pyglib-functions.xml
+++ b/docs/reference/pyglib-functions.xml
@@ -71,6 +71,19 @@ linkend="function-glib--spawn-async">glib.spawn_async</link></methodname>
 linkend="function-glib--get-current-time">glib.get_current_time</link></methodname>
       </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
+          linkend="function-glib--get-user-cache-dir">glib.get_user_cache_dir</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+          linkend="function-glib--get-user-config-dir">glib.get_user_config_dir</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+          linkend="function-glib--get-user-data-dir">glib.get_user_data_dir</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+          linkend="function-glib--get-user-special-dir">glib.get_user_special_dir</link></methodname>
+	<methodparam><parameter role="keyword">directory</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
 linkend="function-glib--main-depth">glib.main_depth</link></methodname>
       </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
@@ -717,6 +730,142 @@ from the epoch.</para>
 
     </refsect2>
 
+    <refsect2 id="function-glib--get-user-cache-dir">
+      <title>glib.get_user_cache_dir</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>glib.get_user_cache_dir</methodname>
+      </methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem>
+            <simpara>
+              a strings with a path to user's cache directory.
+            </simpara>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGObject 2.18 and above.</para>
+      </note>
+
+      <para>Returns a base directory in which to store non-essential,
+        cached data specific to particular user.</para>
+
+      <para>On UNIX platforms this is determined using the mechanisms
+        described in the
+        <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG
+          Base Directory Specification</ulink>.</para>
+    </refsect2>
+
+    <refsect2 id="function-glib--get-user-config-dir">
+      <title>glib.get_user_config_dir</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>glib.get_user_config_dir</methodname>
+      </methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem>
+            <simpara>
+              a strings with a path to user's configuration directory.
+            </simpara>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGObject 2.18 and above.</para>
+      </note>
+
+      <para>Returns a base directory in which to store user-specific
+        application configuration information such as user preferences
+        and settings. </para>
+
+      <para>On UNIX platforms this is determined using the mechanisms
+        described in the
+        <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG
+          Base Directory Specification</ulink>.</para>
+    </refsect2>
+
+    <refsect2 id="function-glib--get-user-data-dir">
+      <title>glib.get_user_data_dir</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>glib.get_user_data_dir</methodname>
+      </methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem>
+            <simpara>
+              a strings with a path to user's data directory.
+            </simpara>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGObject 2.18 and above.</para>
+      </note>
+
+      <para>Returns a base directory in which to access application
+        data such as icons that is customized for a particular
+        user</para>
+
+      <para>On UNIX platforms this is determined using the mechanisms
+        described in the
+        <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG
+          Base Directory Specification</ulink>.</para>
+    </refsect2>
+
+    <refsect2 id="function-glib--get-user-special-dir">
+      <title>glib.get_user_special_dir</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>glib.get_user_special_dir</methodname>
+        <methodparam><parameter>directory</parameter></methodparam>
+      </methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>directory</emphasis>&nbsp;:</term>
+          <listitem>
+            <simpara>
+              the logical id of special directory,
+              see <link linkend="glib-user-directory-constants">User
+              Directory constants</link> for the list of supported
+              values
+            </simpara>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem>
+            <simpara>
+              a strings with a path to the requested directory.
+            </simpara>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGObject 2.18 and above.</para>
+      </note>
+
+      <para>Returns the full path of a special directory using its
+        logical id.</para>
+
+      <para>On Unix this is done using the XDG special user
+        directories.  For compatibility with existing practise,
+        <link linkend="glib-user-directory-constants">glib.USER_DIRECTORY_DESKTOP</link>
+        falls back to <literal>$HOME/Desktop</literal> when XDG
+        special user directories have not been set up.</para>
+
+      <para>Depending on the platform, the user might be able to
+        change the path of the special directory without requiring the
+        session to restart; GLib will not reflect any change once the
+        special directories are loaded.</para>
+    </refsect2>
+
     <refsect2 id="function-glib--main-depth">
       <title>glib.main_depth</title>
       
diff --git a/glib/glibmodule.c b/glib/glibmodule.c
index 8e118aad..5591d361 100644
--- a/glib/glibmodule.c
+++ b/glib/glibmodule.c
@@ -406,6 +406,66 @@ pyglib_get_current_time(PyObject *unused)
     return pyglib_float_from_timeval(timeval);
 }
 
+static PyObject*
+pyglib_get_user_cache_dir(PyObject *self)
+{
+    const char *path = g_get_user_cache_dir();
+
+    if (path)
+        return _PyUnicode_FromString(path);
+    else {
+        Py_INCREF(Py_None);
+        return Py_None;
+    }
+}
+
+static PyObject*
+pyglib_get_user_config_dir(PyObject *self)
+{
+    const char *path = g_get_user_config_dir();
+
+    if (path)
+        return _PyUnicode_FromString(path);
+    else {
+        Py_INCREF(Py_None);
+        return Py_None;
+    }
+}
+
+static PyObject*
+pyglib_get_user_data_dir(PyObject *self)
+{
+    const char *path = g_get_user_data_dir();
+
+    if (path)
+        return _PyUnicode_FromString(path);
+    else {
+        Py_INCREF(Py_None);
+        return Py_None;
+    }
+}
+
+static PyObject *
+pyglib_get_user_special_dir(PyObject *unused, PyObject *args, PyObject *kwargs)
+{
+    static char *kwlist[] = { "directory", NULL };
+    guint directory;
+    const char *path;
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs,
+                                     "i:glib.get_user_special_dir", kwlist,
+                                     &directory))
+        return NULL;
+
+    path = g_get_user_special_dir(directory);
+    if (path)
+        return _PyUnicode_FromString(path);
+    else {
+        Py_INCREF(Py_None);
+        return Py_None;
+    }
+}
+
 static PyObject *
 pyglib_main_depth(PyObject *unused)
 {
@@ -602,6 +662,14 @@ static PyMethodDef _glib_functions[] = {
       (PyCFunction)pyglib_set_prgname, METH_O },
     { "get_current_time",
       (PyCFunction)pyglib_get_current_time, METH_NOARGS },
+    { "get_user_cache_dir",
+      (PyCFunction)pyglib_get_user_cache_dir, METH_NOARGS },
+    { "get_user_config_dir",
+      (PyCFunction)pyglib_get_user_config_dir, METH_NOARGS },
+    { "get_user_data_dir",
+      (PyCFunction)pyglib_get_user_data_dir, METH_NOARGS },
+    { "get_user_special_dir",
+      (PyCFunction)pyglib_get_user_special_dir, METH_VARARGS },
     { "markup_escape_text",
       (PyCFunction)pyglib_markup_escape_text, METH_VARARGS|METH_KEYWORDS },
     { NULL, NULL, 0 }
@@ -749,6 +817,23 @@ pyglib_register_constants(PyObject *m)
 			    G_OPTION_ERROR_BAD_VALUE);
     PyModule_AddIntConstant(m, "OPTION_ERROR_FAILED",
 			    G_OPTION_ERROR_FAILED);
+ 
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_DESKTOP",
+                            G_USER_DIRECTORY_DESKTOP);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_DOCUMENTS",
+                            G_USER_DIRECTORY_DOCUMENTS);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_DOWNLOAD",
+                            G_USER_DIRECTORY_DOWNLOAD);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_MUSIC",
+                            G_USER_DIRECTORY_MUSIC);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_PICTURES",
+                            G_USER_DIRECTORY_PICTURES);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_PUBLIC_SHARE",
+                            G_USER_DIRECTORY_PUBLIC_SHARE);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_TEMPLATES",
+                            G_USER_DIRECTORY_TEMPLATES);
+    PyModule_AddIntConstant(m, "USER_DIRECTORY_VIDEOS",
+                            G_USER_DIRECTORY_VIDEOS);
 
     PyModule_AddStringConstant(m, "OPTION_REMAINING",
 			       G_OPTION_REMAINING);