DOC: better docs on infer_type

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -67,12 +67,17 @@ will be removed from the ``*.common`` locations in a future release. (:issue:`15
 
 The following are now part of this API:
 
-.. ipython:: python
-
-   import pprint
-   from pandas import errors
-   excs = [ e for e in dir(errors) if not e.startswith('_') ]
-   pprint.pprint(excs)
+.. code-block:: python
+
+   ['AmbiguousIndexError',
+    'DtypeWarning',
+    'EmptyDataError',
+    'OutOfBoundsDatetime',
+    'ParserError',
+    'ParserWarning',
+    'PerformanceWarning',
+    'UnsortedIndexError',
+    'UnsupportedFunctionCall']
 
 .. _whatsnew_0200.enhancements.groupby_access:
 

pandas/_libs/src/inference.pyx

@@ -218,9 +218,42 @@ cdef _try_infer_map(v):
     return None
 
 
-def infer_dtype(object _values):
+def infer_dtype(object value):
     """
-    we are coercing to an ndarray here
+    Effeciently infer the type of a passed val, or list-like
+    array of values. Return a string describing the type.
+
+    Parameters
+    ----------
+    value : scalar, list, ndarray, or pandas type
+
+    Returns
+    -------
+    string describing the common type of the input data.
+    Results can include:
+       - floating
+       - integer
+       - mixed-integer
+       - mixed-integer-float
+       - complex
+       - categorical
+       - boolean
+       - datetime64
+       - datetime
+       - date
+       - timedelta64
+       - timedelta
+       - time
+       - period
+       - string
+       - unicode
+       - bytes
+       - mixed
+
+    Raises
+    ------
+    TypeError if ndarray-like but cannot infer the dtype
+
     """
 
     cdef:
@@ -229,27 +262,27 @@ def infer_dtype(object _values):
         ndarray values
         bint seen_pdnat = False, seen_val = False
 
-    if isinstance(_values, np.ndarray):
-        values = _values
-    elif hasattr(_values, 'dtype'):
+    if isinstance(value, np.ndarray):
+        values = value
+    elif hasattr(value, 'dtype'):
 
         # this will handle ndarray-like
         # e.g. categoricals
         try:
-            values = getattr(_values, '_values', getattr(
-                _values, 'values', _values))
+            values = getattr(value, '_values', getattr(
+                value, 'values', value))
         except:
-            val = _try_infer_map(_values)
-            if val is not None:
-                return val
+            value = _try_infer_map(value)
+            if value is not None:
+                return value
 
             # its ndarray like but we can't handle
-            raise ValueError("cannot infer type for {0}".format(type(_values)))
+            raise ValueError("cannot infer type for {0}".format(type(value)))
 
     else:
-        if not isinstance(_values, list):
-            _values = list(_values)
-        values = list_to_object_array(_values)
+        if not isinstance(value, list):
+            value = list(value)
+        values = list_to_object_array(value)
 
     values = getattr(values, 'values', values)
     val = _try_infer_map(values)