[issue33095] Cross-reference isolated mode from relevant locations
New submission from Nick Coghlan ncoghlan@gmail.com:
In https://bugs.python.org/issue33053#msg313966, jwilk noted that it isn't obvious from https://docs.python.org/3/using/cmdline.html#cmdoption-m how to keep the current directory from being added to `sys.path` when using the -m switch. The answer is to pass the `-I` switch as well (to activate isolated mode), but there's no cross reference to help readers discover that fact.
https://docs.python.org/3/using/cmdline.html#id2 is the main documentation for isolated mode, so the steps needed to close this issue are:
1. At least add a reference from the -m switch documentation to the -I switch documentation 2. Review the other parts of the `using` docs that describe how `sys.path` is initialised, and reference the -I switch documentation where relevant
---------- assignee: docs@python components: Documentation keywords: easy messages: 314022 nosy: docs@python, jwilk, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Cross-reference isolated mode from relevant locations type: enhancement versions: Python 3.6, Python 3.7, Python 3.8
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Change by Jakub Wilk jwilk@jwilk.net:
---------- nosy: -jwilk
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Karthikeyan Singaravelan tir.karthi@gmail.com added the comment:
There are four parts where I could see sys.path manipulation being mentioned while running scripts :
-c option (https://docs.python.org/3/using/cmdline.html#cmdoption-c) -m option (https://docs.python.org/3/using/cmdline.html#cmdoption-m) - (input option) <script> (running as script)
For some reason I am not able to hyperlink to - and <script> parts since they are not a command line option but a method to execute code. I could sys.path references in windows (https://docs.python.org/3/using/windows.html#finding-modules) where `._pth` file is mentioned to completely override sys.path.
I am new to adding documentation so add in if it needs a simple reference or explain the option which I feel redundant and useful at the same time kind of missing the point of cross-referencing. I am attaching a patch for `-m` and <script> option. Feel free to add comments and if I am missing something.
Thanks
---------- keywords: +patch nosy: +xtreak Added file: https://bugs.python.org/file47644/33095.patch
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Nick Coghlan ncoghlan@gmail.com added the comment:
xtreak: if you're familiar with GitHub workflows, then we now accept docs and code updates as GitHub PRs: https://devguide.python.org/pullrequest/
The parts about running the tests aren't exactly relevant here, what's more relevant is building the documentation: https://devguide.python.org/documenting/#building-the-documentation
In relation to your draft patch, I think that's a good starting point, but for -c and -m, it's the current directory that gets omitted, rather than "the script's directory" (that isn't well defined when anything other than a path is passed in).
For making "-" and "<script>" hyperlinkable, you'll need to add a label definition to the Sphinx source code immediately before those description sections. I'd suggest ".. _cmdarg-dash:" and ".. _cmdarg-script:" so the resulting anchors look similar to the option ones, without being the same.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Change by Karthikeyan Singaravelan tir.karthi@gmail.com:
---------- pull_requests: +7372 stage: needs patch -> patch review
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Nick Coghlan ncoghlan@gmail.com added the comment:
New changeset bdd6945d4dbd1fe6a7fcff95f7d6908db7d791a1 by Nick Coghlan (Xtreak) in branch 'master': bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) https://github.com/python/cpython/commit/bdd6945d4dbd1fe6a7fcff95f7d6908db7d...
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Change by miss-islington mariatta.wijaya+miss-islington@gmail.com:
---------- pull_requests: +15790 pull_request: https://github.com/python/cpython/pull/16180
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Change by Julien Palard julien+python@palard.fr:
---------- pull_requests: +15791 pull_request: https://github.com/python/cpython/pull/16181
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
miss-islington mariatta.wijaya+miss-islington@gmail.com added the comment:
New changeset 07186c3959a61c3d73b5ccae431cdd32afe70e5e by Miss Islington (bot) in branch '3.8': bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) https://github.com/python/cpython/commit/07186c3959a61c3d73b5ccae431cdd32afe...
---------- nosy: +miss-islington
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Julien Palard julien+python@palard.fr added the comment:
New changeset 210dc3bb37ec57a8b8b16ffe0881181138a6e973 by Julien Palard in branch '3.7': [3.7] bpo-33095: Add reference to isolated mode in -m and script option (GH-7764) (GH-16181) https://github.com/python/cpython/commit/210dc3bb37ec57a8b8b16ffe0881181138a...
---------- nosy: +mdk
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
Karthikeyan Singaravelan tir.karthi@gmail.com added the comment:
Closing since PRs were merged. Thanks for the review.
---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue33095 _______________________________________
participants (5)
-
Jakub Wilk -
Julien Palard
-
Karthikeyan Singaravelan
-
miss-islington
-
Nick Coghlan