Update wording based on review comments
@@ -19,23 +19,31 @@ from pip._internal.utils import deprecation
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:
