Skip to content

Commit ff86a64

Browse files
authored
docs: add tips for numpy (#2465)
* docs: add tips for numpy Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * docs: update example for numpy 2.3.0 Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * Update docs/faq.md --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
1 parent 6f5e480 commit ff86a64

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

docs/faq.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,56 @@ myextension = Extension(
4949
)
5050
```
5151

52+
### Building with NumPy
53+
54+
If using NumPy, there are a couple of things that can help.
55+
56+
First, if you require the `numpy` package at build-time (some binding tools, like `pybind11` and `nanobind`, do not), then the backward compatibility for your `build-backend.build-requires` is a little complicated for Python <3.9:
57+
58+
* NumPy <1.25: You must build with the oldest version of NumPy you want to support at runtime.
59+
* NumPy 1.25 and 1.26: Anything you build will be compatible with 1.19+ by default, and you can set the minimum target to, for example, 1.22 with `#define NPY_TARGET_VERSION NPY_1_22_API_VERSION`.
60+
* NumPy 2.x: You must build with NumPy 2 to support NumPy 2; otherwise the same as 1.25+.
61+
62+
So the rule is:
63+
64+
* Python <3.8: Use the oldest supported NumPy (via helper `oldest-supported-numpy` if you want)
65+
* Python 3.9+: Use latest supported NumPy (2+).
66+
67+
Second, there might be platforms you want to ship for that NumPy (or some other scientific Python libraries) are not shipping yet for. This is often true for beta candidates of new Python releases, for example. To work with this, you can use the Scientific Python Nightly wheels. Here's an example, depending on what frontend you use:
68+
69+
!!! tab "pip based"
70+
For frontends like `build` (the default) and `pip`:
71+
72+
```toml
73+
[tool.cibuildwheel]
74+
environment.PIP_ONLY_BINARY = "numpy"
75+
environment.PIP_PREFER_BINARY = "1"
76+
77+
[[tool.cibuildwheel.overrides]]
78+
select = ["cp314*"]
79+
inherit.environment = "append"
80+
environment.PIP_EXTRA_INDEX_URL = "https://pypi.anaconda.org/scientific-python-nightly-wheels/simple/"
81+
environment.PIP_PRERELEASE = "allow"
82+
```
83+
84+
!!! tab "uv based"
85+
For frontends like `build[uv]`:
86+
87+
```toml
88+
[tool.cibuildwheel]
89+
environment.UV_ONLY_BINARY = "numpy"
90+
environment.UV_PREFER_BINARY = "1"
91+
92+
[[tool.cibuildwheel.overrides]]
93+
select = ["cp314*"]
94+
inherit.environment = "append"
95+
environment.UV_INDEX = "https://pypi.anaconda.org/scientific-python-nightly-wheels/simple/"
96+
environment.UV_INDEX_STRATEGY = "unsafe-best-match"
97+
environment.UV_PRERELEASE = "allow"
98+
```
99+
100+
(Note the `*_ONLY_BINARY` variable also supports `":all:"`, and you don't need both that and `*_PREFER_BINARY`, you can use either one, depending on if you want a missing wheel to be a failure or an attempt to build in CI.)
101+
52102
### Automatic updates using Dependabot {: #automatic-updates}
53103

54104
Selecting a moving target (like the latest release) is generally a bad idea in CI. If something breaks, you can't tell whether it was your code or an upstream update that caused the breakage, and in a worst-case scenario, it could occur during a release.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy