Repository: pandas-dev/pandas

Issue:
pandas.Series docstrings dtype information
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. 


Discussion:
This has changed on master: https://github.com/pandas-dev/pandas/blob/3675c29a7bf8714d3f83d1c6a854325702f81969/pandas/core/series.py#L129-L131

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.
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.
Was the intention to link to here?

https://pandas.pydata.org/pandas-docs/stable/basics.html#dtypes

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 <notifications@github.com>
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
> <https://github.com/pandas-dev/pandas/issues/24325#issuecomment-448288035>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIh1zY_bXO9ocUbdZKgkDQiGGCNwuks5u6RvygaJpZM4ZXH2->
> .
>

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.



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 <notifications@github.com>
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
> <https://github.com/pandas-dev/pandas/issues/24325#issuecomment-448297071>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHImKscBgIRxSIc7esvhygQDXLIfl6ks5u6SH9gaJpZM4ZXH2->
> .
>


Resolving patch:
diff --git a/pandas/core/series.py b/pandas/core/series.py
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -130,6 +130,7 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     dtype : str, numpy.dtype, or ExtensionDtype, optional
         dtype for the output Series. If not specified, this will be
         inferred from `data`.
+        See the :ref:`user guide <basics.dtypes>` for more usages.
     copy : bool, default False
         Copy input data.
     """


Test patch: