Add examples

Author: m-dz

pandas/core/frame.py

@@ -1568,6 +1568,83 @@ def to_csv(self, path_or_buf=None, sep=",", na_rep='', float_format=None,
         file.
         pandas.read_csv : Read a comma-separated values (CSV) file into
         a DataFrame.
+
+        Examples
+        --------
+        Setup:
+
+        >>> from csv import reader
+        >>> from tempfile import TemporaryFile
+        >>> def print_helper(temp):
+        ...     # Read and print a "raw" version of the input file
+        ...     # "Rewind" to the begining of the file
+        ...     _ = temp.seek(0)
+        ...     r = reader(temp, delimiter='X')
+        ...     for row in r:
+        ...         print(''.join(row))
+
+        A simple example of writing (and reading) a CSV file:
+
+        >>> df = pd.DataFrame({'col_a': [1, 2], 'col_b': [9, 8]},
+        ...                   index=['a','b'])
+        >>> df
+           col_a  col_b
+        a      1      9
+        b      2      8
+        >>> with TemporaryFile('w+') as temp:
+        ...     df.to_csv(temp)
+        ...     _ = temp.seek(0)
+        ...     df_out = pd.read_csv(temp, sep=',', index_col=0)
+        ...     print_helper(temp)
+        ,col_a,col_b
+        a,1,9
+        b,2,8
+        >>> df_out
+           col_a  col_b
+        a      1      9
+        b      2      8
+
+        Assert equality ignoring `dtype`
+
+        >>> pd.testing.assert_frame_equal(df, df_out, check_dtype=False)
+
+        **Custom formatting**
+
+        Write a CSV file with a custom separator, missing value representation,
+        and float and dates formatting:
+
+        >>> df = pd.DataFrame({
+        ...     'col_a': [1.0, 2.0],
+        ...     'col_b': [0.0001, 0.01],
+        ...     'date_col': pd.date_range('2018-03-10', '2018-03-11')
+        ... })
+        >>> df.iloc[0,0] = np.nan
+        >>> df
+           col_a   col_b   date_col
+        0    NaN  0.0001 2018-03-10
+        1    2.0  0.0100 2018-03-11
+        >>> with TemporaryFile('w+') as temp:
+        ...     df.to_csv(temp, sep=':', na_rep='NaNa', float_format='%.2f',
+        ...               date_format='%Y/%m/%d')
+        ...     _ = temp.seek(0)
+        ...     df_out = pd.read_csv(temp, sep=':', na_values='NaNa',
+        ...                          index_col=0, parse_dates=['date_col'])
+        ...     print_helper(temp)
+        :col_a:col_b:date_col
+        0:NaNa:0.00:2018/03/10
+        1:2.00:0.01:2018/03/11
+
+        Note the "standard" Python NaN representation "NaN"
+
+        >>> df_out
+           col_a  col_b   date_col
+        0    NaN   0.00 2018-03-10
+        1    2.0   0.01 2018-03-11
+
+        Assert equality with a rounded column to match the format used
+
+        >>> df['col_b'] = np.round(df.col_b, 2)
+        >>> pd.testing.assert_frame_equal(df, df_out, check_dtype=False)
         """
 
         if tupleize_cols is not None: