From 001536c25d4a35c61bd29ab818e7eca213cb0a82 Mon Sep 17 00:00:00 2001 From: amyfung Date: Thu, 11 Dec 2025 22:08:00 -0500 Subject: [PATCH] Replace @doc decorators with inline docstrings in _get_filepath_or_buffer, infer_compression, and get_handle --- pandas/io/common.py | 76 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 13 deletions(-) diff --git a/pandas/io/common.py b/pandas/io/common.py index 9d53dd22f7b2c..6b5ed73ceeb65 100644 --- a/pandas/io/common.py +++ b/pandas/io/common.py @@ -56,7 +56,6 @@ ReadCsvBuffer, ) from pandas.compat._optional import import_optional_dependency -from pandas.util._decorators import doc from pandas.util._exceptions import find_stack_level from pandas.core.dtypes.common import ( @@ -67,8 +66,6 @@ ) from pandas.core.dtypes.generic import ABCMultiIndex -from pandas.core.shared_docs import _shared_docs - _VALID_URLS = set(uses_relative + uses_netloc + uses_params) _VALID_URLS.discard("") _FSSPEC_URL_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9+\-+.]*(::[A-Za-z0-9+\-+.]+)*://") @@ -296,10 +293,6 @@ def is_fsspec_url(url: FilePath | BaseBuffer) -> bool: ) -@doc( - storage_options=_shared_docs["storage_options"], - compression_options=_shared_docs["compression_options"] % "filepath_or_buffer", -) def _get_filepath_or_buffer( filepath_or_buffer: FilePath | BaseBuffer, encoding: str = "utf-8", @@ -315,12 +308,37 @@ def _get_filepath_or_buffer( ---------- filepath_or_buffer : a url, filepath (str or pathlib.Path), or buffer - {compression_options} + compression : str or dict, default 'infer' + For on-the-fly compression of the output data. If 'infer' and + 'filepath_or_buffer' is path-like, then detect compression from the + following extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', + '.tar.gz', '.tar.xz' or '.tar.bz2' (otherwise no compression). + Set to ``None`` for no compression. + Can also be a dict with key ``'method'`` set + to one of {``'zip'``, ``'gzip'``, ``'bz2'``, ``'zstd'``, ``'xz'``, + ``'tar'``} and other key-value pairs are forwarded to + ``zipfile.ZipFile``, ``gzip.GzipFile``, ``bz2.BZ2File``, + ``zstandard.ZstdCompressor``, ``lzma.LZMAFile`` or + ``tarfile.TarFile``, respectively. + As an example, the following could be passed for faster compression and + to create a reproducible gzip archive: + ``compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}``. + + .. versionadded:: 1.5.0 + Added support for `.tar` files. encoding : the encoding to use to decode bytes, default is 'utf-8' mode : str, optional - {storage_options} + storage_options : dict, optional + Extra options that make sense for a particular storage connection, e.g. + host, port, username, password, etc. For HTTP(S) URLs the key-value pairs + are forwarded to ``urllib.request.Request`` as header options. For other + URLs (e.g. starting with "s3://", and "gcs://") the key-value pairs are + forwarded to ``fsspec.open``. Please see ``fsspec`` and ``urllib`` for more + details, and for more examples on storage options refer `here + `_. Returns the dataclass IOArgs. @@ -550,7 +568,6 @@ def get_compression_method( return compression_method, compression_args -@doc(compression_options=_shared_docs["compression_options"] % "filepath_or_buffer") def infer_compression( filepath_or_buffer: FilePath | BaseBuffer, compression: str | None ) -> str | None: @@ -564,7 +581,24 @@ def infer_compression( ---------- filepath_or_buffer : str or file handle File path or object. - {compression_options} + compression : str or dict, default 'infer' + For on-the-fly compression of the output data. If 'infer' and + 'filepath_or_buffer' is path-like, then detect compression from the + following extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', + '.tar.gz', '.tar.xz' or '.tar.bz2' (otherwise no compression). + Set to ``None`` for no compression. + Can also be a dict with key ``'method'`` set + to one of {``'zip'``, ``'gzip'``, ``'bz2'``, ``'zstd'``, ``'xz'``, + ``'tar'``} and other key-value pairs are forwarded to + ``zipfile.ZipFile``, ``gzip.GzipFile``, ``bz2.BZ2File``, + ``zstandard.ZstdCompressor``, ``lzma.LZMAFile`` or + ``tarfile.TarFile``, respectively. + As an example, the following could be passed for faster compression + and to create a reproducible gzip archive: + ``compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}``. + + .. versionadded:: 1.5.0 + Added support for `.tar` files. Returns ------- @@ -662,7 +696,6 @@ def get_handle( ) -> IOHandles[str] | IOHandles[bytes]: ... -@doc(compression_options=_shared_docs["compression_options"] % "path_or_buf") def get_handle( path_or_buf: FilePath | BaseBuffer, mode: str, @@ -685,7 +718,24 @@ def get_handle( Mode to open path_or_buf with. encoding : str or None Encoding to use. - {compression_options} + compression : str or dict, default 'infer' + For on-the-fly compression of the output data. If 'infer' and + 'path_or_buf' is path-like, then detect compression from the following + extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', + '.tar.xz' or '.tar.bz2' (otherwise no compression). + Set to ``None`` for no compression. + Can also be a dict with key ``'method'`` set + to one of {``'zip'``, ``'gzip'``, ``'bz2'``, ``'zstd'``, ``'xz'``, + ``'tar'``} and other key-value pairs are forwarded to + ``zipfile.ZipFile``, ``gzip.GzipFile``, ``bz2.BZ2File``, + ``zstandard.ZstdCompressor``, ``lzma.LZMAFile`` or + ``tarfile.TarFile``, respectively. + As an example, the following could be passed for faster compression + and to create a reproducible gzip archive: + ``compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}``. + + .. versionadded:: 1.5.0 + Added support for `.tar` files. May be a dict with key 'method' as compression mode and other keys as compression options if compression