Skip to content

DOC: revise __astropy_table__'s documentation ? #16235

Closed

Description

@neutrinoceros

I noticed that __astropy_table__'s documentation is using a strict_copy boolean argument as an example on an additional keyword argument that can be added on the side of the implementor.
See https://docs.astropy.org/en/stable/table/construct_table.html#table-like-objects

In the context of NumPy's change of semantics regarding the copy argument (see #16167 for the broader discussion), it seems to me that this example will not age well and might become confusing (since the upcoming convention, dictated by numpy, is that copy arguments are already strict). We might also want to update the __astropy_table__ protocol definition so that the meaning of the copy argument aligns with the rest of the code base (i.e., follows numpy at runtime).

In short, I see two documentation changes to be made:

  • clarify that the copy argument should follow numpy's semantic at runtime (and demonstrate how)
  • use a different example for an additional keyword argument

I feel this needs to be addressed in astropy 6.1.0, though I think (?) it could be done past the feature freeze (scheduled for this Friday). Just in case though, let me ping a couple stake holders here: @astrofrog @saimn @mhvk @taldcroft
To be clear, I can absolutely deal with this before Friday, I'd like to know whether that's required or even desired. Thanks !

Activity

  1. mhvk commented on Mar 26, 2024

    @mhvk
    Contributor

    I agree that we should change the example. I would perhaps discuss the meaning of copy less, just state that it should follow the convention of Table itself. As a different example of a possibly useful keyword, maybe mask_invalid, which would call Masked(col, mask=np.isnan(col))?

  2. taldcroft commented on Mar 26, 2024

    @taldcroft
    Member

    Good catch @neutrinoceros, I definitely agree with changing that example as @mhvk suggested. The mask_invalid idea seems nice.

  3. neutrinoceros commented on Mar 26, 2024

    @neutrinoceros
    ContributorAuthor

    Ok, I'll address this now then. Thank you both for your prompt replies !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions