ENH: Provide dict object for to_dict() pandas-dev#16122

Author: dwkenefick

doc/source/whatsnew/v0.20.0.txt

@@ -515,6 +515,7 @@ Other Enhancements
 - Options added to allow one to turn on/off using ``bottleneck`` and ``numexpr``, see :ref:`here <basics.accelerate>` (:issue:`16157`)
 - ``DataFrame.style.bar()`` now accepts two more options to further customize the bar chart. Bar alignment is set with ``align='left'|'mid'|'zero'``, the default is "left", which is backward compatible; You can now pass a list of ``color=[color_negative, color_positive]``. (:issue:`14757`)
 
+
 .. _ISO 8601 duration: https://en.wikipedia.org/wiki/ISO_8601#Durations
 
 

pandas/core/common.py

@@ -481,10 +481,12 @@ def _dict_compat(d):
                 for key, value in iteritems(d))
 
 
-def _standardize_mapping(into):
+def prep_maping_for_to_dict(into):
     """
     Helper function to standardize the supplied mapping so it can
     be passed to the ``Series.to_dict()`` and ``DataFrame.to_dict()``
+    
+    .. versionadded:: 0.21.0
 
     Parameters
     ----------
@@ -504,11 +506,11 @@ def _standardize_mapping(into):
         if len(into) > 0:
             raise ValueError(
                 "to_dict() only accepts empty mappings.")
-        elif type(into) == collections.defaultdict:
+        elif isinstance(into, collections.defaultdict):
             return partial(
                 collections.defaultdict, into.default_factory)
         else:
-            return _standardize_mapping(type(into))
+            return prep_maping_for_to_dict(type(into))
     elif not issubclass(into, collections.Mapping):
         raise TypeError('unsupported type: {}'.format(into))
     elif into == collections.defaultdict:

pandas/core/frame.py

@@ -64,7 +64,7 @@
                                 _values_from_object,
                                 _maybe_box_datetimelike,
                                 _dict_compat,
-                                _standardize_mapping)
+                                prep_maping_for_to_dict)
 from pandas.core.generic import NDFrame, _shared_docs
 from pandas.core.index import Index, MultiIndex, _ensure_index
 from pandas.core.indexing import (maybe_droplevels, convert_to_index_sliceable,
@@ -889,19 +889,59 @@ def to_dict(self, orient='dict', into=dict):
             instance of the mapping type you want.  If you want a
             collections.defaultdict, you must pass an initialized
             instance.
+            
             .. versionadded:: 0.21.0
 
         Returns
         -------
         result : collections.Mapping like {column -> {index -> value}}
             If ``into`` is collections.defaultdict, the return
             value's default_factory will be None.
+            
+        Examples
+        --------
+        >>> from pandas import DataFrame
+        >>> from collections import OrderedDict, defaultdict
+        >>> df = DataFrame({'col1': [1, 2], 'col2': [0.5, 0.75]}, index=['a', 'b'])
+        >>> df
+           col1  col2
+        a     1   0.1
+        b     2   0.2
+        >>> df.to_dict()
+        {'col1': {'a': 1, 'b': 2}, 'col2': {'a': 0.5, 'b': 0.75}}
+        
+        You can specify the return orientation.
+        
+        >>> df.to_dict('series')
+        {'col1': a    1
+        b    2
+        Name: col1, dtype: int64, 'col2': a    0.50
+        b    0.75
+        Name: col2, dtype: float64}
+        >>> df.to_dict('split')
+        {'columns': ['col1', 'col2'],
+        'data': [[1.0, 0.5], [2.0, 0.75]],
+        'index': ['a', 'b']}
+        >>> df.to_dict('records')
+        [{'col1': 1.0, 'col2': 0.5}, {'col1': 2.0, 'col2': 0.75}]
+        >>> df.to_dict('index')
+        {'a': {'col1': 1.0, 'col2': 0.5}, 'b': {'col1': 2.0, 'col2': 0.75}}
+        
+        You can also specify the mapping type.  
+        
+        >>> df.to_dict(into=OrderedDict)
+        OrderedDict([('col2', OrderedDict([('a', 0.5), ('b', 0.75)])),
+                     ('col1', OrderedDict([('a', 1), ('b', 2)]))])
+        >>> dd = defaultdict(list)
+        >>> df.to_dict('records', into=dd)
+        [defaultdict(list, {'col1': 1.0, 'col2': 0.5}),
+         defaultdict(list, {'col1': 2.0, 'col2': 0.75})]        
         """
         if not self.columns.is_unique:
             warnings.warn("DataFrame columns are not unique, some "
                           "columns will be omitted.", UserWarning)
         # GH16122
