DOC: Use of "Yields" vs "Returns" for documentation of DataFrame.items() and DataFrame.iteritems()

[benthayer]

DataFrame.items() says it "Yields" the label and content of the columns whereas DataFrame.iteritems() says it "Returns" the label and content of the columns

https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.items.html
https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.iteritems.html

[TomAugspurger]

Yields is the correct one.

[jorisvandenbossche]

There is some discussion about this here: #26114 (comment)

cc @topper-123

[topper-123]

Yeah, yield is correct, though very technically, I think items is a generator (it yields) while iteritems returns a generator (it returns something that yields).

But that is a useless distinction, so I agree both could be marked as yielding.

[benthayer]

@topper-123 Not quite. When a function "yields", it is actually returning a generator object. The net effect is that both are functions and both return generators.

>>>def gen():
>>>    for i in range(100):
>>>        yield i
>>>print(type(gen))

<class 'function'>

>>>print(type(gen()))

<class 'generator'>

>>>def return_gen():
>>>    return gen()
>>>print(type(return_gen))

<class 'function'>

>>>print(type(return_gen()))

<class 'generator'>

[jorisvandenbossche]

In any case, both return exactly the same:

In [8]: df = pd.DataFrame({'a': [1, 2, 3]})                                                                                                                                                   

In [9]: df.iteritems()                                                                                                                                                                        
Out[9]: <generator object DataFrame.items at 0x7f4a143e7840>

In [10]: df.items()                                                                                                                                                                           
Out[10]: <generator object DataFrame.items at 0x7f4a143e7660>

so I am not fully sure why the doc validation thinks there is a difference between both.