DOC: Add and fixup/move docs for descriptor changes #25946
Conversation
| The ``PyArray_Descr`` struct has been changed | ||
| --------------------------------------------- | ||
| One of the most impactful C-API changes is that the ``PyArray_Descr`` struct | ||
| is no more opaque to allow us to add additional flags and have |
There was a problem hiding this comment.
Should this say it is now opaque instead of no longer opaque? Unless I am misinterpreting the word opaque, but I would assume you want to make it more opaque to allow changing it later without breaking user code again
There was a problem hiding this comment.
Thanks, it was meant to be a "now", not a "no". It is mostly changed really, but I think it makes sense to write it as opaque.
(I.e. elsize is available if you set -DNPY_TARGET_VERSION=NPY_2_0_API_VERSION, but that should be relevant only for authors of new-style DTypes.)
fcbbab1 to
0f987a8
Compare
|
Looks like a good idea to split this off, to keep PR sizes reasonable. This already accumulated a conflict in |
[skip actions] [skip cirrus] [skip azp]
0f987a8 to
7653a32
Compare
Fixed. The important thing is I would like this merged before the other PR. Because the other PR will break doc builds (hopefully not for long), and we need the newest docs visible. |
Co-authored-by: Matti Picus <matti.picus@gmail.com>
|
|
||
| Where not possible, new accessor functions are required: | ||
| * ``PyDataType_ELSIZE`` and ``PyDataType_SET_ELSIZE`` (note that the result | ||
| is now ``npy_intp`` and not ``int``). |
There was a problem hiding this comment.
Formatting is off in the rendered page
| is now ``npy_intp`` and not ``int``). | |
| is now ``npy_intp`` and not ``int``). |
|
|
||
| **Custom User DTypes:** | ||
| Existing user dtypes must now use ``PyArray_DescrProto`` to define their | ||
| dtype and slightly modify the code. See note in `PyArray_RegisterDataType`. |
There was a problem hiding this comment.
Link to PyArray_RegisterDataType is broken in the rendered page.
| is non- ``NULL`` (the fields member of the base descriptor can be | ||
| non- ``NULL`` however). | ||
|
|
||
| .. c:type:: PyArray_ArrayDescr |
There was a problem hiding this comment.
Is this indented on purpose? See the rendered page
| Some dtypes have additional members which are accessible through | ||
| `PyDataType_NAMES`, `PyDataType_FIELDS`, `PyDataType_SUBARRAY`, and | ||
| in some cases (times) `PyDataType_C_METADATA`. | ||
|
|
There was a problem hiding this comment.
These reference links are not working. Do you need a domain?
| See `PyDataType_ELSIZE` and `PyDataType_SET_ELSIZE` for a way to access | ||
| this field in a NumPy 1.x compatible way. | ||
|
|
||
| .. c:member:: npy_intp alignment |
There was a problem hiding this comment.
The links are broken. Do you need a domain?
| An ordered tuple of field names. It is NULL if no field is | ||
| defined. | ||
| See `PyDataType_ALIGNMENT` for a way to access this field in a NumPy 1.x | ||
| compatible way. |
| ---------------------------------------------- | ||
| Unless compiling only with NumPy 2 support, the ``elsize`` and ``aligment`` | ||
| fields must now be accessed via `PyDataType_ELSIZE`, | ||
| `PyDataType_SET_ELSIZE`, and `PyDataType_ALIGNMENT`. |
There was a problem hiding this comment.
The links above are broken. Maybe you can fix the other warnings in the release notes, see the warnings starting here
| One of the most impactful C-API changes is that the ``PyArray_Descr`` struct | ||
| is now more opaque to allow us to add additional flags and have | ||
| itemsizes not limited by the size of ``int`` as well as allow improving | ||
| structured dtypes in the future and not burdon new dtypes with their fields. |
There was a problem hiding this comment.
| structured dtypes in the future and not burdon new dtypes with their fields. | |
| structured dtypes in the future and not burden new dtypes with their fields. |
| structured dtypes in the future and not burdon new dtypes with their fields. | ||
|
|
||
| Code which only uses the type number and other initial fields is unaffected. | ||
| Most code will hopefull mainly access the ``->elsize`` field, when the |
There was a problem hiding this comment.
| Most code will hopefull mainly access the ``->elsize`` field, when the | |
| Most code will hopefully mainly access the ``->elsize`` field, when the |
|
Lets merge this now and work on cleanups later. |
|
Thanks, one additional small fixup, will be to add the additional |
…elsize (#40418) ### Rationale for this change NumPy 2.0 is changing some ABI, see the issue description and numpy/numpy#25946 for more details. The changes here should make our code compatible both with current numpy 1.x and future numpy 2.x * GitHub Issue: #40376 Lead-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> Co-authored-by: Sebastian Berg <sebastianb@nvidia.com> Signed-off-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>
This is a "pre" PR for the actual changes in #25943. The point is that the PR breaks the docs build as it is enough of an ABI break that downstream has to recompile.
That will take a few days (maybe a bit longer if
pyibind11proofs problematic, although it seems problematic use of pybind11 is rare, e.g. in SciPy only one file/module was affected).Thus, split it out so we can put it in (and also see doc mistakes).