Skip to content

DOC: #22899, Fixed docstring of itertuples in pandas/core/frame.py #22902

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

Merged
merged 3 commits into from
Oct 7, 2018
Merged

DOC: #22899, Fixed docstring of itertuples in pandas/core/frame.py #22902

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c68feec
DOC: #22899, Fixed docstring of itertuples in pandas/core/frame.py
Sep 30, 2018
be1bee9
DOC: #22899, updated docstring with more examples and fixed Returns t…
Sep 30, 2018
064cf33
DOC: #22899, fix example whitespacing and update formatting in See Al…
Sep 30, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -883,8 +883,7 @@ def iterrows(self):

def itertuples(self, index=True, name="Pandas"):
"""
Iterate over DataFrame rows as namedtuples, with index value as first
element of the tuple.
Iterate over DataFrame rows as namedtuples.

Parameters
----------
Expand All @@ -894,6 +893,10 @@ def itertuples(self, index=True, name="Pandas"):
The name of the returned namedtuples or None to return regular
tuples.

Returns
-------
Returns namedtuples.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case instead of Returns, can you use Yields, as the function is a generator, and the namedtuples are yielded from it.

The exact syntax would be something like:

Yields
------
collections.namedtuple
    A description of what is being yielded.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it! Working on it now.


Notes
-----
The column names will be renamed to positional names if they are
Expand All @@ -907,19 +910,17 @@ def itertuples(self, index=True, name="Pandas"):

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the See Also, can you make the A in the title capital? And then, the items, if you can prefix iterrows and iteritems with DataFrame.iterrows...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, just prefixed both iterrows and iteritems.

Examples
--------

>>> df = pd.DataFrame({'col1': [1, 2], 'col2': [0.1, 0.2]},
index=['a', 'b'])
... index=['a', 'b'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I think it's better to have data that somehow looks real. I think it helps understand better, as you don't need to check in the DataFrame constructor that the row a, in the col2, has a 0.1. It's self-contained that a cat has 4 legs (see this example: https://github.com/pandas-dev/pandas/blob/master/pandas/core/frame.py#L7580).

Also, if you can also one examples with index=False, and one with name='Animal (or whatever concept you think it's better), that would also be valuable.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome. I really like the animal ideas, it is super intuitive!

I made the changes as such and will push it up now.

        Examples
        --------
        >>> df = pd.DataFrame({'num_legs': [4,2], 'num_wings': [0,2]},
        ...                   index=['dog','hawk'])
        >>> df
              num_legs  num_wings
        dog          4          0
        hawk         2          2
        >>> for row in df.itertuples():
        ...     print(row)
        ...
        Pandas(Index='dog', num_legs=4, num_wings=0)
        Pandas(Index='hawk', num_legs=2, num_wings=2)

        By setting the `index` parameter to False we can remove the index
        as the first element of the tuple:

        >>> for row in df.itertuples(index=False):
        ...     print(row)
        ...
        Pandas(num_legs=4, num_wings=0)
        Pandas(num_legs=2, num_wings=2)

        With the `name` parameter set we set a custom name for the yielded
        namedtuples:

        >>> for row in df.itertuples(name='Animal'):
        ...     print(row)
        ...
        Animal(Index='dog', num_legs=4, num_wings=0)
        Animal(Index='hawk', num_legs=2, num_wings=2)

>>> df
col1 col2
a 1 0.1
b 2 0.2
>>> for row in df.itertuples():
... print(row)
...
Pandas(Index='a', col1=1, col2=0.10000000000000001)
Pandas(Index='b', col1=2, col2=0.20000000000000001)

Pandas(Index='a', col1=1, col2=0.1)
Pandas(Index='b', col1=2, col2=0.2)
"""
arrays = []
fields = []
Expand Down