pandas.Series docstrings dtype information

[DanielGoldfarb]

docstring for pandas.Series states:

dtype : numpy.dtype or None
    If None, dtype will be inferred

I'm new at this so I don't know all the dtypes that are valid, but at the very least I see that I can write dtype='category' yet categorical_dtype is (as far as I know) not a numpy.dtype (or am I missing something?)

Assuming I'm correct, that there is at least one (possibly more) valid input(s) for dtype that are NOT numpy.dtypes (and not None), then it would be nice if all of them could be listed here. If someone can point me in the right direction (where to gather valid dtype inputs) I would be happy to make the docstring change myself and enter a PR.

[TomAugspurger]

This has changed on master:

pandas/pandas/core/series.py

Lines 129 to 131 in 3675c29

	dtype : str, numpy.dtype, or ExtensionDtype, optional
	dtype for the output Series. If not specified, this will be
	inferred from `data`.

Does that clarify things? I think the main thing that's missing is a link to our dtypes reference at

:ref:`basics.dtypes`

You're correct that category is not a NumPy dtype. It's an extension dtype.

Listing them all probably isn't a good idea, especially since third parties can add additional extension dtypes that would be valid here.

[DanielGoldfarb]

That change makes it somewhat more clear, and I agree that if the list is long, then listing them in the docstring is probably not a good idea. A link in the docstring would be appropriate, however I don't understand exactly where

:ref:basics.dtypes

is supposed to be pointing me. Also, in the case of 'str', I would hope the link would point to a place that lists all possible valid strings that a client of the constructor can use.

[DanielGoldfarb]

Was the intention to link to here?

https://pandas.pydata.org/pandas-docs/stable/basics.html#dtypes

[TomAugspurger]

It's been recently expanded. We would use the :ref: version though, not the URL. Listing the string is somewhat difficult since there are two sources 1. Anything which `np.dtype()` accepts 2. Any of the registered extension types: http://pandas-docs.github.io/pandas-docs-travis/extending.html#extensiondtype

…

On Tue, Dec 18, 2018 at 10:46 AM DanielGoldfarb ***@***.***> wrote: Was the intention to link to here? https://pandas.pydata.org/pandas-docs/stable/basics.html#dtypes — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#24325 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABQHIh1zY_bXO9ocUbdZKgkDQiGGCNwuks5u6RvygaJpZM4ZXH2-> .

[DanielGoldfarb]

Understood regarding using :ref: version; I guess being a newbie to python and pandas, I didn't quite understand the syntax

:ref:`basics.dtypes`

and what it's supposed to mean: it took me more than a couple minutes of poking around to find https://pandas.pydata.org/pandas-docs/stable/basics.html#dtypes

And now that I think of it, I'm a little confused regarding the syntax meaning of saying

dtype : str, numpy.dtype, or ExtensionDtype, ...

in that I now realize (correct me if I'm wrong) that when specifying the optional dtype (keyword) argument, the value will actually always be a string such as

dtype='category'
dtype='int64'
dtype='str'

Is the 3rd one (dtype='str') what is actually meant by the 'str' in

dtype : str, numpy.dtype, or ExtensionDtype, ...

or did you mean something else??

Apologies if these questions sound stupid. Still trying to get used to some of the short-hand ways of speaking within the python documentation.

[TomAugspurger]

The line dtype : str, numpy.dtype, or ExtensionDtype Means that the input can be any of those types. So users can also pass a NumPy dtype like pd.Series([1, 2], dype=np.dtype("int64")) or an extension dtype pd.Series([1, 2], dtype=pd.api.types.CategoricalDtype([1, 2, 3]))

…

On Tue, Dec 18, 2018 at 11:12 AM DanielGoldfarb ***@***.***> wrote: Understood regarding using :ref: version; I guess being a newbie to python and pandas, I didn't quite understand the syntax :ref:`basics.dtypes` and what it's supposed to mean: it took me more than a couple minutes of poking around to find https://pandas.pydata.org/pandas-docs/stable/basics.html#dtypes And now that I think of it, I'm a little confused regarding the syntax meaning of saying dtype : str, numpy.dtype, or ExtensionDtype, ... in that I now realize (correct me if I'm wrong) that when specifying the optional dtype (keyword) argument, the value will actually always be a string such as dtype='category' dtype='int64' dtype='str' Is the 3rd one (dtype='str') what is actually meant by the 'str' in dtype : str, numpy.dtype, or ExtensionDtype, ... or did you mean something else?? Apologies if these questions sound stupid. Still trying to get used to some of the short-hand ways of speaking within the python documentation. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#24325 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABQHImKscBgIRxSIc7esvhygQDXLIfl6ks5u6SH9gaJpZM4ZXH2-> .