diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Gems,-Eggs-and-Perl-Modules.md | 10 | ||||
| -rw-r--r-- | docs/Homebrew-and-Python.md | 33 | ||||
| -rw-r--r-- | docs/Python-for-Formula-Authors.md | 16 |
3 files changed, 29 insertions, 30 deletions
diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md index 4a1b1ba44..14d38003b 100644 --- a/docs/Gems,-Eggs-and-Perl-Modules.md +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -11,8 +11,8 @@ Starting with OS X Lion (10.7), you need `sudo` to install to these like so: `sudo gem install`, `sudo easy_install` or `sudo cpan -i`. An option to avoid sudo is to use an access control list: -`chmod +a 'user:YOUR_NAME_HERE allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/2.7/site-packages`, -for example, will let you add packages to Python 2.7 as yourself. That +`chmod +a 'user:YOUR_NAME_HERE allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/3.6/site-packages`, +for example, will let you add packages to Python 3.6 as yourself. That is probably safer than changing the group ownership of the directory. ### So why was I using sudo? @@ -29,14 +29,14 @@ Rather than changing the rights on `/Library/Python`, we recommend the following options: ### With a brewed Python -Note, `easy_install` is deprecated. We install `pip` (or `pip3` for -Python 3) along with python/python3. +Note, `easy_install` is deprecated. We install `pip` (or `pip2` for +Python 2) along with python/python2. We set up distutils such that `pip install` will always put modules in `$(brew --prefix)/lib/pythonX.Y/site-packages` and scripts in `$(brew --prefix)/share/python`. Therefore, you won’t need sudo! -Do `brew info python` or `brew info python3` for precise information +Do `brew info python` or `brew info python@2` for precise information about the paths. Note, a brewed Python still searches for modules in `/Library/Python/X.Y/site-packages` and also in `~/Library/Python/X.Y/lib/python/site-packages`. 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. diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index a530dbef7..e4d50e524 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -16,16 +16,16 @@ Applications should unconditionally bundle all of their Python-language dependen ### Python declarations +Formulae for apps that require Python 3 **should** declare an unconditional dependency on `"python"`. These apps **must** work with the current Homebrew Python 3.x formula. + Applications that are compatible with Python 2 **should** use the Apple-provided system Python in `/usr/bin` on systems that provide Python 2.7. To do this, declare: ```ruby -depends_on "python" if MacOS.version <= :snow_leopard +depends_on "python@2" if MacOS.version <= :snow_leopard ``` No explicit Python dependency is needed on recent OS versions since `/usr/bin` is always in `PATH` for Homebrew formulae; on Leopard and older, the `python` in `PATH` is used if it's at least version 2.7, or else Homebrew's Python 2.7.x is installed. -Formulae for apps that require Python 3 **should** declare an unconditional dependency on `"python3"`. These apps **must** work with the current Homebrew Python 3.x formula. - ### Installing Applications should be installed into a Python [virtualenv](https://virtualenv.pypa.io/en/stable/) environment rooted in `libexec`. This prevents the app's Python modules from contaminating the system site-packages and vice versa. @@ -66,7 +66,7 @@ This is exactly the same as writing: ```ruby def install # Create a virtualenv in `libexec`. If your app needs Python 3, make sure that - # `depends_on "python3"` is declared, and use `virtualenv_create(libexec, "python3")`. + # `depends_on "python"` is declared, and use `virtualenv_create(libexec, "python")`. venv = virtualenv_create(libexec) # Install all of the resources declared on the formula into the virtualenv. venv.pip_install resources @@ -121,9 +121,9 @@ in case you need to do different things for different resources. ## Bindings -Build bindings with the system Python by default (don't add an option) and they should be usable with any binary-compatible Python. If that isn't the case, it's an upstream bug; [here's some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/). +To add bindings for Python 3, please add `depends_on "python"`. -To add bindings for Python 3, please add `depends_on "python3" => :optional` and make the bindings conditional on `build.with?("python3")`. +Build Python 2 bindings with the system Python by default (don't add an option) and they should be usable with any binary-compatible Python. If that isn't the case, it's an upstream bug; [here's some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/). ### Dependencies @@ -153,7 +153,9 @@ Sometimes we have to `inreplace` a `Makefile` to use our prefix for the Python b ### Python declarations -Python 2 libraries do not need a `depends_on "python"` declaration; they will be built with the system Python, but should still be usable with any other Python 2.7. If this is not the case, it is an upstream bug; [here is some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/). Libraries built for Python 3 should include `depends_on "python3"`, which will bottle against Homebrew's Python 3.x. If a library supports both Python 2.x and Python 3.x, the `"python3"` dependency should be `:optional`. Python 2.x libraries must function when they are installed against either the system Python or brewed Python. +Libraries built for Python 3 should include `depends_on "python"`, which will bottle against Homebrew's Python 3.x. Python 2.x libraries must function when they are installed against either the system Python or brewed Python. + +Python 2 libraries do not need a `depends_on "python@2"` declaration; they will be built with the system Python, but should still be usable with any other Python 2.7. If this is not the case, it is an upstream bug; [here is some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/). ### Installing |