[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