DOC: Added docstring for Series.name and corrected docstring guide #32549
Conversation
pandas/core/series.py
Outdated
| 1 2 | ||
| 2 3 | ||
| dtype: int64 | ||
| >>> s1.name = "Numbers" |
There was a problem hiding this comment.
Can you post a screenshot of the built doc? Might need a newline here
There was a problem hiding this comment.
Though I changed this here's a screenshot of the new version
pandas/core/series.py
Outdated
| 1 2 2 | ||
| 2 3 3 | ||
|
|
||
| The name of a Series also persists through some transformations. |
There was a problem hiding this comment.
Appreciate what you are trying to do here but typically best to avoid vagaries like this in the docstring. I think can just delete this part altogether unless this is completely standard (don't think it is, but maybe should be)
There was a problem hiding this comment.
Thanks, I've removed this part
pandas/core/series.py
Outdated
|
|
||
| Returns | ||
| ------- | ||
| Label (int, str or other hashable object). |
There was a problem hiding this comment.
The format of Returns is the type first (without an ending period), and the description in the next line:
Returns
-------
label
The name of the Series, which is the column name if it's part of a DataFrame.
There was a problem hiding this comment.
Thanks, I've changed the format. I don't see any other reference to custom pandas types like label, does capitalisation matter?
pandas/core/series.py
Outdated
|
|
||
| Examples | ||
| -------- | ||
| >>> s1 = pd.Series([1, 2, 3], dtype=np.int64) |
There was a problem hiding this comment.
Nice work @dan1261. I agree with @WillAyd, I think the examples don't represent the common uses of pandas, and that they can somehow confuse users.
What do you think about having two simple examples:
- Create a series with the name as
Series(..., name='whatever'), and then set to something else - Create a small dataframe (two columns, three rows), and check the name of one of the columns
I think this will be easier for users to understand the main usage of the name attribute. While your examples are good and probably more accurate than this, I think users visiting this page may in most cases appreciate something more basic.
There was a problem hiding this comment.
Great, I've followed your suggestions, what do you think? I was originally motivated by trying to concat some Series in this manner which led to the example.
There was a problem hiding this comment.
Looks great, really nice example, thanks a lot for the work on this @dan1261.
For future PRs, we usually prefer to have atomic PRs, and not mix things in the same PR. So, in this case would be preferred to have one for the improvements to the contributing doc, and another for the docstring. If you want to split it, feel free to, but I'm happy to get this merged (doc PRs are very unlikely to be reverted, one of the main reasons for having atomic PRs).
|
Thanks @datapythonista , I considered making two separate PRs - in future I'll follow your advice! |
|
Great thanks @dan1261 |
The main contribution is to add a docstring with examples for the "name" property of the Series object. Also corrected some typos and grammatical points in the "pandas docstring guide".
The type hint gives the type as "Label" and I could not find any other reference to a custom type defined in pandas._typing which was explicitly mentioned in the docs (instead they specify "str" or "int" or somesuch), so I chose "Label (int, str or other hashable object)".
Further I chose "whenever displaying the Series in the interpreter" as clearer alternative to "when invoking the repr method" or a similar precise statement.