From 70253f0009ee8095a5d10ee7bdd891f1fe5cc35c Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sat, 3 Mar 2018 09:42:25 +0000 Subject: Adjust docs and more internal code for Python 3. Now we have `python` for Python 3 and `python@2` for Python 2 some more adjustments need to be made. --- docs/Homebrew-and-Python.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) (limited to 'docs/Homebrew-and-Python.md') 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/./bin`) is: ```sh -python2 -m pip install --user --install-option="--prefix=" +python -m pip install --user --install-option="--prefix=" ``` ## `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 `.) - -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 `.) **Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import ` from a brewed Python if you ran `brew install ` 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. -- cgit v1.2.3