10000 Consistency of docstrings between `ones`, `zeros` and `empty`. · Issue #10611 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

Consistency of docstrings between ones, zeros and empty. #10611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
godaygo opened this issue Feb 16, 2018 · 2 comments · Fixed by #10679
Closed

Consistency of docstrings between ones, zeros and empty. #10611

godaygo opened this issue Feb 16, 2018 · 2 comments · Fixed by #10679

Comments

@godaygo
Copy link
Contributor
godaygo commented Feb 16, 2018

There is some inconsistency in docstrings for 3 frequently used constructor functions:

  • ones
  • zeros
  • empty
  1. The docstring for ones looks as follows:
ones(shape, dtype=None, order='C'):
    """
    Return a new array of given shape and type, filled with ones.

    Parameters
    ----------
    shape : int or sequence of ints
        Shape of the new array, e.g., ``(2, 3)`` or ``2``.
    dtype : data-type, optional
        The desired data-type for the array, e.g., `numpy.int8`.  Default is
        `numpy.float64`.
    order : {'C', 'F'}, optional
        Whether to store multidimensional data in C- or Fortran-contiguous
        (row- or column-wise) order in memory.

Interesting part here is signature ones(shape, dtype=None, order='C'), and dtype=None. While dtype description it is said that "Default is numpy.float64". For other two functions the signatures are:

zeros(shape, dtype=float, order='C')
empty(shape, dtype=float, order='C')

While they are better, they are also incorrect -> should be dtype=double or dtype=float64.

  1. The description of parameters for ones and zeros a pretty identical. But for the empty it is somewhat stripped down:
Docstring:
empty(shape, dtype=float, order='C')

Return a new array of given shape and type, without initializing entries.

Parameters
----------
shape : int or tuple of int
    Shape of the empty array
dtype : data-type, optional
    Desired output data-type.
order : {'C', 'F'}, optional
    Whether to store multi-dimensional data in row-major
    (C-style) or column-major (Fortran-style) order in
    memory.
@godaygo
Copy link
Contributor Author
godaygo commented Feb 16, 2018 •
edited
Loading

While this is offtopic, but somewhat related, the chosen default type for these functions - float64 for dtype is the very general type with all consequences see the #10405.

@eric-wieser
Copy link
Member
eric-wieser commented Feb 27, 2018 •
edited
Loading

While they are better, they are also incorrect

No, they are correct - numpy promotes float into np.double/np.float64. Calling np.ones(..., dtype=float) is always the same as np.ones(...).

Your other remarks are valid - patch welcome!

@NelleV NelleV mentioned this issue Mar 1, 2018
Merged
NelleV added a commit to NelleV/numpy that referenced this issue Mar 1, 2018
@NelleV
DOC zeros, empty, and ones now have consistent docstrings
5a23878 
closes numpy#10611
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DOC: zeros, empty, and ones now have consistent docstrings NelleV/numpy
2 participants
@eric-wieser @godaygo
0