DOC: Exception raised if columns do not match data GH27003
State: closed

- [X] closes #27003
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs
name: Error Reporting
description: Incorrect or improved errors from pandas
name: DataFrame
description: DataFrame data structure

Comments:
Hello @srf94! 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-06-26 19:58:19 UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/27067?src=pr&el=h1) Report
> Merging [#27067](https://codecov.io/gh/pandas-dev/pandas/pull/27067?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d94146cf5d5d9f899a31308d0a4d9e5d132f6442?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #27067      +/-   ##
==========================================
- Coverage   92.04%   92.03%   -0.01%     
==========================================
  Files         180      180              
  Lines       50714    50714              
==========================================
- Hits        46680    46676       -4     
- Misses       4034     4038       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.67% <ø> (ø)` | :arrow_up: |
| #single | `41.88% <ø> (-0.09%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/27067?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/27067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.89% <ø> (-0.12%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/27067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `88.88% <0%> (-11.12%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/27067?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/27067?src=pr&el=footer). Last update [d94146c...d3218c7](https://codecov.io/gh/pandas-dev/pandas/pull/27067?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/27067?src=pr&el=h1) Report
> Merging [#27067](https://codecov.io/gh/pandas-dev/pandas/pull/27067?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d94146cf5d5d9f899a31308d0a4d9e5d132f6442?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #27067      +/-   ##
==========================================
- Coverage   92.04%   92.03%   -0.01%     
==========================================
  Files         180      180              
  Lines       50714    50714              
==========================================
- Hits        46680    46676       -4     
- Misses       4034     4038       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.67% <ø> (ø)` | :arrow_up: |
| #single | `41.88% <ø> (-0.09%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/27067?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/27067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.89% <ø> (-0.12%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/27067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `88.88% <0%> (-11.12%)` | :arrow_down: |

------

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

I think that we indeed first need to pin down the behaviour in code and tests. As it does not seem to always give an error message. For example:

```
In [24]: data = {1: ["foo"], 2: ["bar"]} 

In [25]: pd.DataFrame.from_records(data, columns=['a', 'b']) 
Out[25]: 
Empty DataFrame
Columns: [a, b]
Index: []
```


This is an example from the tests: https://github.com/pandas-dev/pandas/blob/de0867f8bedab9ce7d8d4f46267c4c123ff3166c/pandas/tests/frame/test_constructors.py#L2049-L2053


Also, the sentence you are changing is about the case that your data already have names. While the use case in the reported issue is when the data have no names.
This looks stale so closing for now but ping if you'd like to pick back up