From Fedora Project Wiki
(Move the list of macros to detailed description)
Line 48: Line 48:
== Detailed Description ==
== Detailed Description ==
<!-- Expand on the summary, if appropriate.  A couple sentences suffices to explain the goal, but the more details you can provide the better. -->
<!-- Expand on the summary, if appropriate.  A couple sentences suffices to explain the goal, but the more details you can provide the better. -->
All Python 3 shebang RPM macros are changed to contain one more flag: `-P`. Previously, they contained `-s`, now they will contain `-sP`.
From the [https://docs.python.org/3.11/using/cmdline.html#cmdoption-P documentation for the `-P` option]:
> Don’t prepend a potentially unsafe path to `sys.path`:
>
> * `python -m module` command line: Don’t prepend the current working directory.
> * `python script.py` command line: Don’t prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.
> * `python -c code` and `python` (REPL) command lines: Don’t prepend an empty string, which means the current working directory.
In shebangs, only the middle option (''don’t prepend the script’s directory'') is relevant.
Consider the following executbale script installed as `/usr/bin/let-there-be-fun`:
#! /usr/bin/python3 -s
import abc
...
When the script is directly executed (e.g. by running `let-there-be-fun` from the console), the script's directory (`/usr/bin`) is prepended to `sys.path`. Python tries to locate an importable `abc` module in `/usr/bin` first. This can cause real issues: https://bugzilla.redhat.com/2057340 https://github.com/benjaminp/six/issues/359
When the shebang includes `-P`:
#! /usr/bin/python3 -sP
import abc
...
The script's directory (`/usr/bin`) is '''not''' prepended to `sys.path`. The change owners consider this approach safer for the majority of Fedora's RPM packages.


=== List of RPM macros that will gain `-P` ===
=== List of RPM macros that will gain `-P` ===
Line 57: Line 86:
* `%{py_shbang_opts_nodash}`
* `%{py_shbang_opts_nodash}`
* `%{py_shebang_flags}`
* `%{py_shebang_flags}`
=== Opting out ===
If the new behavior is not desirable to your package, use `sed` to remove the `P` part of the flags.
If you use the [https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/ current Python packaging guidelines], e.g. `%pyproject_wheel` and `%pyproject_install`, use:
# Don't add -P to Python shebang
# This package only works when /usr/bin is in sys.path (use your own rationale here)
%global py3_shebang_flags %(echo %py3_shebang_flags | sed s/P//)
If you use the [https://docs.fedoraproject.org/en-US/packaging-guidelines/Python_201x/ 201x-era Python packaging guidelines], e.g. `%py3_build` and `%py3_install`, use:
# Don't add -P to Python shebang
# This package only works when /usr/bin is in sys.path (use your own rationale here)
%global py3_shbang_opts %(echo %py3_shbang_opts | sed s/P//)
(The only difference is the name of the macro.)
=== Opting in ===
If you use the [https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/ current Python packaging guidelines], e.g. `%pyproject_wheel` and `%pyproject_install`, the standard set of Python shebang flags is applied to all files with Python shebangs installed in `/usr/bin/`.
If you use the [https://docs.fedoraproject.org/en-US/packaging-guidelines/Python_201x/ 201x-era Python packaging guidelines], e.g. `%py3_build` and `%py3_install`, the standard set of Python shebang flags might be applied to some files and not applied to others depending on the exact structure of the packaged software.
If you wish to explicitly apply the standard set of Python shebang flags on a certain file that is not handled automatically, use [https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/#py3_shebang_fix the `%py3_shebang_fix` macro].


== Feedback ==
== Feedback ==

Revision as of 14:34, 10 May 2022


Python: Add -P to default shebangs

Important.png
This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.

Summary

The -P flag will be added to the Python shebang macros (%{py3_shbang_opts}, %{py3_shebang_flags}, ...). Packages that adhere to those macros will change their Python shbanegs from #! /usr/bin/python3 -s to #! /usr/bin/python3 -sP and as a result, will no longer have the directory of the script (such as /usr/bin) in sys.path. An opt-out mechanism exists.

Owner


Current status

  • Targeted release: Fedora Linux 37
  • Last updated: 2022-05-10
  • FESCo issue: <will be assigned by the Wrangler>
  • Tracker bug: <will be assigned by the Wrangler>
  • Release notes tracker: <will be assigned by the Wrangler>

Detailed Description

All Python 3 shebang RPM macros are changed to contain one more flag: -P. Previously, they contained -s, now they will contain -sP.

From the documentation for the -P option:

> Don’t prepend a potentially unsafe path to sys.path: > > * python -m module command line: Don’t prepend the current working directory. > * python script.py command line: Don’t prepend the script’s directory. If it’s a symbolic link, resolve symbolic links. > * python -c code and python (REPL) command lines: Don’t prepend an empty string, which means the current working directory.

In shebangs, only the middle option (don’t prepend the script’s directory) is relevant.

Consider the following executbale script installed as /usr/bin/let-there-be-fun:

#! /usr/bin/python3 -s
import abc
...

When the script is directly executed (e.g. by running let-there-be-fun from the console), the script's directory (/usr/bin) is prepended to sys.path. Python tries to locate an importable abc module in /usr/bin first. This can cause real issues: https://bugzilla.redhat.com/2057340 https://github.com/benjaminp/six/issues/359

When the shebang includes -P:


#! /usr/bin/python3 -sP
import abc
...

The script's directory (/usr/bin) is not prepended to sys.path. The change owners consider this approach safer for the majority of Fedora's RPM packages.

List of RPM macros that will gain -P

  • %{py3_shbang_opts}
  • %{py3_shbang_opts_nodash}
  • %{py3_shebang_flags}
  • %{py_shbang_opts}
  • %{py_shbang_opts_nodash}
  • %{py_shebang_flags}

Opting out

If the new behavior is not desirable to your package, use sed to remove the P part of the flags.

If you use the current Python packaging guidelines, e.g. %pyproject_wheel and %pyproject_install, use:

# Don't add -P to Python shebang
# This package only works when /usr/bin is in sys.path (use your own rationale here)
%global py3_shebang_flags %(echo %py3_shebang_flags | sed s/P//)


If you use the 201x-era Python packaging guidelines, e.g. %py3_build and %py3_install, use:

# Don't add -P to Python shebang
# This package only works when /usr/bin is in sys.path (use your own rationale here)
%global py3_shbang_opts %(echo %py3_shbang_opts | sed s/P//)

(The only difference is the name of the macro.)

Opting in

If you use the current Python packaging guidelines, e.g. %pyproject_wheel and %pyproject_install, the standard set of Python shebang flags is applied to all files with Python shebangs installed in /usr/bin/.

If you use the 201x-era Python packaging guidelines, e.g. %py3_build and %py3_install, the standard set of Python shebang flags might be applied to some files and not applied to others depending on the exact structure of the packaged software.

If you wish to explicitly apply the standard set of Python shebang flags on a certain file that is not handled automatically, use the %py3_shebang_fix macro.

Feedback

Benefit to Fedora

Scope

  • Proposal owners:
  • Other developers:
  • Policies and guidelines: N/A (not needed for this Change)
  • Trademark approval: N/A (not needed for this Change)
  • Alignment with Objectives:

Upgrade/compatibility impact

How To Test

User Experience

Dependencies

Contingency Plan

  • Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
  • Contingency deadline: N/A (not a System Wide Change)
  • Blocks release? N/A (not a System Wide Change), Yes/No


Documentation

N/A (not a System Wide Change)

Release Notes