Merge pull request #7019 from iMichka/python2doc

brew: remove most traces of python@2

Library/Homebrew/dev-cmd/audit.rb

@@ -508,7 +508,6 @@ def audit_versioned_keg_only
         bash-completion@2
         gnupg@1.4
         lua@5.1
-        python@2
         numpy@1.16
       ].freeze
 
@@ -706,7 +705,6 @@ def audit_specs
         versioned_head_spec = %w[
           bash-completion@2
           imagemagick@6
-          python@2
         ]
         problem head_spec_message unless versioned_head_spec.include?(formula.name)
       end

Library/Homebrew/exceptions.rb

@@ -335,8 +335,8 @@ class FormulaAmbiguousPythonError < RuntimeError
   def initialize(formula)
     super <<~EOS
       The version of python to use with the virtualenv in the `#{formula.full_name}` formula
-      cannot be guessed automatically. If the simultaneous use of python and python@2
-      is intentional, please add `:using => "python"` or `:using => "python@2"` to
+      cannot be guessed automatically. If the simultaneous use of multiple pythons
+      is intentional, please add `:using => "python@x.y"` to
       `virtualenv_install_with_resources` to resolve the ambiguity manually.
     EOS
   end

Library/Homebrew/formula.rb

@@ -2387,8 +2387,6 @@ def go_resource(name, &block)
     # depends_on "postgresql" if build.without? "sqlite"</pre>
     # <pre># Python 3.x if the `--with-python` is given to `brew install example`
     # depends_on "python3" => :optional</pre>
-    # <pre># Python 2.7:
-    # depends_on "python@2"</pre>
     def depends_on(dep)
       specs.each { |spec| spec.depends_on(dep) }
     end

Library/Homebrew/language/python.rb

@@ -26,7 +26,6 @@ def self.site_packages(python = "python3.7")
     def self.each_python(build, &block)
       original_pythonpath = ENV["PYTHONPATH"]
       pythons = { "python@3" => "python3",
-                  "python@2" => "python2.7",
                   "pypy"     => "pypy",
                   "pypy3"    => "pypy3" }
       pythons.each do |python_formula, python|
@@ -163,17 +162,16 @@ def needs_python?(python)
       # Creates a virtualenv in `libexec`, installs all `resource`s defined
       # on the formula, and then installs the formula. An options hash may be
       # passed (e.g., `:using => "python"`) to override the default, guessed
-      # formula preference for python or python2, or to resolve an ambiguous
-      # case where it's not clear whether python or python2 should be the
+      # formula preference for python or python@x.y, or to resolve an ambiguous
+      # case where it's not clear whether python or python@x.y should be the
       # default guess.
       def virtualenv_install_with_resources(options = {})
         python = options[:using]
         if python.nil?
-          pythons = %w[python python@2 python2 python3 python@3 python@3.8 pypy pypy3]
+          pythons = %w[python python3 python@3 python@3.8 pypy pypy3]
           wanted = pythons.select { |py| needs_python?(py) }
           raise FormulaAmbiguousPythonError, self if wanted.size > 1
 
-          python = wanted.first || "python2.7"
           python = "python3" if python == "python"
         end
         venv = virtualenv_create(libexec, python.delete("@"))
@@ -221,16 +219,14 @@ def create
             next unless f.symlink?
             next unless (rp = f.realpath.to_s).start_with? HOMEBREW_CELLAR
 
-            python = rp.include?("python@2") ? "python@2" : "python"
-            new_target = rp.sub %r{#{HOMEBREW_CELLAR}/#{python}/[^/]+}, Formula[python].opt_prefix
+            new_target = rp.sub %r{#{HOMEBREW_CELLAR}/python/[^/]+}, Formula["python"].opt_prefix
             f.unlink
             f.make_symlink new_target
           end
 
           Pathname.glob(@venv_root/"lib/python*/orig-prefix.txt").each do |prefix_file|
             prefix_path = prefix_file.read
-            python = prefix_path.include?("python@2") ? "python@2" : "python"
-            prefix_path.sub! %r{^#{HOMEBREW_CELLAR}/#{python}/[^/]+}, Formula[python].opt_prefix
+            prefix_path.sub! %r{^#{HOMEBREW_CELLAR}/#{python}/[^/]+}, Formula["python"].opt_prefix
             prefix_file.atomic_write prefix_path
           end
         end

docs/Gems,-Eggs-and-Perl-Modules.md

@@ -27,25 +27,7 @@ writable location. But if you installed Homebrew as we recommend,
 `/usr/local` will be writable without sudo. So now you are good to
 install the development tools you need without risking the use of sudo.
 
-## Python packages (eggs) without sudo
-
-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 `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 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`.
-
-### With system’s Python
+### Python packages (eggs) without sudo using system’s Python
 _This is only recommended if you **don't** use a brewed Python._
 
 On macOS, any [Python version X.Y also searches in
@@ -66,7 +48,7 @@ following content:
 install_lib = ~/Library/Python/$py_version_short/lib/python/site-packages
 ```
 
-### Using virtualenv (works with brewed and system’s Python)
+### Using virtualenv (with system Python)
 
 [Virtualenv](https://virtualenv.pypa.io/) ships `pip` and
 creates isolated Python environments with separate site-packages,

docs/Homebrew-and-Python.md

@@ -4,45 +4,33 @@ 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 Python 3.x and a more up-to-date Python 2.7.x.
+Homebrew provides formulae to brew Python 3.x.
 
-**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.
+Homebrew provided a `python@2` formula until the end of 2019, at which point it was removed due to the Python 2 deprecation.
 
-## Python 3.x or Python 2.x
-Homebrew provides one formula for Python 3.x (`python`) and another for Python 2.7.x (`python@2`).
+**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.
 
-The executables are organised as follows so that Python 2 and Python 3 can both be installed without conflict:
+## Python 3.x
+Homebrew provides a formula for Python 3.x (`python`).
+
+The executables are organised as follows:
 
 * `python3` points to Homebrew's Python 3.x (if installed)
-* `python2` points to Homebrew's Python 2.7.x (if installed)
-* `python` points to Homebrew's Python 2.7.x (if installed) otherwise the macOS system Python. Check out `brew info python` if you wish to add Homebrew's 3.x `python` to your `PATH`.
 * `pip3` points to Homebrew's Python 3.x's pip (if installed)
-* `pip` and `pip2` point to Homebrew's Python 2.7.x's pip (if installed)
-
-([Wondering which one to choose?](https://wiki.python.org/moin/Python2orPython3))
 
 ## Setuptools, Pip, etc.
-The Python formulae install [pip](https://pip.pypa.io/) (as `pip` or `pip2`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
+The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
 
-Setuptools can be updated via pip, without having to re-brew Python:
+Setuptools can be updated via pip3, without having to re-brew Python:
 
 ```sh
-python -m pip install --upgrade setuptools
+python3 -m pip3 install --upgrade setuptools
 ```
 
-Similarly, pip can be used to upgrade itself via:
-
-```sh
-python -m pip install --upgrade pip
-```
-
-### Note on `pip install --user`
-The normal `pip install --user` is disabled for brewed Python. This is because of a bug in distutils, because Homebrew writes a `distutils.cfg` which sets the package `prefix`.
-
-A possible workaround (which puts executable scripts in `~/Library/Python/<X>.<Y>/bin`) is:
+Similarly, pip3 can be used to upgrade itself via:
 
 ```sh
-python -m pip install --user --install-option="--prefix=" <package-name>
+python3 -m pip3 install --upgrade pip3
 ```
 
 ## `site-packages` and the `PYTHONPATH`
@@ -75,7 +63,7 @@ These should be installed via `pip install <package>`. To discover, you can use
 **Note:** macOS's system Python does not provide `pip`. Follow the [pip documentation](https://pip.readthedocs.io/en/stable/installing/#install-pip) to install it for your system Python if you would like it.
 
 ## Brewed Python modules
-For brewed Python, modules installed with `pip` or `python setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`.
+For brewed Python, modules installed with `pip3` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`.
 
 The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to run:
 
@@ -92,4 +80,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 `"python@2"` formulae are bottled against Homebrew's Python 3.x or 2.7.x and require it to be installed.
+Formulae that declare an unconditional dependency on the `"python"` formula are bottled against Homebrew's Python 3.x and require it to be installed.

docs/Homebrew-homebrew-core-Merge-Checklist.md

@@ -28,7 +28,7 @@ Check for:
   - other teams drop new version with minor release 0 but promote it to stable only after a few minor releases
   - if the software uses only hosted version control (such as GitHub, GitLab or Bitbucket), the release should be tagged and if upstream marks latest/pre-releases, PR must use latest
 - does changelog mention addition/removal of dependency and is it addressed in the PR
-  - does formula depend on versioned formula (for example `python@2`, `go@1.10`, `erlang@17`) that can be upgraded
+  - does formula depend on versioned formula (for example `python@3.7`, `go@1.10`, `erlang@17`) that can be upgraded
 - commits
   - contain one formula change per commit
     - ask author to squash

docs/Python-for-Formula-Authors.md

@@ -149,7 +149,7 @@ Sometimes we have to edit a `Makefile` on-the-fly to use our prefix for the Pyth
 
 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's an upstream bug; [here's some advice for resolving it](https://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
+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/).
 
 ### Installing