-        into_c = _standardize_mapping(into)
+        into_c = prep_maping_for_to_dict(into)
         if orient.lower().startswith('d'):
             return into_c(
                 (k, v.to_dict(into)) for k, v in compat.iteritems(self))

pandas/core/series.py

@@ -47,7 +47,7 @@
                                 SettingWithCopyError,
                                 _maybe_box_datetimelike,
                                 _dict_compat,
-                                _standardize_mapping)
+                                prep_maping_for_to_dict)
 from pandas.core.index import (Index, MultiIndex, InvalidIndexError,
                                Float64Index, _ensure_index)
 from pandas.core.indexing import check_bool_indexer, maybe_convert_indices
@@ -1085,16 +1085,31 @@ def to_dict(self, into=dict):
             object. Can be the actual class or an empty
             instance of the mapping type you want.  If you want a
             collections.defaultdict, you must pass an initialized
+            
             .. versionadded:: 0.21.0
 
         Returns
         -------
         value_dict : collections.Mapping
             If ``into`` is collections.defaultdict, the return
             value's default_factory will be None.
+            
+        Examples
+        --------
+        >>> from pandas import Series
+        >>> from collections import OrderedDict, defaultdict
+        >>> s = Series([1, 2, 3, 4])
+        >>> s.to_dict()
+        {0: 1, 1: 2, 2: 3, 3: 4}
+        >>> s.to_dict(OrderedDict)
+        OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
+        >>> dd = defaultdict(list)
+        >>> s.to_dict(dd)
+        defaultdict(list, {0: 1, 1: 2, 2: 3, 3: 4})
+        
         """
         # GH16122
-        into_c = _standardize_mapping(into)
+        into_c = prep_maping_for_to_dict(into)
         return into_c(compat.iteritems(self))
 
     def to_frame(self, name=None):

pandas/tests/test_common.py

@@ -199,26 +199,26 @@ def test_dict_compat():
     assert (com._dict_compat(data_unchanged) == data_unchanged)
 
 
-def test_standardize_mapping():
+def test_prep_maping_for_to_dict():
     # No non-empty
     bad = {'bad': 'data'}
     with pytest.raises(ValueError):
-        com._standardize_mapping(bad)
+        com.prep_maping_for_to_dict(bad)
 
     # No uninitialized defaultdicts
     with pytest.raises(TypeError):
-        com._standardize_mapping(collections.defaultdict)
+        com.prep_maping_for_to_dict(collections.defaultdict)
 
     # No non-mapping subtypes, instance
     with pytest.raises(TypeError):
-        com._standardize_mapping([])
+        com.prep_maping_for_to_dict([])
 
     # No non-mapping subtypes, class
     with pytest.raises(TypeError):
-        com._standardize_mapping(list)
+        com.prep_maping_for_to_dict(list)
 
     # Convert instance to type
-    assert (com._standardize_mapping({}) == dict)
+    assert (com.prep_maping_for_to_dict({}) == dict)
 
     dd = collections.defaultdict(list)
-    assert (type(com._standardize_mapping(dd)) == partial)
+    assert (type(com.prep_maping_for_to_dict(dd)) == partial)