Skip to content

"sequence of float" vs "1D array-like" #16161

Closed

Description

@anntzer

Currently some docstrings use "sequence of float" ("sequence of scalar", etc.) and others use "1D array-like" ("1d array-like", "array-like"). We could try to stick to one form (my preference would be "1d array-like" (implicitly floats), "1d int array-like", etc. (lowercase "d")).

attn @timhoffm who has been doing a lot of docstring homogeneization/policy recently :-)

Activity

  1. QuLogic commented on Feb 3, 2021

    @QuLogic
    Member

    "array-like" is the preferred form, according to #11495.

  2. timhoffm commented on Feb 3, 2021

    @timhoffm
    Member

    I think it's all laid out in https://matplotlib.org/devdocs/devel/documenting_mpl.html#parameter-type-descriptions
    But of course not yet applied everywhere in existing docs.

    Use array-like for homogeneous numeric sequences, which could typically be a numpy.array. Dimensionality may be specified using 2D, 3D, n-dimensional. If you need to have variables denoting the sizes of the dimensions, use capital letters in brackets (array-like (M, N)). When referring to them in the text they are easier read and no special formatting is needed.

    float is the implicit default dtype for array-likes. For other dtypes use array-like of int.

    Non-numeric homogeneous sequences are described as list

  3. anntzer commented on Feb 3, 2021

    @anntzer
    ContributorAuthor

    I started editing a few of these, but realized two points (that afaict were not really discussed when this was added in #10225/#11495):

    • (M, N) array-like reads better (IMO) than array-like (M, N), especially when combined into longer expressions such as list of (M, N) array-like (list of array-like (M, N)).
    • Likewise, when the dtype is specified, it looks like an adjective to me (int array-like). Especially when combined with a shape: int (M, N) array-like or (M, N) int array-like rather than array-like (M, N) of int.

    (I guess one case in favor of postscripts would be if we were actually using typing-style syntax, e.g. something like Array[int, Shape[M, N]] (python/typing#516), but we're not there.)

    Thoughts?

  4. timhoffm commented on Feb 4, 2021

    @timhoffm
    Member

    I see your point on readability. Numpy also uses dimension prefixes, so changing to (M, N) array-like should be fine.
    I'm undecided on the dtype position array-like of int is slightly bulky, but in particular also the case int (M, N) ... and (M, N) int ... don't read good.

    Let's take a quick vote in tomorrows dev call.

  5. jklymak commented on Feb 4, 2021

    @jklymak
    Member

    (M, N) array-like of int reads well to me. Its not like we specify the type very often, and a little bulk maybe doesn't hurt if it is unusual...

  6. anntzer commented on Feb 4, 2021

    @anntzer
    ContributorAuthor

    Actually I agree that just moving the shape to the front and leaving the type at the back looks better.

  7. github-actions commented on Jul 7, 2023

    @github-actions

    This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

  8. anntzer commented on Jul 7, 2023

    @anntzer
    ContributorAuthor

    Not many inconsistencies remain and they all read reasonably well.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions