docs: improve Python docs, add section about PEP 668

[iMichka]

Remove comment about Python@2 that is now long gone

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

[iMichka]

Note: this PR does not contain other comments / decisions we made in Homebrew/homebrew-core#157500, which I will handle later in a second PR.

[woodruffw]

Some small nitpicks 🙂

[MikeMcQuaid]

Looks good! As a general note (and we should maybe define this somewhere): a "package" is "either a cask or a formula". In cases where it's definitely either a "formula" or "cask": use that instead to avoid confusion.

(I believe some casks may depend on Python formulae but never vice-versa and there are no Python modules installed as casks).

[iMichka]

Looks good! As a general note (and we should maybe define this somewhere): a "package" is "either a cask or a formula". In cases where it's definitely either a "formula" or "cask": use that instead to avoid confusion.

(I believe some casks may depend on Python formulae but never vice-versa and there are no Python modules installed as casks).

I went with formula in more places to be consistent. I think that a cask depending on a brewed Python is a very small edge case that is not worth mentioning in this documentation (unless there is a specific thing that our users should be aware of, but let's try to not confuse them too much).

[MikeMcQuaid]

Thanks @iMichka!

[iMichka]

Merging, we can do a second pass later. I opened a PR to improve the second page of Python documentation: #16662
Given that there is much more content in #16662, I think both documents will need a full final review at the end.

[cho-m]

Some typos to fix for future PR:

Suggested change

	It is possible to install some Python packages as formulae, by using `brew install xyz`. We do not recommend using these formulae and recommend you install them with pip using a virtualenv. These syste-wide Hombrew Python formulae are often Homebrew-specific formulae that are useful as dependencies for other Homebrew formulae. It is not recommended to rely on them.
	It is possible to install some Python packages as formulae, by using `brew install xyz`. We do not recommend using these formulae and recommend you install them with pip using a virtualenv. These system-wide Homebrew Python formulae are often Homebrew-specific formulae that are useful as dependencies for other Homebrew formulae. It is not recommended to rely on them.