DOC: Document existing functionality of pandas.DataFrame.to_sql() #11886
- [x] Adds documentation for #11886 
- [ ] doc build fails (may be related to #26723)
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] **What's new?** Adds documentation to an existing functionality. In fact, the functionality is documented at `pandas.io.sql.to_sql` but it's not visible [here](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_sql.html).

The documentation related notes on "Contribute to Pandas" are not in a very helpful state. I haven't yet managed to build and check if this appears at `pandas.DataFrame.to_sql()`. I suppose it would, so I went on with the PR.

Next one in line is documentation contribution notes :) # [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26795?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@bc65fe6`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff            @@
##             master   #26795   +/-   ##
=========================================
  Coverage          ?   91.87%           
=========================================
  Files             ?      179           
  Lines             ?    50698           
  Branches          ?        0           
=========================================
  Hits              ?    46578           
  Misses            ?     4120           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.46% <100%> (?)` | |
| #single | `41.1% <100%> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26795?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/26795/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `94.2% <100%> (ø)` | |

------

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

Cool thanks. If it ends up being a lot of trouble we could go forward with just this for now and address annotations in separate PRs. lmk Hello @oguzhanogreden! 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-08-29 10:01:59 UTC Oops... circular import. I don't feel comfortable with the code base enough to work around this. I'll replace the annotation for `pd_table` with `Any` unless you have a suggestion.
 OK sure. Any is not very useful as an annotation but can come back to that piece later; I think the rest of this is great Just put a comment like `TODO: replace Any with SQLTable if circular import resolved` Sure, thanks for the way out here and patient help! 

For completeness...

```
method: Union[str, Callable[[Any, Any, ...
```

can be replaced with

```
method: Union[str, Callable[[pandas.io.sql.SQLTable, Union[sqlalchemy.engine.Connection, sqlalchemy.engine.Engine], ...
```

This can be done when:
- SQLTable can be imported without causing circular import,
- sqlalchemy types are available for type annotations. I expected that VSCode would let me know of updates in master. The last conflict was due to that and I missed it before hitting resolve! Makes sense as sqlite3 is part of the stdlib whereas sqlalchemy is a third party package and I don’t think on typeshed. 

Sent from my iPhone

> On Jun 17, 2019, at 11:56 AM, Oğuzhan Öğreden <notifications@github.com> wrote:
> 
> @oguzhanogreden commented on this pull request.
> 
> In pandas/core/generic.py:
> 
> > @@ -2458,8 +2462,22 @@ def to_msgpack(self, path_or_buf=None, encoding='utf-8', **kwargs):
>          return packers.to_msgpack(path_or_buf, self, encoding=encoding,
>                                    **kwargs)
>  
> -    def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
> -               index_label=None, chunksize=None, dtype=None, method=None):
> +    # TODO: Replace `con: Any` and `Callable[[Any, Any, ...` when SQLTable
> +    # and sqlalchemy can be imported. SQLTable can't be imported due to
> I got the correct type for sqlite3 when I tried reveal_type(). @WillAyd did you notice the if TYPE_CHECKING: imports? It seems I'm making a mistake with sqlalchemy though, since it's revealed as Any as you mentioned.
> 
> pandas\core\generic.py:2619: error: Revealed type is 'Union[Any, sqlite3.dbapi2.Connection]'
> pandas\core\generic.py:2620: error: Revealed type is 'Union[builtins.str, def (pandas.io.sql.SQLTable, Union[Any, sqlite3.dbapi2.Connection], builtins.list[builtins.str], typing.Iterator[builtins.list[Any]]), None]'
> I'll figure sqlalchemy types out and make sure this passes the tests out.
> 
> Also, here is the cross-module example: https://mypy.readthedocs.io/en/latest/common_issues.html#import-cycles
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub, or mute the thread.
 Of course, should've thought! :) This has been very educative for me, thanks.

Once you folks decide how to treat these annotations, I'll move on as you suggest. I want to move this forward. 

We have two issues:

1. `SQLTable` can't be imported due to circular import,
2. `sqlalchemy.engine.Engine` can't be imported due to it being an optional dependency.

Quick recap of what happened so far: Initially we added `Any` for these and left comments. Then I was pointed to quoting these with backticks, which led me down to `TYPE_CHECKING` conditional. It turned out that's something you don't want. 

I will go back to "`Any` and comments" solution for `SQLTable` and `sqlalchemy.engine.Engine`. I think this is also what's implied by @WillAyd's last request changes. Is this acceptable by the group at this stage? If there is not a consensus, I'd like to remove type annotations from this PR and focus on the initial goal.

Let me know! I would say go ahead and remove the complicated annotations that are tripping this up and we can get this in This should be ready. Thanks! Congrats on your first PR to pandas! Yea nice job @oguzhanogreden thanks for sticking through the back and forth.  Great, thanks for your support and patience as well!