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.

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 dbac79fd7007c6498337ca59fde6c58588bae3dd..91a5494b4a1835a687d67f136dff0bbc4adaf21b 100644 (file)
--- a/man/check-os-release.py
+++ b/man/check-os-release.py
@@ -29,7 +29,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 dd3c39f8762b61dc535eeee0cc38969c5088d0ac..4acd1a9a575722351b05609cac67471bd0df5db0 100644 (file)
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -502,9 +502,23 @@ VERSION_ID=32</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>