Merge branch 'main' into name-normalization

Author: bhrutledge

source/guides/installing-scientific-packages.rst

@@ -64,12 +64,6 @@ up a suitable environment to build extensions locally.
 The extensions provided in these installers are typically compatible with
 the CPython Windows installers published on python.org.
 
-For projects which don't provide their own Windows installers (and even
-some which do), Christoph Gohlke at the University of California provides
-a `collection of Windows installers
-<https://www.lfd.uci.edu/~gohlke/pythonlibs/>`__. Many Python users on
-Windows have reported a positive experience with these prebuilt versions.
-
 As with Linux system packages, the Windows installers will only install into a
 system Python installation - they do not support installation in virtual
 environments. Allowing access to distributions installed into the system Python

source/key_projects.rst

@@ -452,6 +452,21 @@ problem of installing scientific software, and making package
 distribution stateless, cached, and branchable. It is used by some
 researchers but has been lacking in maintenance since 2016.
 
+.. _meson-python:
+
+meson-python
+============
+
+`Docs <https://meson-python.readthedocs.io/en/latest/>`__ |
+`GitHub <https://github.com/mesonbuild/meson-python>`__
+
+``meson-python`` is a build backend that uses the Meson_ build system. It enables
+Python package authors to use Meson_ as the build system for their package. It
+supports a wide variety of languages, including C, and is able to fill the needs
+of most complex build configurations.
+
+.. _Meson: https://github.com/mesonbuild/meson
+
 .. _multibuild:
 
 multibuild

source/specifications/declaring-project-metadata.rst

@@ -73,6 +73,10 @@ The name of the project.
 Tools SHOULD :ref:`normalize <name-normalization>` this name, as soon
 as it is read for internal consistency.
 
+.. code-block:: toml
+
+    [project]
+    name = "spam"
 
 ``version``
 -----------
@@ -85,6 +89,10 @@ The version of the project as supported by :pep:`440`.
 
 Users SHOULD prefer to specify already-normalized versions.
 
+.. code-block:: toml
+
+    [project]
+    version = "2020.0.0"
 
 ``description``
 ---------------
@@ -95,6 +103,10 @@ Users SHOULD prefer to specify already-normalized versions.
 
 The summary description of the project.
 
+.. code-block:: toml
+
+    [project]
+    description = "Lovely Spam! Wonderful Spam!"
 
 ``readme``
 ----------
@@ -134,6 +146,13 @@ alternative content-types which they can transform to a content-type
 as supported by the :ref:`core metadata <core-metadata>`. Otherwise
 tools MUST raise an error for unsupported content-types.
 
+.. code-block:: toml
+
+    [project]
+    # A single pyproject.toml file can only have one of the following.
+    readme = "README.md"
+    readme = "README.rst"
+    readme = {file = "README.txt", content-type = "text/markdown"}
 
 ``requires-python``
 -------------------
@@ -144,6 +163,10 @@ tools MUST raise an error for unsupported content-types.
 
 The Python version requirements of the project.
 
+.. code-block:: toml
+
+    [project]
+    requires-python = ">=3.8"
 
 ``license``
 -----------
@@ -159,6 +182,12 @@ file's encoding is UTF-8. The ``text`` key has a string value which is
 the license of the project.  These keys are mutually exclusive, so a
 tool MUST raise an error if the metadata specifies both keys.
 
+.. code-block:: toml
+
+    [project]
+    # A single pyproject.toml file can only have one of the following.
+    license = {file = "LICENSE"}
+    license = {text = "MIT License"}
 
 ``authors``/``maintainers``
 ---------------------------
@@ -201,6 +230,19 @@ follows:
    as appropriate, with the format ``{name} <{email}>``.
 4. Multiple values should be separated by commas.
 
+.. code-block:: toml
+
+    [project]
+    authors = [
+      {name = "Pradyun Gedam", email = "pradyun@example.com"},
+      {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
+      {name = "Another person"},
+      {email = "different.person@example.com"},
+    ]
+    maintainers = [
+      {name = "Brett Cannon", email = "brett@python.org"}
+    ]
+
 
 ``keywords``
 ------------
@@ -211,6 +253,10 @@ follows:
 
 The keywords for the project.
 
+.. code-block:: toml
+
+    [project]
+    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
 
 ``classifiers``
 ---------------
@@ -221,6 +267,12 @@ The keywords for the project.
 
 Trove classifiers which apply to the project.
 
+.. code-block:: toml
+
+    classifiers = [
+      "Development Status :: 4 - Beta",
+      "Programming Language :: Python"
+    ]
 
 ``urls``
 --------
@@ -232,6 +284,13 @@ Trove classifiers which apply to the project.
 A table of URLs where the key is the URL label and the value is the
 URL itself.
 
+.. code-block:: toml
+
+    [project.urls]
+    homepage = "https://example.com"
+    documentation = "https://readthedocs.org"
+    repository = "https://github.com/me/spam.git"
+    changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
 
 Entry points
 ------------
@@ -262,6 +321,17 @@ Build back-ends MUST raise an error if the metadata defines a
 be ambiguous in the face of ``[project.scripts]`` and
 ``[project.gui-scripts]``, respectively.
 
+.. code-block:: toml
+
+    [project.scripts]
+    spam-cli = "spam:main_cli"
+
+    [project.gui-scripts]
+    spam-gui = "spam:main_gui"
+
+    [project.entry-points."spam.magical"]
+    tomatoes = "spam:main_tomatoes"
+
 
 ``dependencies``/``optional-dependencies``
 ------------------------------------------
@@ -289,6 +359,22 @@ in the array thus becomes a corresponding
 matching :ref:`Provides-Extra <core-metadata-provides-extra>`
 metadata.
 
+.. code-block:: toml
+
+    [project]
+    dependencies = [
+      "httpx",
+      "gidgethub[httpx]>4.0.0",
+      "django>2.1; os_name != 'nt'",
+      "django>2.0; os_name == 'nt'",
+    ]
+
+    [project.optional-dependencies]
+    gui = ["PyQt5"]
+    cli = [
+      "rich",
+      "click",
+    ]
 
 ``dynamic``
 -----------
@@ -327,6 +413,10 @@ provided via tooling later on.
   the data for it (omitting the data, if determined to be the accurate
   value, is acceptable).
 
+.. code-block:: toml
+
+    dynamic = ["version", "description", "optional-dependencies"]
+
 
 Example
 =======
@@ -342,8 +432,10 @@ Example
     license = {file = "LICENSE.txt"}
     keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
     authors = [
-      {email = "pradyun@example.com"},
-      {name = "Tzu-Ping Chung"}
+      {name = "Pradyun Gedam", email = "pradyun@example.com"},
+      {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
+      {name = "Another person"},
+      {email = "different.person@example.com"},
     ]
     maintainers = [
       {name = "Brett Cannon", email = "brett@python.org"}
@@ -357,19 +449,16 @@ Example
       "httpx",
       "gidgethub[httpx]>4.0.0",
       "django>2.1; os_name != 'nt'",
-      "django>2.0; os_name == 'nt'"
+      "django>2.0; os_name == 'nt'",
     ]
 
     # dynamic = ["version", "description"]
 
     [project.optional-dependencies]
-    test = [
-      "pytest > 5.0.0",
-      "pytest-cov[all]"
-    ]
-    doc = [
-      "sphinx",
-      "furo"
+    gui = ["PyQt5"]
+    cli = [
+      "rich",
+      "click",
     ]
 
     [project.urls]