bpo-33944: note about the intended use of code in .pth files (GH-10131) (GH-15942)

miss-islington · native-api · matrixise · commit d1d968d45df1 · 2019-09-11T15:36:50.000+02:00
https://bugs.python.org/issue33944 (cherry picked from commit f9b5840) Co-authored-by: native-api <ivan_pozdeev@mail.ru>
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
@@ -61,6 +61,19 @@ directory rather than a file.  No item is added to ``sys.path`` more than
 once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
 with ``import`` (followed by space or tab) are executed.
 
+.. note::
+
+   An executable line in a :file:`.pth` file is run at every Python startup,
+   regardless of whether a particular module is actually going to be used.
+   Its impact should thus be kept to a minimum.
+   The primary intended purpose of executable lines is to make the
+   corresponding module(s) importable
+   (load 3rd-party import hooks, adjust :envvar:`PATH` etc).
+   Any other initialization is supposed to be done upon a module's
+   actual import, if and when it happens.
+   Limiting a code chunk to a single line is a deliberate measure
+   to discourage putting anything more complex here.
+
 .. index::
    single: package
    triple: path; configuration; file
diff --git a/Misc/NEWS.d/next/Documentation/2018-10-26-18-10-29.bpo-33944.V1YeOA.rst b/Misc/NEWS.d/next/Documentation/2018-10-26-18-10-29.bpo-33944.V1YeOA.rst
@@ -0,0 +1 @@
+Added a note about the intended use of code in .pth files.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Added a note about the intended use of code in .pth files.`