diff --git a/pandas/core/frame.py b/pandas/core/frame.py index abf9b3d8823aa..27713b5bde201 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -118,7 +118,7 @@ ) from pandas.core.dtypes.missing import isna, notna -from pandas.core import algorithms, common as com, nanops, ops +from pandas.core import algorithms, common as com, generic, nanops, ops from pandas.core.accessor import CachedAccessor from pandas.core.aggregation import ( aggregate, @@ -2066,6 +2066,7 @@ def _from_arrays( ) return cls(mgr) + @doc(storage_options=generic._shared_docs["storage_options"]) @deprecate_kwarg(old_arg_name="fname", new_arg_name="path") def to_stata( self, @@ -2118,7 +2119,7 @@ def to_stata( variable_labels : dict Dictionary containing columns as keys and variable labels as values. Each label must be 80 characters or smaller. - version : {114, 117, 118, 119, None}, default 114 + version : {{114, 117, 118, 119, None}}, default 114 Version to use in the output dta file. Set to None to let pandas decide between 118 or 119 formats depending on the number of columns in the frame. Version 114 can be read by Stata 10 and @@ -2147,23 +2148,17 @@ def to_stata( compression : str or dict, default 'infer' For on-the-fly compression of the output dta. If string, specifies compression mode. If dict, value at key 'method' specifies - compression mode. Compression mode must be one of {'infer', 'gzip', - 'bz2', 'zip', 'xz', None}. If compression mode is 'infer' and + compression mode. Compression mode must be one of {{'infer', 'gzip', + 'bz2', 'zip', 'xz', None}}. If compression mode is 'infer' and `fname` is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', or '.xz' (otherwise no - compression). If dict and compression mode is one of {'zip', - 'gzip', 'bz2'}, or inferred as one of the above, other entries + compression). If dict and compression mode is one of {{'zip', + 'gzip', 'bz2'}}, or inferred as one of the above, other entries passed as additional compression options. .. versionadded:: 1.1.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -2186,9 +2181,9 @@ def to_stata( Examples -------- - >>> df = pd.DataFrame({'animal': ['falcon', 'parrot', 'falcon', + >>> df = pd.DataFrame({{'animal': ['falcon', 'parrot', 'falcon', ... 'parrot'], - ... 'speed': [350, 18, 361, 15]}) + ... 'speed': [350, 18, 361, 15]}}) >>> df.to_stata('animals.dta') # doctest: +SKIP """ if version not in (114, 117, 118, 119, None): @@ -2255,6 +2250,7 @@ def to_feather(self, path: FilePathOrBuffer[AnyStr], **kwargs) -> None: @doc( Series.to_markdown, klass=_shared_doc_kwargs["klass"], + storage_options=_shared_docs["storage_options"], examples="""Examples -------- >>> df = pd.DataFrame( @@ -2307,6 +2303,7 @@ def to_markdown( handles.handle.writelines(result) return None + @doc(storage_options=generic._shared_docs["storage_options"]) @deprecate_kwarg(old_arg_name="fname", new_arg_name="path") def to_parquet( self, @@ -2340,12 +2337,12 @@ def to_parquet( Previously this was "fname" - engine : {'auto', 'pyarrow', 'fastparquet'}, default 'auto' + engine : {{'auto', 'pyarrow', 'fastparquet'}}, default 'auto' Parquet library to use. If 'auto', then the option ``io.parquet.engine`` is used. The default ``io.parquet.engine`` behavior is to try 'pyarrow', falling back to 'fastparquet' if 'pyarrow' is unavailable. - compression : {'snappy', 'gzip', 'brotli', None}, default 'snappy' + compression : {{'snappy', 'gzip', 'brotli', None}}, default 'snappy' Name of the compression to use. Use ``None`` for no compression. index : bool, default None If ``True``, include the dataframe's index(es) in the file output. @@ -2365,13 +2362,7 @@ def to_parquet( .. versionadded:: 0.24.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -2398,7 +2389,7 @@ def to_parquet( Examples -------- - >>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [3, 4]}) + >>> df = pd.DataFrame(data={{'col1': [1, 2], 'col2': [3, 4]}}) >>> df.to_parquet('df.parquet.gzip', ... compression='gzip') # doctest: +SKIP >>> pd.read_parquet('df.parquet.gzip') # doctest: +SKIP diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 73f1e7127dca4..8b71ff83400d1 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2024,7 +2024,7 @@ def _repr_data_resource_(self): # I/O Methods @final - @doc(klass="object") + @doc(klass="object", storage_options=_shared_docs["storage_options"]) def to_excel( self, excel_writer, @@ -2101,10 +2101,7 @@ def to_excel( freeze_panes : tuple of int (length 2), optional Specifies the one-based bottommost row and rightmost column that is to be frozen. - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". + {storage_options} .. versionadded:: 1.2.0 @@ -2185,6 +2182,7 @@ def to_excel( ) @final + @doc(storage_options=_shared_docs["storage_options"]) def to_json( self, path_or_buf: Optional[FilePathOrBuffer] = None, @@ -2217,27 +2215,27 @@ def to_json( * Series: - default is 'index' - - allowed values are: {'split', 'records', 'index', 'table'}. + - allowed values are: {{'split', 'records', 'index', 'table'}}. * DataFrame: - default is 'columns' - - allowed values are: {'split', 'records', 'index', 'columns', - 'values', 'table'}. + - allowed values are: {{'split', 'records', 'index', 'columns', + 'values', 'table'}}. * The format of the JSON string: - - 'split' : dict like {'index' -> [index], 'columns' -> [columns], - 'data' -> [values]} - - 'records' : list like [{column -> value}, ... , {column -> value}] - - 'index' : dict like {index -> {column -> value}} - - 'columns' : dict like {column -> {index -> value}} + - 'split' : dict like {{'index' -> [index], 'columns' -> [columns], + 'data' -> [values]}} + - 'records' : list like [{{column -> value}}, ... , {{column -> value}}] + - 'index' : dict like {{index -> {{column -> value}}}} + - 'columns' : dict like {{column -> {{index -> value}}}} - 'values' : just the values array - - 'table' : dict like {'schema': {schema}, 'data': {data}} + - 'table' : dict like {{'schema': {{schema}}, 'data': {{data}}}} Describing the data, where data component is like ``orient='records'``. - date_format : {None, 'epoch', 'iso'} + date_format : {{None, 'epoch', 'iso'}} Type of date conversion. 'epoch' = epoch milliseconds, 'iso' = ISO8601. The default depends on the `orient`. For ``orient='table'``, the default is 'iso'. For all other orients, @@ -2260,7 +2258,7 @@ def to_json( throw ValueError if incorrect 'orient' since others are not list like. - compression : {'infer', 'gzip', 'bz2', 'zip', 'xz', None} + compression : {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}} A string representing the compression to use in the output file, only used when the first argument is a filename. By default, the @@ -2277,13 +2275,7 @@ def to_json( .. versionadded:: 1.0.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -2320,7 +2312,7 @@ def to_json( >>> result = df.to_json(orient="split") >>> parsed = json.loads(result) >>> json.dumps(parsed, indent=4) # doctest: +SKIP - { + {{ "columns": [ "col 1", "col 2" @@ -2339,7 +2331,7 @@ def to_json( "d" ] ] - } + }} Encoding/decoding a Dataframe using ``'records'`` formatted JSON. Note that index labels are not preserved with this encoding. @@ -2348,14 +2340,14 @@ def to_json( >>> parsed = json.loads(result) >>> json.dumps(parsed, indent=4) # doctest: +SKIP [ - { + {{ "col 1": "a", "col 2": "b" - }, - { + }}, + {{ "col 1": "c", "col 2": "d" - } + }} ] Encoding/decoding a Dataframe using ``'index'`` formatted JSON: @@ -2363,32 +2355,32 @@ def to_json( >>> result = df.to_json(orient="index") >>> parsed = json.loads(result) >>> json.dumps(parsed, indent=4) # doctest: +SKIP - { - "row 1": { + {{ + "row 1": {{ "col 1": "a", "col 2": "b" - }, - "row 2": { + }}, + "row 2": {{ "col 1": "c", "col 2": "d" - } - } + }} + }} Encoding/decoding a Dataframe using ``'columns'`` formatted JSON: >>> result = df.to_json(orient="columns") >>> parsed = json.loads(result) >>> json.dumps(parsed, indent=4) # doctest: +SKIP - { - "col 1": { + {{ + "col 1": {{ "row 1": "a", "row 2": "c" - }, - "col 2": { + }}, + "col 2": {{ "row 1": "b", "row 2": "d" - } - } + }} + }} Encoding/decoding a Dataframe using ``'values'`` formatted JSON: @@ -2411,40 +2403,40 @@ def to_json( >>> result = df.to_json(orient="table") >>> parsed = json.loads(result) >>> json.dumps(parsed, indent=4) # doctest: +SKIP - { - "schema": { + {{ + "schema": {{ "fields": [ - { + {{ "name": "index", "type": "string" - }, - { + }}, + {{ "name": "col 1", "type": "string" - }, - { + }}, + {{ "name": "col 2", "type": "string" - } + }} ], "primaryKey": [ "index" ], "pandas_version": "0.20.0" - }, + }}, "data": [ - { + {{ "index": "row 1", "col 1": "a", "col 2": "b" - }, - { + }}, + {{ "index": "row 2", "col 1": "c", "col 2": "d" - } + }} ] - } + }} """ from pandas.io import json @@ -2783,6 +2775,7 @@ def to_sql( ) @final + @doc(storage_options=_shared_docs["storage_options"]) def to_pickle( self, path, @@ -2797,7 +2790,7 @@ def to_pickle( ---------- path : str File path where the pickled object will be stored. - compression : {'infer', 'gzip', 'bz2', 'zip', 'xz', None}, \ + compression : {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}}, \ default 'infer' A string representing the compression to use in the output file. By default, infers from the file extension in specified path. @@ -2809,13 +2802,7 @@ def to_pickle( .. [1] https://docs.python.org/3/library/pickle.html. - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -2828,7 +2815,7 @@ def to_pickle( Examples -------- - >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df = pd.DataFrame({{"foo": range(5), "bar": range(5, 10)}}) >>> original_df foo bar 0 0 5 @@ -3193,6 +3180,7 @@ def to_latex( ) @final + @doc(storage_options=_shared_docs["storage_options"]) def to_csv( self, path_or_buf: Optional[FilePathOrBuffer] = None, @@ -3272,11 +3260,11 @@ def to_csv( compression : str or dict, default 'infer' If str, represents compression mode. If dict, value at 'method' is the compression mode. Compression mode may be any of the following - possible values: {'infer', 'gzip', 'bz2', 'zip', 'xz', None}. If + possible values: {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}}. If compression mode is 'infer' and `path_or_buf` is path-like, then detect compression mode from the following extensions: '.gz', '.bz2', '.zip' or '.xz'. (otherwise no compression). If dict given - and mode is one of {'zip', 'gzip', 'bz2'}, or inferred as + and mode is one of {{'zip', 'gzip', 'bz2'}}, or inferred as one of the above, other entries passed as additional compression options. @@ -3333,13 +3321,7 @@ def to_csv( .. versionadded:: 1.1.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -3356,9 +3338,9 @@ def to_csv( Examples -------- - >>> df = pd.DataFrame({'name': ['Raphael', 'Donatello'], + >>> df = pd.DataFrame({{'name': ['Raphael', 'Donatello'], ... 'mask': ['red', 'purple'], - ... 'weapon': ['sai', 'bo staff']}) + ... 'weapon': ['sai', 'bo staff']}}) >>> df.to_csv(index=False) 'name,mask,weapon\nRaphael,red,sai\nDonatello,purple,bo staff\n' diff --git a/pandas/core/series.py b/pandas/core/series.py index 42a87b003f634..d59e72a04209c 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1428,6 +1428,7 @@ def to_string( @doc( klass=_shared_doc_kwargs["klass"], + storage_options=generic._shared_docs["storage_options"], examples=dedent( """ Examples @@ -1466,14 +1467,7 @@ def to_markdown( Add index (row) labels. .. versionadded:: 1.1.0 - - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 diff --git a/pandas/core/shared_docs.py b/pandas/core/shared_docs.py index cc918c27b5c2e..7085761ca4d99 100644 --- a/pandas/core/shared_docs.py +++ b/pandas/core/shared_docs.py @@ -325,3 +325,13 @@ 1 1.000000 2.718282 2 1.414214 7.389056 """ + +_shared_docs[ + "storage_options" +] = """storage_options : dict, optional + Extra options that make sense for a particular storage connection, e.g. + host, port, username, password, etc., if using a URL that will + be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error + will be raised if providing this argument with a non-fsspec URL. + See the fsspec and backend storage implementation docs for the set of + allowed keys and values.""" diff --git a/pandas/io/feather_format.py b/pandas/io/feather_format.py index 9e63976bf8cf9..422677771b4d0 100644 --- a/pandas/io/feather_format.py +++ b/pandas/io/feather_format.py @@ -4,12 +4,15 @@ from pandas._typing import FilePathOrBuffer, StorageOptions from pandas.compat._optional import import_optional_dependency +from pandas.util._decorators import doc from pandas import DataFrame, Int64Index, RangeIndex +from pandas.core import generic from pandas.io.common import get_handle +@doc(storage_options=generic._shared_docs["storage_options"]) def to_feather( df: DataFrame, path: FilePathOrBuffer[AnyStr], @@ -23,13 +26,7 @@ def to_feather( ---------- df : DataFrame path : string file path, or file-like object - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -83,6 +80,7 @@ def to_feather( feather.write_feather(df, handles.handle, **kwargs) +@doc(storage_options=generic._shared_docs["storage_options"]) def read_feather( path, columns=None, use_threads: bool = True, storage_options: StorageOptions = None ): @@ -111,13 +109,7 @@ def read_feather( Whether to parallelize reading using multiple threads. .. versionadded:: 0.24.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 diff --git a/pandas/io/formats/excel.py b/pandas/io/formats/excel.py index fe471c6f6f9ac..842cf4b555b3e 100644 --- a/pandas/io/formats/excel.py +++ b/pandas/io/formats/excel.py @@ -11,12 +11,14 @@ import numpy as np from pandas._typing import Label, StorageOptions +from pandas.util._decorators import doc from pandas.core.dtypes import missing from pandas.core.dtypes.common import is_float, is_scalar from pandas.core.dtypes.generic import ABCIndex from pandas import DataFrame, Index, MultiIndex, PeriodIndex +from pandas.core import generic import pandas.core.common as com from pandas.io.formats.css import CSSResolver, CSSWarning @@ -776,6 +778,7 @@ def get_formatted_cells(self): cell.val = self._format_value(cell.val) yield cell + @doc(storage_options=generic._shared_docs["storage_options"]) def write( self, writer, @@ -802,10 +805,7 @@ def write( write engine to use if writer is a path - you can also set this via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and ``io.excel.xlsm.writer``. - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". + {storage_options} .. versionadded:: 1.2.0 """ diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 2f3416cbf2d87..4b7a5e76cb475 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -1,7 +1,6 @@ """ Module for applying conditional formatting to DataFrames and Series. """ - from collections import defaultdict from contextlib import contextmanager import copy @@ -33,6 +32,7 @@ import pandas as pd from pandas.api.types import is_dict_like, is_list_like +from pandas.core import generic import pandas.core.common as com from pandas.core.frame import DataFrame from pandas.core.generic import NDFrame @@ -204,7 +204,11 @@ def _repr_html_(self) -> str: """ return self.render() - @doc(NDFrame.to_excel, klass="Styler") + @doc( + NDFrame.to_excel, + klass="Styler", + storage_options=generic._shared_docs["storage_options"], + ) def to_excel( self, excel_writer, diff --git a/pandas/io/json/_json.py b/pandas/io/json/_json.py index 1f62b6a8096a8..8129d58d5cb34 100644 --- a/pandas/io/json/_json.py +++ b/pandas/io/json/_json.py @@ -16,11 +16,12 @@ StorageOptions, ) from pandas.errors import AbstractMethodError -from pandas.util._decorators import deprecate_kwarg, deprecate_nonkeyword_arguments +from pandas.util._decorators import deprecate_kwarg, deprecate_nonkeyword_arguments, doc from pandas.core.dtypes.common import ensure_str, is_period_dtype from pandas import DataFrame, MultiIndex, Series, isna, to_datetime +from pandas.core import generic from pandas.core.construction import create_series_with_explicit_dtype from pandas.core.generic import NDFrame from pandas.core.reshape.concat import concat @@ -286,6 +287,7 @@ def obj_to_write(self) -> Union[NDFrame, Mapping[IndexLabel, Any]]: return {"schema": self.schema, "data": self.obj} +@doc(storage_options=generic._shared_docs["storage_options"]) @deprecate_kwarg(old_arg_name="numpy", new_arg_name=None) @deprecate_nonkeyword_arguments( version="2.0", allowed_args=["path_or_buf"], stacklevel=3 @@ -332,11 +334,11 @@ def read_json( The set of possible orients is: - ``'split'`` : dict like - ``{index -> [index], columns -> [columns], data -> [values]}`` + ``{{index -> [index], columns -> [columns], data -> [values]}}`` - ``'records'`` : list like - ``[{column -> value}, ... , {column -> value}]`` - - ``'index'`` : dict like ``{index -> {column -> value}}`` - - ``'columns'`` : dict like ``{column -> {index -> value}}`` + ``[{{column -> value}}, ... , {{column -> value}}]`` + - ``'index'`` : dict like ``{{index -> {{column -> value}}}}`` + - ``'columns'`` : dict like ``{{column -> {{index -> value}}}}`` - ``'values'`` : just the values array The allowed and default values depend on the value @@ -344,21 +346,21 @@ def read_json( * when ``typ == 'series'``, - - allowed orients are ``{'split','records','index'}`` + - allowed orients are ``{{'split','records','index'}}`` - default is ``'index'`` - The Series index must be unique for orient ``'index'``. * when ``typ == 'frame'``, - - allowed orients are ``{'split','records','index', - 'columns','values', 'table'}`` + - allowed orients are ``{{'split','records','index', + 'columns','values', 'table'}}`` - default is ``'columns'`` - The DataFrame index must be unique for orients ``'index'`` and ``'columns'``. - The DataFrame columns must be unique for orients ``'index'``, ``'columns'``, and ``'records'``. - typ : {'frame', 'series'}, default 'frame' + typ : {{'frame', 'series'}}, default 'frame' The type of object to recover. dtype : bool or dict, default None @@ -435,7 +437,7 @@ def read_json( This can only be passed if `lines=True`. If this is None, the file will be read into memory all at once. - compression : {'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer' + compression : {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}}, default 'infer' For on-the-fly decompression of on-disk data. If 'infer', then use gzip, bz2, zip or xz if path_or_buf is a string ending in '.gz', '.bz2', '.zip', or 'xz', respectively, and no decompression @@ -449,13 +451,7 @@ def read_json( .. versionadded:: 1.1 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -489,9 +485,9 @@ def read_json( Encoding/decoding a Dataframe using ``'split'`` formatted JSON: >>> df.to_json(orient='split') - '{"columns":["col 1","col 2"], + '{{"columns":["col 1","col 2"], "index":["row 1","row 2"], - "data":[["a","b"],["c","d"]]}' + "data":[["a","b"],["c","d"]]}}' >>> pd.read_json(_, orient='split') col 1 col 2 row 1 a b @@ -500,7 +496,7 @@ def read_json( Encoding/decoding a Dataframe using ``'index'`` formatted JSON: >>> df.to_json(orient='index') - '{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}' + '{{"row 1":{{"col 1":"a","col 2":"b"}},"row 2":{{"col 1":"c","col 2":"d"}}}}' >>> pd.read_json(_, orient='index') col 1 col 2 row 1 a b @@ -510,7 +506,7 @@ def read_json( Note that index labels are not preserved with this encoding. >>> df.to_json(orient='records') - '[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]' + '[{{"col 1":"a","col 2":"b"}},{{"col 1":"c","col 2":"d"}}]' >>> pd.read_json(_, orient='records') col 1 col 2 0 a b @@ -519,13 +515,13 @@ def read_json( Encoding with Table Schema >>> df.to_json(orient='table') - '{"schema": {"fields": [{"name": "index", "type": "string"}, - {"name": "col 1", "type": "string"}, - {"name": "col 2", "type": "string"}], + '{{"schema": {{"fields": [{{"name": "index", "type": "string"}}, + {{"name": "col 1", "type": "string"}}, + {{"name": "col 2", "type": "string"}}], "primaryKey": "index", - "pandas_version": "0.20.0"}, - "data": [{"index": "row 1", "col 1": "a", "col 2": "b"}, - {"index": "row 2", "col 1": "c", "col 2": "d"}]}' + "pandas_version": "0.20.0"}}, + "data": [{{"index": "row 1", "col 1": "a", "col 2": "b"}}, + {{"index": "row 2", "col 1": "c", "col 2": "d"}}]}}' """ if orient == "table" and dtype: raise ValueError("cannot pass both dtype and orient='table'") diff --git a/pandas/io/parquet.py b/pandas/io/parquet.py index 10c70b9a5c43a..a19b132a7891d 100644 --- a/pandas/io/parquet.py +++ b/pandas/io/parquet.py @@ -8,8 +8,10 @@ from pandas._typing import FilePathOrBuffer, StorageOptions from pandas.compat._optional import import_optional_dependency from pandas.errors import AbstractMethodError +from pandas.util._decorators import doc from pandas import DataFrame, MultiIndex, get_option +from pandas.core import generic from pandas.io.common import IOHandles, get_handle, is_fsspec_url, stringify_path @@ -280,6 +282,7 @@ def read( return result +@doc(storage_options=generic._shared_docs["storage_options"]) def to_parquet( df: DataFrame, path: Optional[FilePathOrBuffer] = None, @@ -306,12 +309,12 @@ def to_parquet( .. versionchanged:: 1.2.0 - engine : {'auto', 'pyarrow', 'fastparquet'}, default 'auto' + engine : {{'auto', 'pyarrow', 'fastparquet'}}, default 'auto' Parquet library to use. If 'auto', then the option ``io.parquet.engine`` is used. The default ``io.parquet.engine`` behavior is to try 'pyarrow', falling back to 'fastparquet' if 'pyarrow' is unavailable. - compression : {'snappy', 'gzip', 'brotli', None}, default 'snappy' + compression : {{'snappy', 'gzip', 'brotli', None}}, default 'snappy' Name of the compression to use. Use ``None`` for no compression. index : bool, default None If ``True``, include the dataframe's index(es) in the file output. If @@ -331,13 +334,7 @@ def to_parquet( .. versionadded:: 0.24.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values + {storage_options} .. versionadded:: 1.2.0 diff --git a/pandas/io/parsers.py b/pandas/io/parsers.py index 8d9787a9c8c9e..eb29f6c0d0c48 100644 --- a/pandas/io/parsers.py +++ b/pandas/io/parsers.py @@ -62,7 +62,7 @@ from pandas.core.dtypes.dtypes import CategoricalDtype from pandas.core.dtypes.missing import isna -from pandas.core import algorithms +from pandas.core import algorithms, generic from pandas.core.arrays import Categorical from pandas.core.frame import DataFrame from pandas.core.indexes.api import ( @@ -355,13 +355,7 @@ .. versionchanged:: 1.2 -storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. +{storage_options} .. versionadded:: 1.2 @@ -532,6 +526,7 @@ def _read(filepath_or_buffer: FilePathOrBuffer, kwds): func_name="read_csv", summary="Read a comma-separated values (csv) file into DataFrame.", _default_sep="','", + storage_options=generic._shared_docs["storage_options"], ) ) def read_csv( @@ -611,6 +606,7 @@ def read_csv( func_name="read_table", summary="Read general delimited file into DataFrame.", _default_sep=r"'\\t' (tab-stop)", + storage_options=generic._shared_docs["storage_options"], ) ) def read_table( diff --git a/pandas/io/pickle.py b/pandas/io/pickle.py index 7d09029aded1b..a5507259b7b6a 100644 --- a/pandas/io/pickle.py +++ b/pandas/io/pickle.py @@ -5,10 +5,14 @@ from pandas._typing import CompressionOptions, FilePathOrBuffer, StorageOptions from pandas.compat import pickle_compat as pc +from pandas.util._decorators import doc + +from pandas.core import generic from pandas.io.common import get_handle +@doc(storage_options=generic._shared_docs["storage_options"]) def to_pickle( obj: Any, filepath_or_buffer: FilePathOrBuffer, @@ -29,7 +33,7 @@ def to_pickle( .. versionchanged:: 1.0.0 Accept URL. URL has to be of S3 or GCS. - compression : {'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer' + compression : {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}}, default 'infer' If 'infer' and 'path_or_url' is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', or '.xz' (otherwise no compression) If 'infer' and 'path_or_url' is not path-like, then use @@ -43,13 +47,7 @@ def to_pickle( protocol parameter is equivalent to setting its value to HIGHEST_PROTOCOL. - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -64,7 +62,7 @@ def to_pickle( Examples -------- - >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df = pd.DataFrame({{"foo": range(5), "bar": range(5, 10)}}) >>> original_df foo bar 0 0 5 @@ -99,6 +97,7 @@ def to_pickle( pickle.dump(obj, handles.handle, protocol=protocol) # type: ignore[arg-type] +@doc(storage_options=generic._shared_docs["storage_options"]) def read_pickle( filepath_or_buffer: FilePathOrBuffer, compression: CompressionOptions = "infer", @@ -120,19 +119,13 @@ def read_pickle( .. versionchanged:: 1.0.0 Accept URL. URL is not limited to S3 and GCS. - compression : {'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer' + compression : {{'infer', 'gzip', 'bz2', 'zip', 'xz', None}}, default 'infer' If 'infer' and 'path_or_url' is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', or '.xz' (otherwise no compression) If 'infer' and 'path_or_url' is not path-like, then use None (= no decompression). - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values. + {storage_options} .. versionadded:: 1.2.0 @@ -154,7 +147,7 @@ def read_pickle( Examples -------- - >>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) + >>> original_df = pd.DataFrame({{"foo": range(5), "bar": range(5, 10)}}) >>> original_df foo bar 0 0 5 diff --git a/pandas/io/stata.py b/pandas/io/stata.py index 1f8d9b6213a71..e8b61c3c40291 100644 --- a/pandas/io/stata.py +++ b/pandas/io/stata.py @@ -31,7 +31,7 @@ Label, StorageOptions, ) -from pandas.util._decorators import Appender +from pandas.util._decorators import Appender, doc from pandas.core.dtypes.common import ( ensure_object, @@ -49,6 +49,7 @@ to_datetime, to_timedelta, ) +from pandas.core import generic from pandas.core.frame import DataFrame from pandas.core.indexes.base import Index from pandas.core.series import Series @@ -2060,6 +2061,7 @@ def _dtype_to_default_stata_fmt( raise NotImplementedError(f"Data type {dtype} not supported.") +@doc(storage_options=generic._shared_docs["storage_options"]) class StataWriter(StataParser): """ A class for writing Stata binary dta files @@ -2094,22 +2096,16 @@ class StataWriter(StataParser): compression : str or dict, default 'infer' For on-the-fly compression of the output dta. If string, specifies compression mode. If dict, value at key 'method' specifies compression - mode. Compression mode must be one of {'infer', 'gzip', 'bz2', 'zip', - 'xz', None}. If compression mode is 'infer' and `fname` is path-like, + mode. Compression mode must be one of {{'infer', 'gzip', 'bz2', 'zip', + 'xz', None}}. If compression mode is 'infer' and `fname` is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', or '.xz' (otherwise no compression). If dict and compression - mode is one of {'zip', 'gzip', 'bz2'}, or inferred as one of the above, + mode is one of {{'zip', 'gzip', 'bz2'}}, or inferred as one of the above, other entries passed as additional compression options. .. versionadded:: 1.1.0 - storage_options : dict, optional - Extra options that make sense for a particular storage connection, e.g. - host, port, username, password, etc., if using a URL that will - be parsed by ``fsspec``, e.g., starting "s3://", "gcs://". An error - will be raised if providing this argument with a local path or - a file-like buffer. See the fsspec and backend storage implementation - docs for the set of allowed keys and values + {storage_options} .. versionadded:: 1.2.0 @@ -2137,14 +2133,14 @@ class StataWriter(StataParser): >>> writer.write_file() Directly write a zip file - >>> compression = {"method": "zip", "archive_name": "data_file.dta"} + >>> compression = {{"method": "zip", "archive_name": "data_file.dta"}} >>> writer = StataWriter('./data_file.zip', data, compression=compression) >>> writer.write_file() Save a DataFrame with dates >>> from datetime import datetime >>> data = pd.DataFrame([[datetime(2000,1,1)]], columns=['date']) - >>> writer = StataWriter('./date_data_file.dta', data, {'date' : 'tw'}) + >>> writer = StataWriter('./date_data_file.dta', data, {{'date' : 'tw'}}) >>> writer.write_file() """