Package: oldest-supported-numpy
AboutThis is a meta-package which can be used inpyproject.tomlfiles
to automatically provide as a build-time dependency the oldest version
of NumPy that supports the given Python version and platform. In case
of platforms for which NumPy has prebuilt wheels, the provided version
also has a prebuilt NumPy wheel.The reason to use the oldest available NumPy version as a build-time
dependency is because of ABI compatibility. Binaries compiled with old
NumPy versions are binary compatible with newer NumPy versions, but
not vice versa. This meta-package exists to make dealing with this
more convenient, without having to duplicate the same list manually in
all packages requiring it.In other words:[build-system]requires=["wheel","setuptools","numpy==1.13.3; python_version=='3.5'","numpy==1.13.3; python_version=='3.6'","numpy==1.14.5; python_version=='3.7'",# more numpy requirements...]can be replaced by:[build-system]requires=["wheel","setuptools","oldest-supported-numpy"]And as new Python versions are released, thepyproject.tomlfile does not
need to be updated.Q&AWhy define the NumPy pinnings usinginstall_requiresin this repository?The NumPy version pinnings are defined inside thesetup.cfgfile asinstall_requiresdependencies, rather than as build-time dependencies
insidepyproject.toml. This is deliberate, since NumPy is not actually
required to build wheels ofoldest-supported-numpy. What we need here
is to make sure that whenoldest-supported-numpyis installed into
the build environment of a package using it, NumPy gets installed too
as aruntimedependency inside the build environment.Another way to think about this is that since we only publish (universal)
wheels ofoldest-supported-numpy, the wheel contains nopyproject.toml,setup.cfg, orsetup.pycode - it only contains metadata including
dependencies which get installed by pip whenoldest-supported-numpyis
installed.Can I use this if my package requires a recent version of NumPy?In many cases, even though your package may require a version of
NumPy that is more recent than the pinned versions here, this
is often a runtime requirement, i.e. for running (rather than
building) your package. In many cases, unless you use recent
features of the NumPy C API, you will still be able to build your
package with an older version of NumPy and therefore you will still
be able to useoldest-supported-numpy. You can still impose a
more recent NumPy requirement ininstall_requiresWhat if a bug in NumPy that affects me is fixed only in a newer release?Ifoldest-supported-numpypins anumpyversion that is broken for
everyone using a certain OS/platform/interpreter combination, we can update the==pin to a newer release. In general, building against a newerbugfixrelease (i.e., a higherYvalue for a1.X.Yversion number) is safe to
do. Newer minor versions will likely not be ABI-compatible, so are much more
difficult to change. If a bug only affects some uses cases (e.g., versions< 1.20.3don’t work on Windows when usingf2py), the pin cannot be updated
because it will affect backwards compatibility ofoldest-supported-numpy.
In that case, it is recommended that you add the needed constraint directly
in your ownpyproject.tomlfile. For example:[build-system]requires=["wheel","numpy==1.19.0; python_version<='3.8' and platform_system=='Windows' and platform_python_implementation != 'PyPy'","oldest-supported-numpy; python_version>'3.8' or platform_system!='Windows' or platform_python_implementation == 'PyPy'",# more requirements (if needed) ...]Note that when you do this, it is important to ensure the conditions are such
that there is exactly one pin possible for a given platform configuration.
Otherwise your build will fail orpipmay refuse to install your packageonlyon that configuration (so you likely won’t see it in CI).
Theoldest-supported-numpyrepository contains tests, so for safety you
may want to implement your constraints in itssetup.cfgand run the
tests withpytestto validate those constraints.Why isn’toldest-supported-numpyavailable for Conda, Homebrew, Debian, etc.?Thepyproject.tomlformat is specific to PyPI. Other packaging systems have
their own metadata formats and ways of specifying dependencies. Typically they
don’t need anything likeoldest-supported-numpybecause either (a) they ship
only a single NumPy version for a given release (typically the case for Linux
distros and Homebrew), or (b) they have a more explicit way of managing ABI
compatibility (see for example conda-forge’spin_compatiblefeature:https://conda-forge.org/docs/maintainer/knowledge_base.html#linking-numpy).What about having a catchier name for this package?The current name is not very catchy as package names go, but it
is very descriptive. This package is only meant to be used inpyproject.tomlfiles for defining build-time dependencies,
so it’s more important to have a descriptive than a catchy name!What if I think that one of the pinnings is wrong or out of date?Please feel free toopen an issueor a pull request if you think something is wrong or could be improved!