DOC: Examples for DataFrame.from_records

[bdice]

This PR adds examples to the documentation for pandas.DataFrame.from_records. It also rewords a couple sentences to clarify that the input data can be a sequence of dicts or sequence of tuples (but not a sequence of DataFrames).

• closes DOC: Missing examples of from_records. #34057
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[bdice]

Validated docstring, pasting here as requested by the contributing guide.

$ python scripts/validate_docstrings.py pandas.DataFrame.from_records

################################################################################
################## Docstring (pandas.DataFrame.from_records)  ##################
################################################################################

Convert structured or record ndarray to DataFrame.

Creates a DataFrame object from a structured ndarray, sequence of
tuples, sequence of dicts, or DataFrame.

Parameters
----------
data : ndarray (structured dtype), sequence of tuples, sequence of dicts, or DataFrame
    Structured input data.
index : str, list of fields, array-like
    Field of array to use as the index, alternately a specific set of
    input labels to use.
exclude : sequence, default None
    Columns or fields to exclude.
columns : sequence, default None
    Column names to use. If the passed data do not have names
    associated with them, this argument provides names for the
    columns. Otherwise this argument indicates the order of the columns
    in the result (any names not found in the data will become all-NA
    columns).
coerce_float : bool, default False
    Attempt to convert values of non-string, non-numeric objects (like
    decimal.Decimal) to floating point, useful for SQL result sets.
nrows : int, default None
    Number of rows to read if data is an iterator.

Returns
-------
DataFrame

See Also
--------
DataFrame.from_dict : DataFrame from dict of array-like or dicts.
DataFrame : DataFrame object creation using constructor.

Examples
--------
Data can be provided as a structured ndarray:

>>> data = np.array([(3, 'a'), (2, 'b'), (1, 'c'), (0, 'd')],
...                 dtype=[('col_1', 'i4'), ('col_2', 'U1')])
>>> pd.DataFrame.from_records(data)
   col_1 col_2
0      3     a
1      2     b
2      1     c
3      0     d

Data can be provided as a list of dicts:

>>> data = [{'col_1': 3, 'col_2': 'a'},
...         {'col_1': 2, 'col_2': 'b'},
...         {'col_1': 1, 'col_2': 'c'},
...         {'col_1': 0, 'col_2': 'd'}]
>>> pd.DataFrame.from_records(data)
   col_1 col_2
0      3     a
1      2     b
2      1     c
3      0     d

Data can be provided as a list of tuples with corresponding columns:

>>> data = [(3, 'a'), (2, 'b'), (1, 'c'), (0, 'd')]
>>> pd.DataFrame.from_records(data, columns=['col_1', 'col_2'])
   col_1 col_2
0      3     a
1      2     b
2      1     c
3      0     d

################################################################################
################################## Validation ##################################
################################################################################

[MarcoGorelli]

Thanks @bdice

Just suggesting a change on the param description

[bdice]

@MarcoGorelli Thanks for the feedback -- I considered that and wasn't sure if it would be clear, but I agree with your suggestion and have applied that change. That reduces the line length enough that the # noqa: E501 should no longer be necessary (85 char < 88 char).

[pep8speaks]

Hello @bdice! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

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

Comment last updated at 2020-05-08 13:04:29 UTC

[jorisvandenbossche]

Looks good to me!

[simonjayhawkins]

test failures unrelated.

[simonjayhawkins]

Thanks @bdice