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: