DOC: Update __array__ copy keyword docs
#26245
Conversation
b71456a to
04dddd9
Compare
There was a problem hiding this comment.
All the changes LGTM, just one suggestion to improve clarity.
@jorisvandenbossche do the doc changes look OK to you given your recent experience updating __array__ implementations?
|
|
||
| 3. For any ``__array__`` method on a non-NumPy array-like object, | ||
| ``dtype=None`` and ``copy=None`` keywords must be added to the signature - | ||
| this will work with older NumPy versions as well. If the keywords are actually |
There was a problem hiding this comment.
Just to make it a teeny bit clearer what will happen
| this will work with older NumPy versions as well. If the keywords are actually | |
| this will work with older NumPy versions as well (although older numpy versions will never pass in these keywords). If the keywords are actually |
e42d077 to
ae1f038
Compare
| 3. For any ``__array__`` method on a non-NumPy array-like object, | ||
| ``dtype=None`` and ``copy=None`` keywords must be added to the signature - | ||
| this will work with older NumPy versions as well (although older numpy versions | ||
| will never pass in these keywords). If the keywords are actually used in the ``__array__`` |
There was a problem hiding this comment.
It's only copy that is not passed in older versions?
There was a problem hiding this comment.
Ah right, should be (although older numpy versions will never pass in copy keyword). Updated!
| will never pass in these keywords). If the keywords are actually used in the ``__array__`` | ||
| method implementation, then for: |
There was a problem hiding this comment.
| will never pass in these keywords). If the keywords are actually used in the ``__array__`` | |
| method implementation, then for: | |
| will never pass in these keywords). If the keywords are added to the ``__array__`` | |
| signature, then for: |
I still find "if the keywords are actually used in the implementation" a bit confusing, as it sounds that you are allowed to ignore them.
For dtype that is actually maybe true? (if the returned array doesn't match the requested dtype, I suppose that numpy will still do the cast?)
But once copy is added to the signature, it should always be honored in the implementation, right? (to ensure correct behaviour)
There was a problem hiding this comment.
Right, I agree that we should indicate that these arguments should be honored immediately (although copy=True is going to be passed to __array__ starting from 2.1 release). Done!
| method implementation, then for: | ||
| * ``copy=True`` and any ``dtype`` value always return a new copy, | ||
| * ``copy=None`` create a copy if required (for example by ``dtype``), | ||
| * ``copy=False`` a copy must never be made. If ``dtype`` needs a copy then raise an exception. |
There was a problem hiding this comment.
| * ``copy=False`` a copy must never be made. If ``dtype`` needs a copy then raise an exception. | |
| * ``copy=False`` a copy must never be made. If a copy is needed to return a numpy array or satisfy ``dtype``, then raise an exception (``ValueError``). |
Regardless of dtype a copy might be needed. And we can be more specific this should be a ValueError?
There was a problem hiding this comment.
Right - that's more precise. Done!
| ``dtype`` is not given or a new array of provided data type if ``dtype`` | ||
| For ``dtype`` parameter it returns a new reference to self if | ||
| ``dtype`` is not given or it matches array's data type. | ||
| A new array of provided data type is returned if ``dtype`` | ||
| is different from the current data type of the array. | ||
| For ``copy`` parameter it returns a new reference to self if | ||
| ``copy=False`` or ``copy=None`` and copying isn't enforced by ``dtype`` |
There was a problem hiding this comment.
(not about this line, but can't comment on the lines more below)
Not strictly related to this clarification, but I think for implementors of __array__ it might be useful to add a link to https://numpy.org/devdocs/user/basics.interoperability.html#the-array-method here. I know this is the docstring for the numpy __array__ method which has some different semantics (like returning self). But when googling for __array__ you can still end up here.
There was a problem hiding this comment.
To do this you'll need to add a reference anchor to that subsection of the docs and then reference it here. You should be able to build the docs locally to double check that everything is wired up correctly. Let me know if you need a hand wrangling sphinx.
There was a problem hiding this comment.
I added a reference anchor - works locally and in the CI artifact.
ae1f038 to
1f35b27
Compare
36b74ce to
bff75cf
Compare
|
Thanks @mtsokol! |
__array__ copy keyword docs__array__ copy keyword docs
|
Thanks @mtsokol ! |
Hi @ngoldbaum,
As discussed in #25941 here's a few docs updates to avoid ambiguity with
copykeyword argument.