From 28b1ba2c5c57e080fb43699e2da5b31ec8b60681 Mon Sep 17 00:00:00 2001 From: Yusuke Hayashi Date: Wed, 29 Jul 2026 13:42:47 +0900 Subject: [PATCH] gh-131484: Document that a directory or zipfile script stays on sys.path -P, -I and PYTHONSAFEPATH drop the implicit sys.path[0] entries (current directory, script directory, empty string), but a directory or zipfile named as the script argument is still prepended: that entry is used to locate __main__.py and makes other modules stored in the target importable. The -P section currently enumerates only the -m, script and -c/REPL cases. Co-Authored-By: Claude Fable 5 --- Doc/using/cmdline.rst | 16 ++++++++++++---- ...026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst | 2 ++ 2 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 677fbbae3f4219..6d1cd36fcfa902 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -163,10 +163,11 @@ source. added to the start of :data:`sys.path` and the ``__main__.py`` file in that location is executed as the :mod:`__main__` module. - :option:`-I` option can be used to run the script in isolated mode where - :data:`sys.path` contains neither the script's directory nor the user's - site-packages directory. All ``PYTHON*`` environment variables are - ignored, too. + :option:`-I` can be used to run the script in isolated mode. For a Python + file, the containing directory is then omitted from :data:`sys.path`, as + is the user's site-packages directory; a directory or zipfile target + remains, as described under :option:`-P`. All ``PYTHON*`` environment + variables are ignored, too. .. audit-event:: cpython.run_file filename @@ -362,6 +363,13 @@ Miscellaneous options * ``python -c code`` and ``python`` (REPL) command lines: Don't prepend an empty string, which means the current working directory. + If the script name refers to a directory or zipfile (see + :ref:`using-on-interface-options`), the script name is still added to the + start of :data:`sys.path`. This also applies when safe-path mode is + enabled by :option:`-I` or :envvar:`PYTHONSAFEPATH`. The entry is used to + locate ``__main__.py`` and makes other modules stored in the target + importable. + See also the :envvar:`PYTHONSAFEPATH` environment variable, and :option:`-E` and :option:`-I` (isolated) options. diff --git a/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst b/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst new file mode 100644 index 00000000000000..d4c76b89110df2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-07-29-12-50-00.gh-issue-131484.Xk2mVq.rst @@ -0,0 +1,2 @@ +Clarify that a directory or zipfile passed as the script argument remains on +:data:`sys.path` in safe-path and isolated modes.