DOC: pd.DataFrame(dtype) arg cannot be list, dict, Series. And None will infer wider type than necessary.

[smcinerney]

Code Sample, a copy-pastable example if possible

# This is a DOCbug simply to document what pd.DataFrame(dtype) currently does.
# It is non-obvious to new users, gives non-obvious error messages, and also behaves differently to read_csv(dtype)

# a) Leaving dtype=None in constructor will infer a wider type than necessary
df_cols = {'year':np.int32, 'month':np.int8}
df = pd.DataFrame(columns=df_cols.keys(), dtype=None, index=range(10), data=-1)
>>> df.dtypes
month    int64
year     int64

# b) The doc doesn't explicitly say a list/dict/Series/array-like is not allowed (and if you
# pass in one the error is not very friendly). Also behaves differently to read_csv(dtype)
df = pd.DataFrame(columns=df_cols.keys(), dtype=np.int32, index=range(10), data=-1)
# df.dtypes shows they're all np.int32
# Fix up dtypes after declaration
for col,coltype in df_cols.items():
    df[col] = df[col].astype(coltype) 

Problem description

The DataFrame() doc doesn't explicitly say a list/dict/Series/array-like is not allowed (and if you pass in one the error is not very friendly). Also behaves differently to read_csv(dtype).
Leaving dtype=None in constructor will infer a wider type than necessary.
So in general you either set dtype=widest_necessary_type, or dtype=None and then manually fix them up after declaration, by casting with astype()

Expected Output

Output of pd.show_versions()

python: 2.7.10.final.0 python-bits: 64 machine: x86_64 processor: i386 byteorder: little pandas: 0.19.1 numpy: 1.11.2 scipy: 0.18.1

[chris-b1]

repro for the error case

df = pd.DataFrame(columns=['year', 'month'], 
                  dtype={'year': 'int32', 'month': 'int8'},
                  index=range(10), data=-1)

I could see an argument for supporting this, consistent with #13375

[smcinerney]

To be clear, I'm only asking for the documentation to reflect what currently happens. It's pretty confusing. We can live with fixing-up the dtypes after the df is declared; it would be good to document that workaround.

[jreback]

this is a (partial) duplicate of: #4464 (which is the actual impl issue). No objections to clarifying the doc-string.

[patniharshit]

I would like to do this but I am not exactly sure what to do. Should I copy paste the example given by @smcinerney in docstring of DataFrame class in pandas/core/frame.py ?

[jreback]

@patniharshit well, the idea is to create a nice-example / expl in the doc-string. so you can certainly start with that.

[VincentLa]

Looks like this issue got dropped. Happy to see if i can take a stab at this now. If anyone is at pycon sprints, happy to pair!

[VincentLa]

Ok added an example in the docstring. Would welcome feedback about its usefulness!