From ecb4627f0739a0e12585bccc156f2337084ad60e Mon Sep 17 00:00:00 2001
From: Miro Hrončok <miro@hroncok.cz>
Date: Jul 21 2022 12:14:31 +0000
Subject: [PATCH 1/2] Python: Document %{_py3_shebang_s} and %{_py3_shebang_P}


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 8a61626..71a053b 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -868,32 +868,49 @@ and they *MAY* include extra flags.
 
 If (some of) the default flags from
 <<py3_shebang_flags,the `+%{py3_shebang_flags}+` macro>> are not desirable,
-packages *SHOULD* explicitly redefine the macro to remove them.
+packages *SHOULD* explicitly redefine the macro to remove them by undefining
+the relevant `+%{_py3_shebang_...}+` macro.
 
 Using `+#!%{python3}+` (`+#!/usr/bin/python3+`)
 rather than e.g. `+#!/usr/bin/env python+`
 ensures that the system-wide Python interpreter is used to run the code,
 even if the user modifies `+$PATH+` (e.g. by activating a virtual environment).
 
-By default, `+-%{py3_shebang_flags}+` expands to `+-s+`,
-which means _don’t add user site directory to `+sys.path+`._
+By default, `+-%{py3_shebang_flags}+` expands to `+-sP+`
+(or just `+-s+` on Python version lower than 3.11 and Fedora Linux older than 37).
+
+The `+-s+` flag,
+stored in <<_py3_shebang_s,the `+%{_py3_shebang_s}+` macro>>,
+means _don’t add user site directory to `+sys.path+`._
 That ensures the user’s Python packages
 (e.g. installed by `+pip install --user+`,
 or just placed in the current directory)
 don’t interfere with the RPM installed software.
 Sometimes, such content is desirable, such as with plugins.
-Redefining <<py3_shebang_flags,the `+%{py3_shebang_flags}+` macro>>
-to a set of flags without `+s+`,
+
+The `+-P+` flag,
+stored in <<_py3_shebang_P,the `+%{_py3_shebang_P}+` macro>>,
+means _don’t add the script's directory to `+sys.path+`._
+Sometimes, adding the script's directory to `+sys.path+` is desirable,
+such as with executable Python scripts installed in a custom directory,
+importing each other.
+
+Removing the undesired flag(s) from <<py3_shebang_flags,the `+%{py3_shebang_flags}+` macro>>
 rather than not using the macro at all,
 ensures that existing or future automation won’t add the flag.
-The default set of flags might be extended in the future,
-hence only explicitly removing the undesired flags is more future-proof than emptying the macro:
 
 [source,spec]
 ----
 # Remove -s from Python shebang - ensure that extensions installed with pip
 # to user locations are seen and properly loaded
-%global py3_shebang_flags %(echo %py3_shebang_flags | sed s/s//)
+%undefine _py3_shebang_s
+----
+
+[source,spec]
+----
+# Don't add -P to Python shebangs
+# The executable Python scripts in /usr/share/opt-viewer/ import each other
+%undefine _py3_shebang_P 
 ----
 
 The <<pyproject_install,`+%pyproject_install+` macro>>
@@ -1317,11 +1334,22 @@ See the <<Mandatory macros>> section above for:
 === Shebang macros
 
 [#py3_shebang_flags]
-* `+%{py3_shebang_flags}+` (`+s+`)
+* `+%{py3_shebang_flags}+` (`+sP+` or `+s+` before Fedora Linux 37)
 +
 Flags for `+%{python3}+` to use in shebangs.
-Redefine this macro to use a different set of flags.
-Undefine it to use no flags. See <<Shebangs>> for details.
+See <<Shebangs>> for details.
+Includes flags from several `+%{_py3_shebang_...}+` macros listed here.
+
+[#_py3_shebang_s]
+* `+%{_py3_shebang_s}+` (`+s+`)
++
+Undefine this macro to drop `+s+` from `+%{py3_shebang_flags}+`.
+
+[#_py3_shebang_P]
+* `+%{_py3_shebang_P}+` (`+P+`)
++
+Undefine this macro to drop `+P+` from `+%{py3_shebang_flags}+`.
+Introduced in Fedora Linux 37.
 
 [#py3_shebang_fix]
 * `+%py3_shebang_fix PATHS+` (`+pathfix.py ... PATHS+`)

From 896735e57546a5f83f5c376f8f968ef92c0b0166 Mon Sep 17 00:00:00 2001
From: Miro Hrončok <miro@hroncok.cz>
Date: Jul 21 2022 12:14:31 +0000
Subject: [PATCH 2/2] Python: Document %{python3_cache_tag}


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 71a053b..312f636 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1413,6 +1413,14 @@ A string identifying the architecture/platform.
 This corresponds to the `+MULTIARCH+`
 https://docs.python.org/3/library/sysconfig.html[sysconfig] variable.
 
+[#python3_cache_tag]
+* `+%{python3_cache_tag}+` (e.g. `+cpython-311+`)
++
+Part of the bytecode cache filename that identifies the interpreter.
+This corresponds to the
+https://docs.python.org/3/library/sys.html#sys.implementation[`+sys.implementation.cache_tag+`]
+value.
+
 === Build macros
 
 The “pyproject macros” are most useful