Add a new *public* main() method

This is mostly compatible with the prior use of `pip.main()` but not
exactly identical.
If the recommended mode of use for invoking `pip` programmatically is to
call `sys.executable` with `-m pip`, then that mode of use *must* be
supported by `pip`.

`subprocess.check_output(...)` behaves very similarly, but of course not
identically, to `pip.main(...)` on pip<9.0.2

This is therefore a mostly compatible interface which alleviates some
transitional hurdles for those using virtualenv or other 3rd party
packages which depend upon `pip.main`.
The only packages which will remain broken are those which use
`pip.main` from an environment in which subprocess cannot be spawned.

The new public `pip.main` is very clearly declared as the *only* public
python API for pip and is noted as having been added for better
backwards compatibility with known (but not supported) usage.

Author: sirosen

src/pip/__init__.py

@@ -1 +1,27 @@
+from __future__ import absolute_import
+import subprocess
+import sys
+
 __version__ = "10.0.0.dev0"
+
+
+def main(*args):
+    """
+    This function is included primarily for backwards compatibility.
+
+    Although anything using `pip.main()` in pip<9.0.2 was engaged in a
+    non-supported mode of use, as a pragmatic accommodation, `pip.main()` is
+    being *added* as a *new* piece of functionality with very similar behaviors
+    and call signature.
+
+    Why use check_call instead of check_output?
+    It's behavior is slightly closer to the older `pip.main()` behavior,
+    printing output information directly to stdout.
+
+    check_call was added in py2.5 and is supported through py3.x , so it's more
+    compatible than some alternatives like subprocess.run (added in py3.5)
+    """
+    return subprocess.check_call([sys.executable, '-m', 'pip'] + list(args))
+
+
+__all__ = ('main',)