Merge pull request #7963 from Homebrew/python3.8-docs

docs: update docs to reflect new Python procedures

docs/Homebrew-and-Python.md

@@ -11,13 +11,19 @@ Homebrew provided a `python@2` formula until the end of 2019, at which point it
 **Important:** If you choose to use 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 3.x
-Homebrew provides a formula for Python 3.x (`python`).
+Homebrew provides a formula for Python 3.x (`python@3.x`).
 
 The executables are organised as follows:
 
 * `python3` points to Homebrew's Python 3.x (if installed)
 * `pip3` points to Homebrew's Python 3.x's pip (if installed)
 
+Unversioned symlinks for `python`, `python-config`, `pip` etc. are installed here:
+
+```sh
+$(brew --prefix)/opt/python/libexec/bin
+```
+
 ## Setuptools, Pip, etc.
 The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
 

docs/Python-for-Formula-Authors.md

@@ -16,7 +16,7 @@ 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.
+Formulae for apps that require Python 3 **should** declare an unconditional dependency on `"python@3.x"`. 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. No explicit Python dependency is needed since `/usr/bin` is always in `PATH` for Homebrew formulae.
 
@@ -31,14 +31,14 @@ You can use [homebrew-pypi-poet](https://pypi.python.org/pypi/homebrew-pypi-poet
 ```sh
 # Install virtualenvwrapper
 brew install python
-python -m pip install virtualenvwrapper
+python3 -m pip install virtualenvwrapper
 source $(brew --prefix)/bin/virtualenvwrapper.sh
 
 # Set up a temporary virtual environment
 mktmpenv
 
 # Install the package of interest as well as homebrew-pypi-poet
-pip install some_package homebrew-pypi-poet
+pip3 install some_package homebrew-pypi-poet
 poet some_package
 
 # Destroy the temporary virtualenv you just created
@@ -115,7 +115,7 @@ in case you need to do different things for different resources.
 
 ## Bindings
 
-To add bindings for Python 3, please add `depends_on "python"`.
+To add bindings for Python 3, please add `depends_on "python@3.x"` to work with the current Homebrew Python 3.x formula.
 
 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](https://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
 
@@ -129,7 +129,7 @@ If the bindings are installed by invoking a `setup.py`, do something like:
 
 ```ruby
 cd "source/python" do
-  system "python", *Language::Python.setup_install_args(prefix)
+  system Formula["python@3.x"].opt_bin/"python3", *Language::Python.setup_install_args(prefix)
 end
 ```
 
@@ -147,7 +147,7 @@ Sometimes we have to edit a `Makefile` on-the-fly to use our prefix for the Pyth
 
 ### Python declarations
 
-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.
+Libraries built for Python 3 should include `depends_on "python@3.x"`, 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 need a `uses_from_macos "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's an upstream bug; [here's some advice for resolving it](https://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
 
@@ -180,7 +180,7 @@ Distribute (not to be confused with distutils) is an obsolete fork of setuptools
 In the event that a formula needs to interact with `setup.py` instead of calling `pip`, Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns useful arguments for invoking `setup.py`. Your formula should use this instead of invoking `setup.py` explicitly. The syntax is:
 
 ```ruby
-system "python", *Language::Python.setup_install_args(prefix)
+system Formula["python@3.x"].opt_bin/"python3", *Language::Python.setup_install_args(prefix)
 ```
 
 where `prefix` is the destination prefix (usually `libexec` or `prefix`).