Repository: pandas-dev/pandas

Issue:
DOC: pd.DataFrame(dtype) arg cannot be list, dict, Series. And None will infer wider type than necessary.
#### Code Sample, a copy-pastable example if possible

```python

# 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()``

<details>
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
</details>


Discussion:
repro for the error case
```python
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
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.
this is a (partial) duplicate of: https://github.com/pandas-dev/pandas/issues/4464 (which is the actual impl issue). No objections to clarifying the doc-string.
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 ?
@patniharshit well, the idea is to create a nice-example / expl in the doc-string. so you can certainly start with that.

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -241,17 +241,47 @@ class DataFrame(NDFrame):
         Column labels to use for resulting frame. Will default to
         np.arange(n) if no column labels are provided
     dtype : dtype, default None
-        Data type to force, otherwise infer
+        Data type to force. Only a single dtype is allowed. If None, infer
     copy : boolean, default False
         Copy data from inputs. Only affects DataFrame / 2d ndarray input
 
     Examples
     --------
-    >>> d = {'col1': ts1, 'col2': ts2}
-    >>> df = DataFrame(data=d, index=index)
-    >>> df2 = DataFrame(np.random.randn(10, 5))
-    >>> df3 = DataFrame(np.random.randn(10, 5),
-    ...                 columns=['a', 'b', 'c', 'd', 'e'])
+    Constructing DataFrame from a dictionary.
+
+    >>> d = {'col1': [1, 2], 'col2': [3, 4]}
+    >>> df = pd.DataFrame(data=d)
+    >>> df
+       col1  col2
+    0     1     3
+    1     2     4
+
+    Notice that the inferred dtype is int64.
+
+    >>> df.dtypes
+    col1    int64
+    col2    int64
+    dtype: object
+
+    To enforce a single dtype:
+
+    >>> df = pd.DataFrame(data=d, dtype=np.int8)
+    >>> df.dtypes
+    col1    int8
+    col2    int8
+    dtype: object
+
+    Constructing DataFrame from numpy ndarray:
+
+    >>> df2 = pd.DataFrame(np.random.randint(low=0, high=10, size=(5, 5)),
+    ...                    columns=['a', 'b', 'c', 'd', 'e'])
+    >>> df2
+        a   b   c   d   e
+    0   2   8   8   3   4
+    1   4   2   9   0   9
+    2   1   0   7   8   0
+    3   5   1   7   1   3
+    4   6   0   2   4   2
 
     See also
     --------


Test patch: