DOC: update the axes, shape, dim and size property docstring (Seoul) #20101

yeongseon · 2018-03-10T08:33:35Z

This change includes the following property axes, shape, ndim, size

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

# paste output of "scripts/validate_docstrings.py <your-function-or-method>" here
# between the "```" (remove this comment, but keep the "```")

$ scripts/validate_docstrings.py pandas.DataFrame.axes

################################################################################
###################### Docstring (pandas.DataFrame.axes)  ######################
################################################################################

Return a list representing the row axis labels and column axis labels
as the only members. They are returned in that order.

Examples
--------
>>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> df.axes
[RangeIndex(start=0, stop=2, step=1), Index(['coll', 'col2'],
dtype='object')]

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No summary found (a short summary in a single line should be present at the beginning of the docstring)
	No returns section found
	See Also section not found
	Examples do not pass tests

################################################################################
################################### Doctests ###################################
################################################################################

**********************************************************************
Line 8, in pandas.DataFrame.axes
Failed example:
    df.axes
Expected:
    [RangeIndex(start=0, stop=2, step=1), Index(['coll', 'col2'],
    dtype='object')]
Got:
    [RangeIndex(start=0, stop=2, step=1), Index(['col1', 'col2'], dtype='object')]


$ scripts/validate_docstrings.py pandas.DataFrame.ndim

################################################################################
###################### Docstring (pandas.DataFrame.ndim)  ######################
################################################################################

Return an int representing the number of axes / array dimensions.

Examples
--------
>>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> df.ndim
2

>>> df = pd.DataFrame({'col1': [1, 2, 3], 'col2': [4, 5, 6],
...                    'col3': [7, 8, 9]})
>>> df.ndim
2

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found
	No returns section found
	See Also section not found


$ scripts/validate_docstrings.py pandas.DataFrame.size

################################################################################
###################### Docstring (pandas.DataFrame.size)  ######################
################################################################################

Return a numpy.int64 representing the number of elements
in this object.

Examples
--------
>>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> df.size
4

>>> df = pd.DataFrame({'col1': [1, 2, 3], 'col2': [4, 5, 6],
...                    'col3': [7, 8, 9]})
>>> df.size
9

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No summary found (a short summary in a single line should be present at the beginning of the docstring)
	No returns section found
	See Also section not found


$ scripts/validate_docstrings.py pandas.DataFrame.shape

################################################################################
###################### Docstring (pandas.DataFrame.shape) ######################
################################################################################

Return a tuple representing the dimensionality of the DataFrame.

Examples
--------
>>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> df.shape
(2, 2)

>>> df = pd.DataFrame({'col0': [1, 2, 3], 'col2': [4, 5, 6],
...                    'col3': [7, 8, 9]})
>>> df.shape
(3, 3)

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found
	No returns section found
	See Also section not found

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Current change [1][2][3][4] occurred following error "No returns section found", "See Also section nod found".
Because this function is property. so I did not make Return and Also section.
And then axes[1] property occurred "Examples do not pass tests". I made a newline in the result to avoid flake8 error. It raises the above error.

[1] pandas.DataFrame.axes
[2] pandas.DataFrame.ndim
[3] pandas.DataFrame.size
[4] pandas.DataFrame.shape

jorisvandenbossche

Thanks for the PR! Added some first comments

jorisvandenbossche · 2018-03-10T09:59:15Z

pandas/core/frame.py

-        Return a list with the row axis labels and column axis labels as the
-        only members. They are returned in that order.
+        Return a list representing the row axis labels and column axis labels
+        as the only members. They are returned in that order.


Can you make sure this first line is a single sentence? And then you can have multiple sentences as extended summary. Please look at the docstring guideline: https://python-sprints.github.io/pandas/guide/pandas_docstring.html

Sure. I will make it.

jorisvandenbossche · 2018-03-10T10:00:12Z

pandas/core/frame.py

+        >>> df = pd.DataFrame({'col0': [1, 2, 3], 'col2': [4, 5, 6],
+        ...                    'col3': [7, 8, 9]})
+        >>> df.shape
+        (3, 3)


Can you make an example where the number of columns and number of rows is not identical?

Okay, I will make it.

jorisvandenbossche · 2018-03-10T10:01:03Z

pandas/core/generic.py

+        ...                    'col3': [7, 8, 9]})
+        >>> df.ndim
+        2
+        """


Can you also add an example for Series? (and I think one for DataFrame is good enough)

Okay, I will add.

jorisvandenbossche · 2018-03-10T10:01:48Z

pandas/core/generic.py

-        """Number of axes / array dimensions"""
+        """
+        Return an int representing the number of axes / array dimensions.
+


I think it would be fine to add here a sentence saying that this is always 1 for Series and 2 for DataFrame

jorisvandenbossche · 2018-03-10T10:02:36Z

pandas/core/generic.py

        return self._data.ndim

    @property
    def size(self):
-        """number of elements in the NDFrame"""
+        """
+        Return a numpy.int64 representing the number of elements


I think this also just returns an int? (and not np.int64 ?)

jorisvandenbossche · 2018-03-10T10:06:04Z

pandas/core/generic.py

+        >>> df = pd.DataFrame({'col1': [1, 2, 3], 'col2': [4, 5, 6],
+        ...                    'col3': [7, 8, 9]})
+        >>> df.size
+        9


The same here, can you also add an example for Series? And I think it would be useful to put a small sentence before the example explaining the result (so in case of dataframe number of rows times number of columns)

codecov · 2018-03-10T12:38:49Z

Codecov Report

❗ No coverage uploaded for pull request base (master@840d432). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master   #20101   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49149           
  Branches          ?        0           
=========================================
  Hits              ?    45083           
  Misses            ?     4066           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.11% <ø> (?)`
#single	`41.85% <ø> (?)`

Impacted Files	Coverage Δ
pandas/core/frame.py	`97.18% <ø> (ø)`
pandas/core/generic.py	`95.84% <ø> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 840d432...6322586. Read the comment docs.

jreback · 2018-03-10T13:17:09Z

pandas/core/frame.py

+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4],
+        ...                    'col3': [5, 6]})
+        >>> df.shape
+        (2, 3)


can you add a See Also to ndarray.shape

jreback · 2018-03-10T13:17:25Z

pandas/core/generic.py

+
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df.ndim
+        2


Uh oh!

DOC: update the axes, shape, dim and size property docstring (Seoul) #20101

DOC: update the axes, shape, dim and size property docstring (Seoul) #20101

Uh oh!

Conversation

yeongseon commented Mar 10, 2018

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche commented Mar 13, 2018

Uh oh!

yeongseon commented Mar 15, 2018

Uh oh!

Uh oh!

codecov bot commented Mar 10, 2018 •

edited

Loading