DOC: update file path descriptions in IO docstrings
State: closed

- [x] closes #24321
- [ ] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Validate Docstrings script output:

```
 ✔  python scripts/validate_docstrings.py pandas.io.parquet.read_parquet                                                                                                                                                       (pandas-dev)

################################################################################
################## Docstring (pandas.io.parquet.read_parquet) ##################
################################################################################

Load a parquet object from the file path, returning a DataFrame.

.. versionadded 0.21.0

Parameters
----------
path : various
    Either a path to a file (a :class:`python:str`,
    :class:`python:pathlib.Path`,
    or :class:`py:py._path.local.LocalPath`),
    URL (including http, ftp, and S3 locations), or any object
    with a ``read()`` method (such as an open file or
    :class:`~python:io.BytesIO`).
columns : list, default=None
    If not None, only these columns will be read from the file.

    .. versionadded 0.21.1
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.
kwargs are passed to the engine

Returns
-------
DataFrame

################################################################################
################################## Validation ##################################
################################################################################

5 Errors found:
	Parameters {**kwargs} not documented
	Unknown parameters {kwargs are passed to the engine}
	Parameter "kwargs are passed to the engine" has no type
	Parameter "kwargs are passed to the engine" has no description
	Return value has no description
2 Warnings found:
	See Also section not found
	No examples section found
```

