DOC: Improved the docstring of errors.ParserWarning
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################### Docstring (pandas.errors.ParserWarning)  ###################
################################################################################

Warning raised when reading a file that doesn't use the default parser.

Thrown by `pd.read_csv` and `pd.read_table` when it is necessary to
change parsers, generally from 'c' to 'python'.

It happens due to lack of support or functionality for parsing
particular attributes of a CSV file with the requested engine.

Currently, C-unsupported options include the following parameters:

1. `sep` other than a single character (e.g. regex separators)
2. `skipfooter` higher than 0
3. `sep=None` with `delim_whitespace=False`

The warning can be avoided by adding `engine='python'` as a parameter
in `pd.read_csv` and `pd.read_table` methods.

See Also
--------
pd.read_csv : Read CSV (comma-separated) file into DataFrame.
pd.read_table : Read general delimited file into DataFrame.

Examples
--------
Using a `sep` in `pd.read_csv` other than a single character:

>>> import io
>>> csv = u'''a;b;c
...           1;1,8
...           1;2,1'''
>>> df = pd.read_csv(io.StringIO(csv), sep='[;,]')
Traceback (most recent call last):
...
ParserWarning: Falling back to the 'python' engine...

Adding `engine='python'` to `pd.read_csv` removes the Warning:

>>> df = pd.read_csv(io.StringIO(csv), sep='[;,]', engine='python')
scripts/validate_docstrings.py:1: ParserWarning: Falling back to the 'python' engine because the 'c' engine does not support regex separators (separators > 1 char and different from '\s+' are interpreted as regex); you can avoid this warning by specifying engine='python'.
  #!/usr/bin/env python

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        No returns section found
        Examples do not pass tests

################################################################################
################################### Doctests ###################################
################################################################################

**********************************************************************
Line 32, in pandas.errors.ParserWarning
Failed example:
    df = pd.read_csv(io.StringIO(csv), sep='[;,]')
Expected:
    Traceback (most recent call last):
    ...
    ParserWarning: Falling back to the 'python' engine...
Got nothing

```


I am documenting a Warning and I could not find a better way to display the warning in the html example other than using a "Traceback (most recent call last):" followed by "ParserWarning: Falling back to the 'python' engine..." in the docstring.

It also says that it found errors about "No returns sections found". On what I understood this is not relevant to the docstring in hand.



Labels:
name: Docs
name: Error Reporting
description: Incorrect or improved errors from pandas
name: IO CSV
description: read_csv, to_csv

Comments:
Hello @joaoavf! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 15, 2018 at 19:28 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20076?src=pr&el=h1) Report
> Merging [#20076](https://codecov.io/gh/pandas-dev/pandas/pull/20076?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/731d97164ba04150174c4e05f56d40f716044219?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20076      +/-   ##
==========================================
+ Coverage    91.7%    91.7%   +<.01%     
==========================================
  Files         150      150              
  Lines       49122    49152      +30     
==========================================
+ Hits        45045    45074      +29     
- Misses       4077     4078       +1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <ø> (ø)` | :arrow_up: |
| #single | `41.84% <ø> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20076?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/errors/\_\_init\_\_.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2Vycm9ycy9fX2luaXRfXy5weQ==) | `92.3% <ø> (ø)` | :arrow_up: |
| [pandas/core/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYmFzZS5weQ==) | `96.78% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.64% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.85% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.14% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.06% <0%> (ø)` | :arrow_up: |
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.32% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `91.03% <0%> (ø)` | :arrow_up: |
| ... and [3 more](https://codecov.io/gh/pandas-dev/pandas/pull/20076/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20076?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/20076?src=pr&el=footer). Last update [731d971...17687b5](https://codecov.io/gh/pandas-dev/pandas/pull/20076?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

https://github.com/pandas-dev/pandas/issues/20309#issuecomment-373495419 for doctesting warnings. Thanks @joaoavf