Merge pull request #3863 from MikeMcQuaid/python3-changesHEADmaster

Adjust docs and more internal code for Python 3.

1 files changed, 15 insertions, 18 deletions

diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md
index eb96e5758..6d24b214f 100644
--- a/docs/Homebrew-and-Python.md
+++ b/docs/Homebrew-and-Python.md
@@ -4,33 +4,32 @@ This page describes how Python is handled in Homebrew for users. See [Python for
 
 Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS system Python.
 
-Homebrew provides formulae to brew a more up-to-date Python 2.7.x and 3.x.
+Homebrew provides formulae to brew 3.x and a more up-to-date Python 2.7.x.
 
-**Important:** If you choose to install a Python which isn't either of these two (system Python or brewed Python), the Homebrew team can only provide limited support.
+**Important:** If you choose to install a Python which isn't either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur.
 
-## Python 2.x or Python 3.x
+## Python 3.x or Python 2.x
 Homebrew provides one formula for Python 2.7.x and another for Python 3.x. The executables are organized as follows so that Python 2 and Python 3 can both be installed without conflict:
-* `python` points to the macOS system Python (with no manual PATH modification)
+* `python` and `python3` point to Homebrew's Python 3.x (if installed) otherwise the macOS system Python
 * `python2` points to Homebrew's Python 2.7.x (if installed)
-* `python3` points to Homebrew's Python 3.x (if installed)
+* `pip` and `pip3` point to Homebrew's Python 3.x's pip (if installed)
 * `pip2` points to Homebrew's Python 2.7.x's pip (if installed)
-* `pip3` points to Homebrew's Python 3.x's pip (if installed)
 
 ([Wondering which one to choose?](https://wiki.python.org/moin/Python2orPython3))
 
 ## Setuptools, Pip, etc.
-The Python formulae install [pip](http://www.pip-installer.org) (as `pip2` or `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
+The Python formulae install [pip](http://www.pip-installer.org) (as `pip` or `pip2`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
 
 Setuptools can be updated via pip, without having to re-brew Python:
 
 ```sh
-python2 -m pip install --upgrade setuptools
+python -m pip install --upgrade setuptools
 ```
 
 Similarly, pip can be used to upgrade itself via:
 
 ```sh
-python2 -m pip install --upgrade pip
+python -m pip install --upgrade pip
 ```
 
 ### Note on `pip install --user`
@@ -39,7 +38,7 @@ The normal `pip install --user` is disabled for brewed Python. This is because o
 A possible workaround (which puts executable scripts in `~/Library/Python/<X>.<Y>/bin`) is:
 
 ```sh
-python2 -m pip install --user --install-option="--prefix=" <package-name>
+python -m pip install --user --install-option="--prefix=" <package-name>
 ```
 
 ## `site-packages` and the `PYTHONPATH`
@@ -49,12 +48,12 @@ The `site-packages` is a directory that contains Python modules (especially bind
 $(brew --prefix)/lib/pythonX.Y/site-packages
 ```
 
-So, for Python 2.7.x, you'll find it at `/usr/local/lib/python2.7/site-packages`.
+So, for Python 3.6.x, you'll find it at `/usr/local/lib/python3.6/site-packages`.
 
-Python 2.7 also searches for modules in:
+Python 3.6 also searches for modules in:
 
-- `/Library/Python/2.7/site-packages`
-- `~/Library/Python/2.7/lib/python/site-packages`
+- `/Library/Python/3.6/site-packages`
+- `~/Library/Python/3.6/lib/python/site-packages`
 
 Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`.
 
@@ -62,9 +61,7 @@ Homebrew's `site-packages` directory is first created if (1) any Homebrew formul
 The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the `brew --prefix`, so we don't spam your system.
 
 ## Homebrew-provided Python bindings
-Some formulae provide Python bindings. Sometimes a `--with-python` or `--with-python3` option has to be passed to `brew install` in order to build the Python bindings. (Check with `brew options <formula>`.)
-
-Homebrew builds bindings against the first `python` (and `python-config`) in your `PATH`. (Check with `which python`).
+Some formulae provide Python bindings. Sometimes a `--with-python` or `--with-python@2` option has to be passed to `brew install` in order to build the Python bindings. (Check with `brew options <formula>`.)
 
 **Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import <module>` from a brewed Python if you ran `brew install <formula_with_python_bindings>` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`).
 
@@ -89,4 +86,4 @@ Homebrew will still install Python modules into Homebrew's `site-packages` and *
 Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
 
 ## Why is Homebrew's Python being installed as a dependency?
-Formulae that declare an unconditional dependency on the `"python"` or `"python3"` formulae are bottled against Homebrew's Python 2.7.x or 3.x and require it to be installed.
+Formulae that declare an unconditional dependency on the `"python"` or `"python@2"` formulae are bottled against Homebrew's Python 3.x or 2.7.x and require it to be installed.