From 8b87f8728aa341e5a765f1eb52181660e2936868 Mon Sep 17 00:00:00 2001
From: Paul Moore
Date: Thu, 12 Dec 2019 09:10:51 +0000
Subject: [PATCH 1/3] Add a comment showing how to call main using runpy
---
...a054cec-e4d6-4494-a554-90a2c0bee837.trivial | 0
src/pip/_internal/main.py | 18 ++++++++++++++++++
2 files changed, 18 insertions(+)
create mode 100644 news/6a054cec-e4d6-4494-a554-90a2c0bee837.trivial
diff --git a/news/6a054cec-e4d6-4494-a554-90a2c0bee837.trivial b/news/6a054cec-e4d6-4494-a554-90a2c0bee837.trivial
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/src/pip/_internal/main.py b/src/pip/_internal/main.py
index 1e922402a0b..fe0bcf09ff0 100644
--- a/src/pip/_internal/main.py
+++ b/src/pip/_internal/main.py
@@ -19,6 +19,24 @@
logger = logging.getLogger(__name__)
+# Do not run this directly! Running pip in-process is unsupported and
+# unsafe.
+#
+# Also, the location of this function may change, so calling it directly
+# is not portable across different pip versions. If you have to call
+# this function, and understand and accept the implications of doing so,
+# the best approach is to use runpy as follows:
+#
+# sys.argv = ["pip", your, args, here]
+# runpy.run_module("pip", run_name="__main__")
+#
+# Note that this will exit the process after running, unlike a direct
+# call to main.
+#
+# This still has all of the issues with running pip in-process, but
+# ensures that you don’t rely on the (internal) name of the main
+# function.
+
def main(args=None):
if args is None:
args = sys.argv[1:]
From 80836a4cae328d1b302a3a49e8679406b10bd441 Mon Sep 17 00:00:00 2001
From: Paul Moore
Date: Thu, 12 Dec 2019 09:31:13 +0000
Subject: [PATCH 2/3] Remove non-ASCII character in comment
---
src/pip/_internal/main.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/pip/_internal/main.py b/src/pip/_internal/main.py
index fe0bcf09ff0..ff1df6d6b62 100644
--- a/src/pip/_internal/main.py
+++ b/src/pip/_internal/main.py
@@ -34,7 +34,7 @@
# call to main.
#
# This still has all of the issues with running pip in-process, but
-# ensures that you don’t rely on the (internal) name of the main
+# ensures that you don't rely on the (internal) name of the main
# function.
def main(args=None):
From 241a3cb6f2730ba829ec5d375962c5190d49727e Mon Sep 17 00:00:00 2001
From: Paul Moore
Date: Thu, 12 Dec 2019 10:50:58 +0000
Subject: [PATCH 3/3] Update wording based on review comments
---
src/pip/_internal/main.py | 32 ++++++++++++++++++++------------
1 file changed, 20 insertions(+), 12 deletions(-)
diff --git a/src/pip/_internal/main.py b/src/pip/_internal/main.py
index ff1df6d6b62..855569f3101 100644
--- a/src/pip/_internal/main.py
+++ b/src/pip/_internal/main.py
@@ -19,23 +19,31 @@
logger = logging.getLogger(__name__)
-# Do not run this directly! Running pip in-process is unsupported and
-# unsafe.
-#
-# Also, the location of this function may change, so calling it directly
-# is not portable across different pip versions. If you have to call
-# this function, and understand and accept the implications of doing so,
-# the best approach is to use runpy as follows:
+# Do not import and use main() directly! Using it directly is actively
+# discouraged by pip's maintainers. The name, location and behavior of
+# this function is subject to change, so calling it directly is not
+# portable across different pip versions.
+
+# In addition, running pip in-process is unsupported and unsafe. This is
+# elaborated in detail at
+# https://pip.pypa.io/en/stable/user_guide/#using-pip-from-your-program.
+# That document also provides suggestions that should work for nearly
+# all users that are considering importing and using main() directly.
+
+# However, we know that certain users will still want to invoke pip
+# in-process. If you understand and accept the implications of using pip
+# in an unsupported manner, the best approach is to use runpy to avoid
+# depending on the exact location of this entry point.
+
+# The following example shows how to use runpy to invoke pip in that
+# case:
#
# sys.argv = ["pip", your, args, here]
# runpy.run_module("pip", run_name="__main__")
#
# Note that this will exit the process after running, unlike a direct
-# call to main.
-#
-# This still has all of the issues with running pip in-process, but
-# ensures that you don't rely on the (internal) name of the main
-# function.
+# call to main. As it is not safe to do any processing after calling
+# main, this should not be an issue in practice.
def main(args=None):
if args is None: