DOC: update the pandas.errors.DtypeWarning docstring
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"
- [X] 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.DtypeWarning) ####################
################################################################################

Warning raised when reading different dtypes in a column from a file.

Raised for a dtype incompatibility. This can happen whenever `read_csv`
or `read_table` encounter non-uniform dtypes in a column(s) of a given
CSV file.

See Also
--------
pandas.read_csv : Read CSV (comma-separated) file into a DataFrame.
pandas.read_table : Read general delimited file into a DataFrame.

Notes
-----
This warning is issued when dealing with larger files because the dtype
checking happens per chunk read.

Despite the warning, the CSV file is read with mixed types in a single
column which will be an object type. See the examples below to better
understand this issue.

Examples
--------
This example creates and reads a large CSV file with a column that contains
`int` and `str`.

>>> df = pd.DataFrame({'a':['1']*100000 + ['X']*100000 + ['1']*100000,
...                    'b':['b']*300000})
>>> df.to_csv('test.csv', index=False)
>>> df2 = pd.read_csv('test.csv')
>>> DtypeWarning: Columns (0) have mixed types... # doctest: +SKIP

Important to notice that df2 will contain both `str` and `int` for the
same input, '1'.

>>> df2.iloc[262140, 0]
'1'
>>> type(df2.iloc[262140, 0])
<class 'str'>
>>> df2.iloc[262150, 0]
1
>>> type(df2.iloc[262150, 0])
<class 'int'>

One way to solve this issue is using the parameter `converters` in the
`read_csv` and `read_table` functions to explicit the conversion:

>>> df2 = pd.read_csv('test', sep=' ', converters={'a': str})
scripts/validate_docstrings.py:268: DtypeWarning: Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.
  runner.run(test)

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No returns section found
```


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

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20208?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@0d86742`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #20208   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49156           
  Branches          ?        0           
=========================================
  Hits              ?    45078           
  Misses            ?     4078           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <ø> (?)` | |
| #single | `41.85% <ø> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20208?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/errors/\_\_init\_\_.py](https://codecov.io/gh/pandas-dev/pandas/pull/20208/diff?src=pr&el=tree#diff-cGFuZGFzL2Vycm9ycy9fX2luaXRfXy5weQ==) | `92.3% <ø> (ø)` | |

------

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

Hmm, yes, that's a general problem though, so let's discuss that somewhere else
@TomAugspurger see https://github.com/pandas-dev/pandas/issues/20302
Updated the example, minding taking a look @jorisvandenbossche?

This unfortunately leaks the warning to stdout. `# doctest: +SKIP` doesn't work because we need the example to run, so that `df2` is defined. I'm not sure of a good way, but when running with pytest we can maybe globally capture those? I don't want to pollute the docstring with things like `catch_warnings`.

@hissashirocha we decided in another issue to just `os.remove` the file when done.

I went back and forth on where to put the import :)
@TomAugspurger the only problem now is that the actual warning is separated from the code block, which looks a bit strange in the html output .. 
But if don't leave the blank line, you get a failing doctest ..

The alternative you mentioned would be

```
>>> import warnings
>>> with warnings.catch_warnings(record=True) as w:
...     df2 = pd.read_csv('test.csv')
>>> w[0].message
pandas.errors.DtypeWarning('Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.')
```

But I agree this boilerplate is a bit unfortunate and distracts from what we actually want to show 
Let's go ahead with the current solution for now. We can always later look into adding our own doctest-extensions (it should be possible to add doctest options while running our own doctests: eg https://github.com/astropy/pytest-doctestplus/blob/master/pytest_doctestplus/output_checker.py)
@hissashirocha Thanks for the PR!
Ah was just going to push this

```
diff --git a/pandas/errors/__init__.py b/pandas/errors/__init__.py
index 16654f022..ff34df64c 100644
--- a/pandas/errors/__init__.py
+++ b/pandas/errors/__init__.py
@@ -68,8 +68,7 @@ class DtypeWarning(Warning):
     ...                    'b': ['b'] * 300000})
     >>> df.to_csv('test.csv', index=False)
     >>> df2 = pd.read_csv('test.csv')
-
-        DtypeWarning: Columns (0) have mixed types
+    ... # DtypeWarning: Columns (0) have mixed types
```

Looks OK. I'll make a new PR.
Ah, that's a good one :)
It was a pleasure! This is my first time contributing to pandas and I really enjoyed it. Thanks for your help!