man: recommend built-in platform.freedesktop_os_release() in our page

Python gained support for reading os-release, let's advertise it a bit more.
Our open-coded example is still useful, but let's not suggest it as the
default implementation.

I added quotes around the printed string because it looks a bit better
this way.

(cherry picked from commit ee6fd6a50922d2b27c97084e1c3f9872d495c273)
(cherry picked from commit d4dd289f821d29415f0057266da48f184a51bb1c)

diff --git a/man/check-os-release-simple.py b/man/check-os-release-simple.py
new file mode 100644 (file)
index 0000000..738b1fd
--- /dev/null
+++ b/man/check-os-release-simple.py
@@ -0,0 +1,12 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: CC0-1.0
+
+import platform
+os_release = platform.freedesktop_os_release()
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'fedora' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Fedora!')

diff --git a/man/check-os-release.py b/man/check-os-release.py
index d009563f025da651bc04bed86445381dbf68771f..68c8f9d890905c2970d478886a2f39223226d98f 100644 (file)
--- a/man/check-os-release.py
+++ b/man/check-os-release.py
@@ -28,7 +28,7 @@ def read_os_release():
 os_release = dict(read_os_release())
 
 pretty_name = os_release.get('PRETTY_NAME', 'Linux')
-print(f'Running on {pretty_name}')
+print(f'Running on {pretty_name!r}')
 
 if 'debian' in [os_release.get('ID', 'linux'),
                 *os_release.get('ID_LIKE', '').split()]:

diff --git a/man/os-release.xml b/man/os-release.xml
index a7c60183aefe1b8b136bf922d9549a629c64413a..adec3e716dcd8f3355ab723457fa3feac2c8bc5b 100644 (file)
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -445,9 +445,23 @@ VARIANT_ID=workstation</programlisting>
 
     <example>
       <title>Reading <filename>os-release</filename> in
-      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
+
+      <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
+
+      <para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release">
+      <function>platform.freedesktop_os_release</function></ulink> for more details.
+      </para>
+    </example>
+
+    <example>
+      <title>Reading <filename>os-release</filename> in
+      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
 
       <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
+
+      <para>Note that the above version that uses the built-in implementation is preferred
+      in most cases, and the open-coded version here is provided for reference.</para>
     </example>
 
   </refsect1>