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).

2 files changed, 209 insertions, 0 deletions

diff --git a/docs/reference/pyglib-constants.xml b/docs/reference/pyglib-constants.xml
index a879171..0f1bf8d 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 59a590d..358fa83 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>