Labels:
name: Docs
name: IO Parquet
description: parquet, feather

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=h1) Report
> Merging [#25164](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/e3b095074c5c3b29ec25a994cd204349b872d961?src=pr&el=desc) will **decrease** coverage by `1.57%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/25164/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #25164      +/-   ##
==========================================
- Coverage   92.37%   90.79%   -1.58%     
==========================================
  Files         166      166              
  Lines       52408    52408              
==========================================
- Hits        48412    47584     -828     
- Misses       3996     4824     +828
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.79% <ø> (ø)` | :arrow_up: |
| #single | `?` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/parquet.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnF1ZXQucHk=) | `84.61% <ø> (ø)` | :arrow_up: |
| [pandas/io/feather\_format.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2ZlYXRoZXJfZm9ybWF0LnB5) | `23.07% <0%> (-66.67%)` | :arrow_down: |
| [pandas/core/computation/pytables.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tcHV0YXRpb24vcHl0YWJsZXMucHk=) | `62.38% <0%> (-29.97%)` | :arrow_down: |
| [pandas/io/pytables.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3B5dGFibGVzLnB5) | `63.89% <0%> (-28.43%)` | :arrow_down: |
| [pandas/core/computation/common.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tcHV0YXRpb24vY29tbW9uLnB5) | `78.57% <0%> (-7.15%)` | :arrow_down: |
| [pandas/core/computation/expr.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tcHV0YXRpb24vZXhwci5weQ==) | `84.31% <0%> (-4.38%)` | :arrow_down: |
| [pandas/io/clipboard/clipboards.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2NsaXBib2FyZC9jbGlwYm9hcmRzLnB5) | `28.23% <0%> (-2.36%)` | :arrow_down: |
| [pandas/io/formats/printing.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvcHJpbnRpbmcucHk=) | `84.37% <0%> (-1.05%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `96.11% <0%> (-0.17%)` | :arrow_down: |
| [pandas/core/arrays/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2NhdGVnb3JpY2FsLnB5) | `95.85% <0%> (-0.13%)` | :arrow_down: |
| ... and [2 more](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=footer). Last update [e3b0950...7676c68](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=h1) Report
> Merging [#25164](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/355e322b5ed4a31c9e1cab9652510e85a54f23a3?src=pr&el=desc) will **increase** coverage by `49.87%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/25164/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=tree)

```diff
@@             Coverage Diff             @@
##           master   #25164       +/-   ##
===========================================
+ Coverage      42%   91.87%   +49.87%     
===========================================
  Files         180      174        -6     
  Lines       50857    50692      -165     
===========================================
+ Hits        21360    46572    +25212     
+ Misses      29497     4120    -25377
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.41% <ø> (?)` | |
| #single | `41.77% <ø> (-0.23%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/feather\_format.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2ZlYXRoZXJfZm9ybWF0LnB5) | `89.47% <ø> (+64.47%)` | :arrow_up: |
| [pandas/io/packers.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhY2tlcnMucHk=) | `88.08% <ø> (+75.65%)` | :arrow_up: |
| [pandas/io/sas/sasreader.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNyZWFkZXIucHk=) | `96% <ø> (+88%)` | :arrow_up: |
| [pandas/io/parquet.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnF1ZXQucHk=) | `84.46% <ø> (+62.96%)` | :arrow_up: |
| [pandas/io/json/json.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2pzb24vanNvbi5weQ==) | `93.24% <ø> (+30.15%)` | :arrow_up: |
| [pandas/io/excel/\_base.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2V4Y2VsL19iYXNlLnB5) | `91.81% <ø> (+63.69%)` | :arrow_up: |
| [pandas/io/pytables.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3B5dGFibGVzLnB5) | `90.29% <ø> (+0.92%)` | :arrow_up: |
| [pandas/io/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2h0bWwucHk=) | `92.66% <ø> (+72.36%)` | :arrow_up: |
| [pandas/plotting/\_misc.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19taXNjLnB5) | `38.23% <0%> (-5.01%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `78.94% <0%> (-4.39%)` | :arrow_down: |
| ... and [159 more](https://codecov.io/gh/pandas-dev/pandas/pull/25164/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=footer). Last update [355e322...e4b11c1](https://codecov.io/gh/pandas-dev/pandas/pull/25164?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@enricorotundo can you merge master and address comments here?
* merged master
* addressed comments
* passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

Validate Docstrings script output:
```
 ✔  python scripts/validate_docstrings.py pandas.io.parquet.read_parquet                                                                                                                                                       (pandas-dev)

################################################################################
################## Docstring (pandas.io.parquet.read_parquet) ##################
################################################################################

Load a parquet object from the file path, returning a DataFrame.

.. versionadded 0.21.0

Parameters
----------
path : various
    Either a path to a file (a :class:`str`,
    :class:`pathlib.Path`,
    or :class:`py:py._path.local.LocalPath`),
    URL (including http, ftp, and S3 locations), or any file-like object.
columns : list, default=None
    If not None, only these columns will be read from the file.

    .. versionadded 0.21.1
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.
columns : list, default=None
    If not None, only these columns will be read from the file.

    .. versionadded 0.21.1
**kwargs
    Any additional kwargs are passed to the engine.

Returns
-------
DataFrame

################################################################################
################################## Validation ##################################
################################################################################

2 Errors found:
	Wrong parameters order. Actual: ('path', 'engine', 'columns', '**kwargs'). Documented: ('path', 'columns', 'engine', '**kwargs')
	Return value has no description
2 Warnings found:
	See Also section not found
	No examples section found
```
yes that’s what i am suggesting - we weant them all to conform to similar to what u have done here
@jreback please check the latests commits. I assume reading from a URL works in every read_* method in this PR. Is that a valid assumption?
> @jreback please check the latests commits. I assume reading from a URL works in every read_* method in this PR. Is that a valid assumption?

yes we use a common reading routine.

cc @jorisvandenbossche 
Anything I can do for this PR at the moment?
can you merge master
> This might be for another PR, but, reading the diff here, I think it would be good to explain somewhere (eg in the io.rst user guide) in more detail what those options are.

Agreed @jorisvandenbossche , will be happy to issue another PR on that.

> Another general remark: you now listed "URL" explicitly in the types list, but should this URL not be a string or path object?

You're right, indeed in this PR I tried to replace generic names with python types (`string, buffer` -> `str, file-like object`) it'd make sense to stick with types. However, my understanding is that if [io.common. get_filepath_or_buffer](https://github.com/pandas-dev/pandas/blob/5c341dc136cae12bf23c1a4b8e34c9951828c0cf/pandas/io/common.py#L179) can parse it, then it's a valid string, so not all strings al valid; how to make that clear?
Not sure if pipelines fail due to my changes, seem most errors relate to `Series`...
Can you merge master? Fixed issues with docstring validation on master within the past few hours
can you merge master and update as above
Removing from 0.25 as not a blocker, but @enricorotundo if you can merge master and address comments would still take this PR!
@enricorotundo already merged master since the last time it was asked, so I think we should first see if we are actually OK with the current diff, or if there are outstanding change requests.

Hello @enricorotundo! Thanks for updating this PR. We checked the lines you've touched for [PEP 8](https://www.python.org/dev/peps/pep-0008) issues, and found:





















There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: 

##### Comment last updated at 2019-07-11 20:37:31 UTC
@jorisvandenbossche I merged `upstream/master` but it seems to have an issue with code formatting.

<img width="1792" alt="Screen Shot 2019-07-08 at 21 11 55" src="https://user-images.githubusercontent.com/4340327/60836226-78deb000-a1c5-11e9-8b38-fd9e0e249ded.png">

@enricorotundo the CI is green, not sure why the long line is not reported, but you can open a new issue for that, this seems unrelated to the changes here.

@jreback you requested changes, if you can take a look.
> lgtm. would just change to use pathlib.Path (and say pathlike) as that's the de-facto path object now

Replaced in ad29cff4ea4ddae0e99803498033d03d179429f2
@jreback can you take a look?


Thanks @enricorotundo. Nice PR!