You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 :-)
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
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.)
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.
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!
Activity
QuLogic commentedon Feb 3, 2021
"array-like" is the preferred form, according to #11495.
timhoffm commentedon Feb 3, 2021
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.
anntzer commentedon Feb 3, 2021
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-likereads better (IMO) thanarray-like (M, N), especially when combined into longer expressions such aslist of (M, N) array-like(list of array-like (M, N)).int array-like). Especially when combined with a shape:int (M, N) array-likeor(M, N) int array-likerather thanarray-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?
timhoffm commentedon Feb 4, 2021
I see your point on readability. Numpy also uses dimension prefixes, so changing to
(M, N) array-likeshould be fine.I'm undecided on the dtype position
array-like of intis slightly bulky, but in particular also the caseint (M, N) ...and(M, N) int ...don't read good.Let's take a quick vote in tomorrows dev call.
jklymak commentedon Feb 4, 2021
(M, N) array-like of intreads well to me. Its not like we specify the type very often, and a little bulk maybe doesn't hurt if it is unusual...anntzer commentedon Feb 4, 2021
Actually I agree that just moving the shape to the front and leaving the type at the back looks better.
github-actions commentedon Jul 7, 2023
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!
anntzer commentedon Jul 7, 2023
Not many inconsistencies remain and they all read reasonably well.