diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 9f2112729a503..3cd1906b3a557 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1901,14 +1901,15 @@ def to_sql(self, name, con, schema=None, if_exists='fail', index=True, def to_pickle(self, path, compression='infer', protocol=pkl.HIGHEST_PROTOCOL): """ - Pickle (serialize) object to input file path. + Pickle (serialize) object to file. Parameters ---------- - path : string - File path + path : str + File path where the pickled object will be stored. compression : {'infer', 'gzip', 'bz2', 'xz', None}, default 'infer' - a string representing the compression to use in the output file + A string representing the compression to use in the output file. By + default, infers from the file extension in specified path. .. versionadded:: 0.20.0 protocol : int @@ -1916,13 +1917,43 @@ def to_pickle(self, path, compression='infer', default HIGHEST_PROTOCOL (see [1], paragraph 12.1.2). The possible values for this parameter depend on the version of Python. For Python 2.x, possible values are 0, 1, 2. For Python>=3.0, 3 is a - valid value. For Python >= 3.4, 4 is a valid value.A negative value - for the protocol parameter is equivalent to setting its value to - HIGHEST_PROTOCOL. + valid value. For Python >= 3.4, 4 is a valid value. A negative + value for the protocol parameter is equivalent to setting its value + to HIGHEST_PROTOCOL. .. [1] https://docs.python.org/3/library/pickle.html .. versionadded:: 0.21.0 + See Also + -------- + read_pickle : Load pickled pandas object (or any object) from file. + DataFrame.to_hdf : Write DataFrame to an HDF5 file. + DataFrame.to_sql : Write DataFrame to a SQL database. + DataFrame.to_parquet : Write a DataFrame to the binary parquet format. + + Examples + -------- + >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + >>> original_df.to_pickle("./dummy.pkl") + + >>> unpickled_df = pd.read_pickle("./dummy.pkl") + >>> unpickled_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + + >>> import os + >>> os.remove("./dummy.pkl") """ from pandas.io.pickle import to_pickle return to_pickle(self, path, compression=compression, diff --git a/pandas/io/pickle.py b/pandas/io/pickle.py index 756096dd0c9ce..8c72c315c142c 100644 --- a/pandas/io/pickle.py +++ b/pandas/io/pickle.py @@ -10,15 +10,17 @@ def to_pickle(obj, path, compression='infer', protocol=pkl.HIGHEST_PROTOCOL): """ - Pickle (serialize) object to input file path + Pickle (serialize) object to file. Parameters ---------- obj : any object - path : string - File path + Any python object. + path : str + File path where the pickled object will be stored. compression : {'infer', 'gzip', 'bz2', 'xz', None}, default 'infer' - a string representing the compression to use in the output file + A string representing the compression to use in the output file. By + default, infers from the file extension in specified path. .. versionadded:: 0.20.0 protocol : int @@ -33,7 +35,36 @@ def to_pickle(obj, path, compression='infer', protocol=pkl.HIGHEST_PROTOCOL): .. [1] https://docs.python.org/3/library/pickle.html .. versionadded:: 0.21.0 - + See Also + -------- + read_pickle : Load pickled pandas object (or any object) from file. + DataFrame.to_hdf : Write DataFrame to an HDF5 file. + DataFrame.to_sql : Write DataFrame to a SQL database. + DataFrame.to_parquet : Write a DataFrame to the binary parquet format. + + Examples + -------- + >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + >>> pd.to_pickle(original_df, "./dummy.pkl") + + >>> unpickled_df = pd.read_pickle("./dummy.pkl") + >>> unpickled_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + + >>> import os + >>> os.remove("./dummy.pkl") """ path = _stringify_path(path) inferred_compression = _infer_compression(path, compression) @@ -51,16 +82,17 @@ def to_pickle(obj, path, compression='infer', protocol=pkl.HIGHEST_PROTOCOL): def read_pickle(path, compression='infer'): """ - Load pickled pandas object (or any other pickled object) from the specified - file path + Load pickled pandas object (or any object) from file. + + .. warning:: - Warning: Loading pickled data received from untrusted sources can be - unsafe. See: https://docs.python.org/3/library/pickle.html + Loading pickled data received from untrusted sources can be + unsafe. See `here `__. Parameters ---------- - path : string - File path + path : str + File path where the pickled object will be loaded. compression : {'infer', 'gzip', 'bz2', 'xz', 'zip', None}, default 'infer' For on-the-fly decompression of on-disk data. If 'infer', then use gzip, bz2, xz or zip if path ends in '.gz', '.bz2', '.xz', @@ -72,6 +104,38 @@ def read_pickle(path, compression='infer'): Returns ------- unpickled : type of object stored in file + + See Also + -------- + DataFrame.to_pickle : Pickle (serialize) DataFrame object to file. + Series.to_pickle : Pickle (serialize) Series object to file. + read_hdf : Read HDF5 file into a DataFrame. + read_sql : Read SQL query or database table into a DataFrame. + read_parquet : Load a parquet object, returning a DataFrame. + + Examples + -------- + >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + >>> pd.to_pickle(original_df, "./dummy.pkl") + + >>> unpickled_df = pd.read_pickle("./dummy.pkl") + >>> unpickled_df + foo bar + 0 0 5 + 1 1 6 + 2 2 7 + 3 3 8 + 4 4 9 + + >>> import os + >>> os.remove("./dummy.pkl") """ path = _stringify_path(path) inferred_compression = _infer_compression(path, compression)