Skip to content

DOC iteritems docstring update and examples #22658

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 12 commits into from
Sep 27, 2018
Merged

DOC iteritems docstring update and examples #22658

Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0521552
DOC
Ecboxer Sep 2, 2018
5447a1f
Continuation lines start with ... and are aligned, reverted descripti…
Ecboxer Sep 11, 2018
8ccd554
Removed trailing space and added Returns/Yields section
Ecboxer Sep 12, 2018
fcc27e8
Added extended summary
Ecboxer Sep 12, 2018
6dad21c
Edits to long description, split Yields section into label and conten…
Ecboxer Sep 23, 2018
25da7f8
Merge remote-tracking branch 'upstream/master' into shiny-new-feature
Ecboxer Sep 23, 2018
30026a4
Changed pop to population and reformatted example
Ecboxer Sep 25, 2018
5110b7c
Changed pop to population in example output
Ecboxer Sep 25, 2018
76243b3
Changed docstring to string literal and removed escape chars
Ecboxer Sep 25, 2018
1b52a08
Removed end="\n"
Ecboxer Sep 25, 2018
618318c
Shortened example, fit long desc to char limit, changed Yields to des…
Ecboxer Sep 25, 2018
d8e5370
Returned to two part Yields section, label and contents
Ecboxer Sep 25, 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
49 changes: 45 additions & 4 deletions pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -778,14 +778,55 @@ def style(self):
return Styler(self)

def iteritems(self):
"""
r"""
Iterator over (column name, Series) pairs.
Copy link
Member

Choose a reason for hiding this comment

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

Technically this returns an Iterator (or more specifically a Generator). So I would leave this as Iterator or change this to Generator.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I thought to make the change to 'Iterate over DataFrame ... as (..., Series) pairs to stay within the style of the iterrows and itertuples functions, but I can revert back to 'Iterator over (column name, Series) pairs.


See also
Iterates over the DataFrame columns, returning a tuple with the column name and the content as a Series.
Copy link
Member

Choose a reason for hiding this comment

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

this doesn't fit within 80 chars line length limit (PEP8), I assume the CI is failing due to that.

There are also some other lines below that are too long. I would recommend to activate a flake8 / linter plugin in your editor, or run flake8 locally. You can also check the output of the failing build on Travis.


Yields
------
label : object
The column names for the DataFrame being iterated over.
content : Series
The column entries belonging to each label, as a Series.
Copy link
Member

Choose a reason for hiding this comment

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

@datapythonista I think in this case, the above is actually a bit confusing. Typically, we use the formatting above if there are actually two return values (so if you could do label, content = df.iteritems()), which is not the case here.
So I think the original single item was better, but we could try to make it clearer that it the values of the iterator consist of those two items.

Copy link
Member

Choose a reason for hiding this comment

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

Looks clear to me, not sure why it doesn't to you. In this case you can do for label, content in df.iteritems(): which is equivalent to what you said.

Not a big deal changing this to a Returns saying it's a generator returning tuples. But I don't think that would be clearer to me, and feels a bit inconsistent.

What do you think is clearer for you @Ecboxer? Also, may be @WillAyd want to give an opinion, and he's doing a lot with the docstrings? Happy with whatever option is clearer to most people.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Let me know what you think of the rephrased it under Yields. It may be too wordy?

Copy link
Member

Choose a reason for hiding this comment

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

for label, content in df.iteritems() is not the same as label, content = df.iteritems() ..

The thing is that otherwise we are using the same visual formatting to mean two different things. I would prefer that a user can know from the return type if there is a single or multiple return values (but maybe I am overestimating our users?)

We can maybe still combine both, something like:

Iterator over (label, content) pairs
    label : object
        The column names for the DataFrame being iterated over.
    content : Series
        The column entries belonging to each label, as a Series.

or does that only make it more complicated?

Copy link
Member

@jorisvandenbossche jorisvandenbossche Sep 25, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Ah sorry, I missed that it was a "Yields" section, and not a "Returns" section. In that case, it is correct that it yields two values in each iteration! (and how you did it here is consistent with the numpydoc guidelines)

Copy link
Member

Choose a reason for hiding this comment

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

@Ecboxer sorry, you can change it back to how it was before I commented :-)

Copy link
Member

Choose a reason for hiding this comment

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

hehe, I see what you meant now. Cool then. :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Changed it back :)


See Also
--------
iterrows : Iterate over DataFrame rows as (index, Series) pairs.
itertuples : Iterate over DataFrame rows as namedtuples of the values.
DataFrame.iterrows : Iterate over DataFrame rows as (index, Series) pairs.
DataFrame.itertuples : Iterate over DataFrame rows as namedtuples of the values.

Examples
--------
>>> df = pd.DataFrame({'species': ['bear', 'bear', 'bear', 'bear', 'marsupial'],
... 'population': [300000, 200000, 1864, 22000, 80000]},
... index=['black', 'brown', 'panda', 'polar', 'koala'])
Copy link
Member

Choose a reason for hiding this comment

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

I would make it a little bit shorter (eg 3 rows seems enough), that will make the output below more clear I think

>>> df
species population
black bear 300000
brown bear 200000
panda bear 1864
polar bear 22000
koala marsupial 80000
>>> for label, content in df.iteritems():
... print('label:', label)
... print('content:', content, sep='\n')
...
label: species
content:
black bear
brown bear
panda bear
polar bear
koala marsupial
Name: species, dtype: object
label: population
content:
black 300000
brown 200000
panda 1864
polar 22000
koala 80000
Name: population, dtype: int64
"""
if self.columns.is_unique and hasattr(self, '_item_cache'):
for k in self.columns:
Expand Down