API: Series/DataFrame.to_string return string by default. Series.to_string

buffer keyword namechange. addresses GH #232

Author: wesm

RELEASE.rst

@@ -19,6 +19,9 @@ pandas 0.5.0
     #225)
   - Removed `weights` option in panel regression which was not doing anything
     principled
+  - Changed `buffer` argument name in `Series.to_string` to `buf`
+  - `Series.to_string` and `DataFrame.to_string` now return strings by default
+    instead of printing to sys.stdout
 
 **New features / modules**
 

pandas/core/frame.py

@@ -552,8 +552,10 @@ def to_string(self, buf=None, columns=None, colSpace=None,
                   sparsify=True):
         from pandas.core.common import _format, adjoin
 
+        return_ = False
         if buf is None:  # pragma: no cover
-            buf = sys.stdout
+            buf = StringIO()
+            return_ = True
 
         if colSpace is None:
             def _myformat(v):
@@ -596,6 +598,9 @@ def _format_col(col):
         for s in to_write:
             print >> buf, s
 
+        if return_:
+            return buf.getvalue()
+
     def _get_formatted_labels(self, sparsify=True):
         from pandas.core.index import _sparsify
 
@@ -3307,7 +3312,7 @@ def install_ipython_completers():
     """Register the DataFrame type with IPython's tab completion machinery, so
     that it knows about accessing column names as attributes."""
     from IPython.utils.generics import complete_object
-    
+
     @complete_object.when_type(DataFrame)
     def complete_dataframe(obj, prev_completions):
         return prev_completions + [c for c in obj.columns \

pandas/core/series.py

@@ -378,8 +378,12 @@ def _tidy_repr(self, max_vals=20):
         result = '%s\nName: %s, Length: %d' % (result, self.name, len(self))
         return result
 
-    def to_string(self, buffer=sys.stdout, nanRep='NaN'):
-        print >> buffer, self._get_repr(nanRep=nanRep)
+    def to_string(self, buf=None, nanRep='NaN'):
+        the_repr = self._get_repr(nanRep=nanRep)
+        if buf is None:
+            return the_repr
+        else:
+            print >> buf, the_repr
 
     def _get_repr(self, name=False, nanRep='NaN'):
         vals = self.values

pandas/tests/test_frame.py

@@ -67,10 +67,11 @@ def test_getitem_boolean(self):
 
         subframe_obj = self.tsframe[indexer_obj]
         assert_frame_equal(subframe_obj, subframe)
-    
+
     def test_getattr(self):
         tm.assert_series_equal(self.frame.A, self.frame['A'])
-        self.assertRaises(AttributeError, getattr, self.frame, 'NONEXISTENT_NAME')
+        self.assertRaises(AttributeError, getattr, self.frame,
+                          'NONEXISTENT_NAME')
 
     def test_setitem(self):
         # not sure what else to do here
@@ -1268,20 +1269,25 @@ def test_to_string(self):
 
         biggie['A'][:20] = nan
         biggie['B'][:20] = nan
+        s = biggie.to_string()
+
         buf = StringIO()
-        biggie.to_string(buf=buf)
+        retval = biggie.to_string(buf=buf)
+        self.assert_(retval is None)
+        self.assertEqual(buf.getvalue(), s)
+
+        self.assert_(isinstance(s, basestring))
 
-        biggie.to_string(buf=buf, columns=['B', 'A'], colSpace=17)
-        biggie.to_string(buf=buf, columns=['B', 'A'],
-                        formatters={'A' : lambda x: '%.1f' % x})
+        biggie.to_string(columns=['B', 'A'], colSpace=17)
+        biggie.to_string(columns=['B', 'A'],
+                         formatters={'A' : lambda x: '%.1f' % x})
 
-        biggie.to_string(buf=buf, columns=['B', 'A'],
-                        float_format=str)
-        biggie.to_string(buf=buf, columns=['B', 'A'], colSpace=12,
-                        float_format=str)
+        biggie.to_string(columns=['B', 'A'], float_format=str)
+        biggie.to_string(columns=['B', 'A'], colSpace=12,
+                         float_format=str)
 
         frame = DataFrame(index=np.arange(1000))
-        frame.to_string(buf=buf)
+        frame.to_string()
 
     def test_insert(self):
         df = DataFrame(np.random.randn(5, 3), index=np.arange(5),

pandas/tests/test_series.py

@@ -426,7 +426,13 @@ def test_repr(self):
 
     def test_to_string(self):
         from cStringIO import StringIO
-        self.ts.to_string(buffer=StringIO())
+        buf = StringIO()
+
+        s = self.ts.to_string()
+
+        retval = self.ts.to_string(buf=buf)
+        self.assert_(retval is None)
+        self.assertEqual(buf.getvalue().strip(), s)
 
     def test_iter(self):
         for i, val in enumerate(self.series):