DOC: update file path descriptions in IO docstrings (#25164)

Author: enricorotundo

pandas/io/excel/_base.py

@@ -41,10 +41,16 @@
 
 Parameters
 ----------
-io : str, file descriptor, pathlib.Path, ExcelFile or xlrd.Book
-    The string could be a URL. Valid URL schemes include http, ftp, s3,
-    gcs, and file. For file URLs, a host is expected. For instance, a local
-    file could be /path/to/workbook.xlsx.
+io : str, ExcelFile, xlrd.Book, path object or file-like object
+    Any valid string path is acceptable. The string could be a URL. Valid
+    URL schemes include http, ftp, s3, and file. For file URLs, a host is
+    expected. A local file could be: ``file://localhost/path/to/table.xlsx``.
+
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
+
+    By file-like object, we refer to objects with a ``read()`` method,
+    such as a file handler (e.g. via builtin ``open`` function)
+    or ``StringIO``.
 sheet_name : str, int, list, or None, default 0
     Strings are used for sheet names. Integers are used in zero-indexed
     sheet positions. Lists of strings/integers are used to request

pandas/io/feather_format.py

@@ -69,24 +69,35 @@ def to_feather(df, path):
 @deprecate_kwarg(old_arg_name="nthreads", new_arg_name="use_threads")
 def read_feather(path, columns=None, use_threads=True):
     """
-    Load a feather-format object from the file path
+    Load a feather-format object from the file path.
 
     .. versionadded 0.20.0
 
     Parameters
     ----------
-    path : string file path, or file-like object
+    path : str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.feather``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function)
+        or ``StringIO``.
     columns : sequence, default None
-        If not provided, all columns are read
+        If not provided, all columns are read.
 
         .. versionadded 0.24.0
     nthreads : int, default 1
-        Number of CPU threads to use when reading to pandas.DataFrame
+        Number of CPU threads to use when reading to pandas.DataFrame.
 
        .. versionadded 0.21.0
        .. deprecated 0.24.0
     use_threads : bool, default True
-        Whether to parallelize reading using multiple threads
+        Whether to parallelize reading using multiple threads.
 
        .. versionadded 0.24.0
 

pandas/io/html.py

@@ -941,7 +941,7 @@ def read_html(
 
     Parameters
     ----------
-    io : str or file-like
+    io : str, path object or file-like object
         A URL, a file-like object, or a raw string containing HTML. Note that
         lxml only accepts the http, ftp and file url protocols. If you have a
         URL that starts with ``'https'`` you might try removing the ``'s'``.

pandas/io/json/_json.py

@@ -352,11 +352,18 @@ def read_json(
 
     Parameters
     ----------
-    path_or_buf : a valid JSON string or file-like, default: None
-        The string could be a URL. Valid URL schemes include http, ftp, s3,
-        gcs, and file. For file URLs, a host is expected. For instance, a local
-        file could be ``file://localhost/path/to/table.json``
-
+    path_or_buf : a valid JSON str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.json``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function)
+        or ``StringIO``.
     orient : string,
         Indication of expected JSON string format.
         Compatible JSON strings can be produced by ``to_json()`` with a

pandas/io/packers.py

@@ -156,7 +156,7 @@ def writer(fh):
 def read_msgpack(path_or_buf, encoding="utf-8", iterator=False, **kwargs):
     """
     Load msgpack pandas object from the specified
-    file path
+    file path.
 
     .. deprecated:: 0.25.0
 
@@ -166,7 +166,17 @@ def read_msgpack(path_or_buf, encoding="utf-8", iterator=False, **kwargs):
 
     Parameters
     ----------
-    path_or_buf : string File path, BytesIO like or string
+    path_or_buf : str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function) or
+        ``StringIO``.
     encoding : Encoding for decoding msgpack str type
     iterator : boolean, if True, return an iterator to the unpacker
                (default is False)

pandas/io/parquet.py

@@ -261,8 +261,18 @@ def read_parquet(path, engine="auto", columns=None, **kwargs):
 
     Parameters
     ----------
-    path : string
-        File path
+    path : str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.parquet``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function)
+        or ``StringIO``.
     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``

pandas/io/parsers.py

@@ -85,13 +85,12 @@
 
 Parameters
 ----------
-filepath_or_buffer : str, path object, or file-like object
+filepath_or_buffer : str, path object or file-like object
     Any valid string path is acceptable. The string could be a URL. Valid
     URL schemes include http, ftp, s3, and file. For file URLs, a host is
     expected. A local file could be: file://localhost/path/to/table.csv.
 
-    If you want to pass in a path object, pandas accepts either
-    ``pathlib.Path`` or ``py._path.local.LocalPath``.
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
 
     By file-like object, we refer to objects with a ``read()`` method, such as
     a file handler (e.g. via builtin ``open`` function) or ``StringIO``.
@@ -728,13 +727,14 @@ def read_fwf(
 
     Parameters
     ----------
-    filepath_or_buffer : str, path object, or file-like object
+    filepath_or_buffer : str, path object or file-like object
         Any valid string path is acceptable. The string could be a URL. Valid
         URL schemes include http, ftp, s3, and file. For file URLs, a host is
-        expected. A local file could be: file://localhost/path/to/table.csv.
+        expected. A local file could be:
+        ``file://localhost/path/to/table.csv``.
 
-        If you want to pass in a path object, pandas accepts either
-        ``pathlib.Path`` or ``py._path.local.LocalPath``.
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
 
         By file-like object, we refer to objects with a ``read()`` method,
         such as a file handler (e.g. via builtin ``open`` function)

pandas/io/pytables.py

@@ -289,11 +289,19 @@ def read_hdf(path_or_buf, key=None, mode="r", **kwargs):
 
     Parameters
     ----------
-    path_or_buf : string, buffer or path object
-        Path to the file to open, or an open :class:`pandas.HDFStore` object.
-        Supports any object implementing the ``__fspath__`` protocol.
-        This includes :class:`pathlib.Path` and py._path.local.LocalPath
-        objects.
+    path_or_buf : str, path object, pandas.HDFStore or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be: ``file://localhost/path/to/table.h5``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        Alternatively, pandas accepts an open :class:`pandas.HDFStore` object.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function)
+        or ``StringIO``.
 
         .. versionadded:: 0.19.0 support for pathlib, py.path.
         .. versionadded:: 0.21.0 support for __fspath__ protocol.

pandas/io/sas/sasreader.py

@@ -17,8 +17,18 @@ def read_sas(
 
     Parameters
     ----------
-    filepath_or_buffer : string or file-like object
-        Path to the SAS file.
+    filepath_or_buffer : str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.sas``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handler (e.g. via builtin ``open`` function)
+        or ``StringIO``.
     format : string {'xport', 'sas7bdat'} or None
         If None, file format is inferred from file extension. If 'xport' or
         'sas7bdat', uses the corresponding format.

pandas/io/stata.py

@@ -94,8 +94,16 @@
 
 Parameters
 ----------
-filepath_or_buffer : string or file-like object
-    Path to .dta file or object implementing a binary read() functions.
+filepath_or_buffer : str, path object or file-like object
+    Any valid string path is acceptable. The string could be a URL. Valid
+    URL schemes include http, ftp, s3, and file. For file URLs, a host is
+    expected. A local file could be: ``file://localhost/path/to/table.dta``.
+
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
+
+    By file-like object, we refer to objects with a ``read()`` method,
+    such as a file handler (e.g. via builtin ``open`` function)
+    or ``StringIO``.
 %s
 %s
 %s