From 985be06a61cad71cb3894983d7a094d180b4748c Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Sat, 26 Mar 2022 10:29:22 +0000 Subject: [PATCH 1/7] docs: add note about opting into PEP 621 --- docs/options.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/options.md b/docs/options.md index 45f67873..8e71e37c 100644 --- a/docs/options.md +++ b/docs/options.md @@ -432,6 +432,12 @@ the package is compatible with all versions of Python that it can build. requires = ["setuptools>=42", "wheel"] build-backend = "setuptools.build_meta" + Note however, that adding a `[project]` table to your `pyproject.toml` may + trigger a series of validations as specified in + [PEP621](https://www.python.org/dev/peps/pep-0621/). Also consider that + adding `[project]`, if not done carefully, will change the behaviour of your + build (e.g. `setuptools` may ignore `install_requires` specified via + `setup.py` or `setup.cfg`). Currently, setuptools has not yet added support for reading this value from pyproject.toml yet, and so does not copy it to Requires-Python in the wheel From d76d019adab51c0e3ead081ccd47eb23ce1160a1 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 27 Mar 2022 21:47:30 +0100 Subject: [PATCH 2/7] Reword requires-python section note --- docs/options.md | 44 +++++++++++++++++++------------------------- 1 file changed, 19 insertions(+), 25 deletions(-) diff --git a/docs/options.md b/docs/options.md index 8e71e37c..cda8500d 100644 --- a/docs/options.md +++ b/docs/options.md @@ -420,39 +420,33 @@ the package is compatible with all versions of Python that it can build. !!! note Rather than using this option, it's recommended you set `project.requires-python` in `pyproject.toml` instead: - Example `pyproject.toml`: - [project] - requires-python = ">=3.6" + ```toml + [project] + requires-python = ">=3.6" + ``` - # Aside - in pyproject.toml you should always specify minimal build - # system options, like this: + A few things to note: + - If your project didn't already have a `pyproject.toml`, be sure to + set the build system to your build backend. + + ```toml [build-system] requires = ["setuptools>=42", "wheel"] build-backend = "setuptools.build_meta" + ``` - Note however, that adding a `[project]` table to your `pyproject.toml` may - trigger a series of validations as specified in - [PEP621](https://www.python.org/dev/peps/pep-0621/). Also consider that - adding `[project]`, if not done carefully, will change the behaviour of your - build (e.g. `setuptools` may ignore `install_requires` specified via - `setup.py` or `setup.cfg`). - - Currently, setuptools has not yet added support for reading this value from - pyproject.toml yet, and so does not copy it to Requires-Python in the wheel - metadata. This mechanism is used by pip to scan through older versions of - your package until it finds a release compatible with the current version - of Python compatible when installing, so it is an important value to set if - you plan to drop support for a version of Python in the future. - - If you don't want to list this value twice, you can also use the setuptools - specific location in `setup.cfg` and cibuildwheel will detect it from - there. Example `setup.cfg`: - - [options] - python_requires = ">=3.6" + - If you didn't already have a `pyproject.toml` that had a `[project]` + table, you should migrate values from `setup.py` or `setup.cfg`, or + [list them in the the `dynamic` field](https://peps.python.org/pep-0621/#dynamic). + The values to include and the format is listed in + [PEP 621](https://peps.python.org/pep-0621/#details) + - Adding `[project]` to `pyproject.toml` can + change the behaviour of your build (e.g. `setuptools` may ignore + `install_requires` specified via `setup.py` or `setup.cfg`). Make sure + to double-check the build after adding. This option is not available in `pyproject.toml` under `tool.cibuildwheel.project-requires-python`, since it should be set with the From 93477cab80bd0edd7f6e5cb3a7f33a46a62a69fe Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 27 Mar 2022 21:58:57 +0100 Subject: [PATCH 3/7] Fix docs build --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index 621ccf27..96b4d10c 100644 --- a/setup.py +++ b/setup.py @@ -4,6 +4,7 @@ extras = { "docs": [ "mkdocs-include-markdown-plugin==2.8.0", "mkdocs==1.0.4", + "jinja2==3.0.3", "pymdown-extensions", "mkdocs-macros-plugin", ], From 1d6a1c020939945bd112c27ac7ee266c22009d2f Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Tue, 29 Mar 2022 09:31:39 -0400 Subject: [PATCH 4/7] Update docs/options.md Co-authored-by: CAM Gerlach --- docs/options.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/options.md b/docs/options.md index cda8500d..17b5ea32 100644 --- a/docs/options.md +++ b/docs/options.md @@ -439,9 +439,10 @@ the package is compatible with all versions of Python that it can build. - If you didn't already have a `pyproject.toml` that had a `[project]` table, you should migrate values from `setup.py` or `setup.cfg`, or - [list them in the the `dynamic` field](https://peps.python.org/pep-0621/#dynamic). - The values to include and the format is listed in - [PEP 621](https://peps.python.org/pep-0621/#details) + list them in the [the `dynamic` field](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic). + The values to include and the format is listed in the + [project source metadata specification](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic) + (as originally defined in PEP 621). - Adding `[project]` to `pyproject.toml` can change the behaviour of your build (e.g. `setuptools` may ignore From 901f07b586939f12fc4996efe73a56ce382d969c Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Tue, 29 Mar 2022 20:45:23 +0100 Subject: [PATCH 5/7] Redraft to respond to comments --- docs/options.md | 45 ++++++++++++++------------------------------- 1 file changed, 14 insertions(+), 31 deletions(-) diff --git a/docs/options.md b/docs/options.md index 17b5ea32..71fc0443 100644 --- a/docs/options.md +++ b/docs/options.md @@ -402,7 +402,7 @@ This option can also be set using the [command-line option](#command-line) > Manually set the Python compatibility of your project By default, cibuildwheel reads your package's Python compatibility from -`pyproject.toml` following [PEP621](https://www.python.org/dev/peps/pep-0621/) +`pyproject.toml` following the [project metadata specification](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/) or from `setup.cfg`; finally it will try to inspect the AST of `setup.py` for a simple keyword assignment in a top level function call. If you need to override this behaviour for some reason, you can use this option. @@ -416,43 +416,26 @@ Default: reads your package's Python compatibility from `pyproject.toml` `setup.py` `setup(python_requires="...")`. If not found, cibuildwheel assumes the package is compatible with all versions of Python that it can build. - !!! note - Rather than using this option, it's recommended you set - `project.requires-python` in `pyproject.toml` instead: + Rather than using this option, it's recommended you set this value + statically in a way that your build backend can use it, too. This ensures + that your package's metadata is correct when published on PyPI. - ```toml - [project] - requires-python = ">=3.6" - ``` - - A few things to note: - - - If your project didn't already have a `pyproject.toml`, be sure to - set the build system to your build backend. + - If you have a `pyproject.toml` containing a `[project]` table, you can + specify `requires-python` there. ```toml - [build-system] - requires = ["setuptools>=42", "wheel"] - build-backend = "setuptools.build_meta" + [project] + requires-python = ">=3.6" ``` - - If you didn't already have a `pyproject.toml` that had a `[project]` - table, you should migrate values from `setup.py` or `setup.cfg`, or - list them in the [the `dynamic` field](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic). - The values to include and the format is listed in the - [project source metadata specification](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic) - (as originally defined in PEP 621). + Note that build backend support for the `[project]` table is still patchy, and + adding `[project]` to `pyproject.toml` can change the behaviour of your build + (e.g. setuptools may ignore `install_requires` specified via `setup.py` or + `setup.cfg`). Make sure to double-check the build after adding. - - Adding `[project]` to `pyproject.toml` can - change the behaviour of your build (e.g. `setuptools` may ignore - `install_requires` specified via `setup.py` or `setup.cfg`). Make sure - to double-check the build after adding. - -This option is not available in `pyproject.toml` under -`tool.cibuildwheel.project-requires-python`, since it should be set with the -[PEP621](https://www.python.org/dev/peps/pep-0621/) location instead, -`project.requires-python`. + - If you're using setuptools, [you can set this value in `setup.cfg` or `setup.py`](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement) + and cibuildwheel will read it from there. #### Examples From cd808df0e9ad19ed36f19c6843400a48e61d6e3b Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Wed, 30 Mar 2022 09:13:17 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Henry Schreiner --- docs/options.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/options.md b/docs/options.md index 71fc0443..973d5d85 100644 --- a/docs/options.md +++ b/docs/options.md @@ -417,24 +417,27 @@ Default: reads your package's Python compatibility from `pyproject.toml` the package is compatible with all versions of Python that it can build. !!! note - Rather than using this option, it's recommended you set this value + Rather than using this environment variable, it's recommended you set this value statically in a way that your build backend can use it, too. This ensures - that your package's metadata is correct when published on PyPI. + that your package's metadata is correct when published on PyPI. This + cibuildwheel-specific option is provided as an override, and therefore is only + available in environment variable form. - If you have a `pyproject.toml` containing a `[project]` table, you can specify `requires-python` there. ```toml [project] + ... requires-python = ">=3.6" ``` - Note that build backend support for the `[project]` table is still patchy, and - adding `[project]` to `pyproject.toml` can change the behaviour of your build - (e.g. setuptools may ignore `install_requires` specified via `setup.py` or - `setup.cfg`). Make sure to double-check the build after adding. + Note that not all build backends fully support using a `[project]` table yet; + specifically setuptools just added experimental support in version 61. + Adding `[project]` to `pyproject.toml` requires all the other supported + values to be specified there, or to be listed in `dynamic`. - - If you're using setuptools, [you can set this value in `setup.cfg` or `setup.py`](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement) + - If you're using setuptools, [you can set this value in `setup.cfg` (preferred) or `setup.py`](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement) and cibuildwheel will read it from there. #### Examples From 0ccd623e605e7527d49e9dacf7e90f6489981c70 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 30 Mar 2022 08:13:46 +0000 Subject: [PATCH 7/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/options.md b/docs/options.md index 973d5d85..c9d7b742 100644 --- a/docs/options.md +++ b/docs/options.md @@ -419,7 +419,7 @@ the package is compatible with all versions of Python that it can build. !!! note Rather than using this environment variable, it's recommended you set this value statically in a way that your build backend can use it, too. This ensures - that your package's metadata is correct when published on PyPI. This + that your package's metadata is correct when published on PyPI. This cibuildwheel-specific option is provided as an override, and therefore is only available in environment variable form.