DOC: rework 'Writing custom array containers' guide #30322
Conversation
|
Hi! Just a friendly ping on this PR. Thanks for your time reviewing :) |
mattip
left a comment
There was a problem hiding this comment.
Thanks! Sorry it took so long to review. A few notes, mainly to remove more verbose old text.
| To get a feel for writing custom array containers, we'll begin with a simple | ||
| example that has rather narrow utility but illustrates the concepts involved. |
There was a problem hiding this comment.
A simple example to demonstrate the use of __array__
| To get a feel for writing custom array containers, we'll begin with a simple | |
| example that has rather narrow utility but illustrates the concepts involved. | |
| Use `__array__` to create a diagonal array of fixed size and value |
| The ``__array__`` method can optionally accept a `dtype` argument. If provided, | ||
| this argument specifies the desired data type for the resulting NumPy array. | ||
| Your implementation should attempt to convert the data to this `dtype` | ||
| if possible. If the conversion is not supported, it's generally best | ||
| to fall back to a default type or raise a `TypeError` or `ValueError`. | ||
|
|
||
| Here's an example demonstrating its use with `dtype` specification: |
There was a problem hiding this comment.
| The ``__array__`` method can optionally accept a `dtype` argument. If provided, | |
| this argument specifies the desired data type for the resulting NumPy array. | |
| Your implementation should attempt to convert the data to this `dtype` | |
| if possible. If the conversion is not supported, it's generally best | |
| to fall back to a default type or raise a `TypeError` or `ValueError`. | |
| Here's an example demonstrating its use with `dtype` specification: | |
| Using ``dtype`` should return an appropriate ndarray or raise an error: |
| To see an example of a custom array implementation including the use of | ||
| ``__array__()``, see :ref:`basics.dispatch`. | ||
| ``__array__()``, see :ref:`special-attributes-and-methods`. |
There was a problem hiding this comment.
Can you remove these three lines and turn the first mention of __array__ on line 121 into a link to reference/arrays.classes.html#numpy.class.__array__ instead?
There was a problem hiding this comment.
Done, I linked the first mention of array to the reference :)
Migrate the __array__() DiagonalArray example from basics.dispatch.rst to arrays.classes.rst where it documents the class.__array__ interface. Reduce basics.dispatch.rst, removing redundant content already covered in basics.interoperability.rst while preserving unique testing utilities documentation. Update cross-reference in basics.interoperability.rst to point to the new example location. See numpy#29258
Simplify verbose text in DiagonalArray example and add link to class.__array__() documentation as suggested.
d1ea84c to
f0ea275
Compare
There was a problem hiding this comment.
Pull request overview
This pull request reorganizes NumPy's documentation for writing custom array containers to reduce duplication with the interoperability documentation. The DiagonalArray example demonstrating __array__() has been moved from the user guide to the reference documentation, and the "Writing custom array containers" guide has been converted to a navigation stub that directs users to the relevant comprehensive documentation.
Key Changes:
- Migrated DiagonalArray
__array__()example to the reference guide - Reduced
basics.dispatch.rstto a navigation stub with links to comprehensive documentation - Updated cross-reference in
basics.interoperability.rstto point to the new example location
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
doc/source/reference/arrays.classes.rst |
Added DiagonalArray example to document the class.__array__() method |
doc/source/user/basics.dispatch.rst |
Converted to navigation stub directing users to comprehensive documentation |
doc/source/user/basics.interoperability.rst |
Updated cross-reference to point to new example location and removed redundant link |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Thanks @nlegendree |
Description
This Pull Request addresses issue #29258, which requested reorganizing the "Writing custom array containers" guide to reduce duplication with the interoperability documentation.
The changes include:
Migrated the
__array__()example: The DiagonalArray example has been moved frombasics.dispatch.rsttoarrays.classes.rst, where it now documents theclass.__array__()method in the reference guide.Reduced
basics.dispatch.rstto a navigation stub: The file has been reduced as a stub.Updated cross-reference: Modified
basics.interoperability.rstto reference the new example location instead of the oldbasics.dispatchpage.Files Modified
doc/source/reference/arrays.classes.rst- Added DiagonalArray exampledoc/source/user/basics.dispatch.rst- Reduced to navigation stubdoc/source/user/basics.interoperability.rst- Updated cross-referenceRelated Issues
Closes #29258