classification
Title: Cross-reference isolated mode from relevant locations
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, mdk, miss-islington, ncoghlan, xtreak
Priority: normal Keywords: easy, patch

Created on 2018-03-18 05:57 by ncoghlan, last changed 2019-09-16 12:30 by mdk.

Files
File name Uploaded Description Edit
33095.patch xtreak, 2018-06-17 05:44
Pull Requests
URL Status Linked Edit
PR 7764 merged xtreak, 2018-06-17 13:42
PR 16180 merged miss-islington, 2019-09-16 12:14
PR 16181 merged mdk, 2019-09-16 12:20
Messages (6)
msg314022 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-03-18 05:57
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
msg319804 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2018-06-17 05:44
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
msg319812 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-06-17 11:40
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.
msg352399 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-09-14 00:35
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/bdd6945d4dbd1fe6a7fcff95f7d6908db7d791a1
msg352540 - (view) Author: miss-islington (miss-islington) Date: 2019-09-16 12:21
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/07186c3959a61c3d73b5ccae431cdd32afe70e5e
msg352542 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-09-16 12:30
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/210dc3bb37ec57a8b8b16ffe0881181138a6e973
History
Date User Action Args
2019-09-16 12:30:36mdksetnosy: + mdk
messages: + msg352542
2019-09-16 12:21:06miss-islingtonsetnosy: + miss-islington
messages: + msg352540
2019-09-16 12:20:26mdksetpull_requests: + pull_request15791
2019-09-16 12:14:22miss-islingtonsetpull_requests: + pull_request15790
2019-09-14 00:35:48ncoghlansetmessages: + msg352399
2018-06-17 13:42:56xtreaksetstage: needs patch -> patch review
pull_requests: + pull_request7372
2018-06-17 11:40:55ncoghlansetmessages: + msg319812
2018-06-17 05:44:46xtreaksetfiles: + 33095.patch

nosy: + xtreak
messages: + msg319804

keywords: + patch
2018-03-18 10:40:23jwilksetnosy: - jwilk
2018-03-18 05:57:16ncoghlancreate