fix overflows in Timestamp.tz_localize near boundaries
State: closed

Flesh out docstring for localize_tsobject, add slightly stronger typing.

Closes #12677

Labels:
name: Error Reporting
description: Incorrect or improved errors from pandas
name: Timezones
description: Timezone data dtype

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19626?src=pr&el=h1) Report
> Merging [#19626](https://codecov.io/gh/pandas-dev/pandas/pull/19626?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/6485a36483884fb817800a8380a4a4197d6df4ad?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/19626/graphs/tree.svg?src=pr&token=eZ4WkYLtcO&width=650&height=150)](https://codecov.io/gh/pandas-dev/pandas/pull/19626?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #19626      +/-   ##
==========================================
- Coverage   91.62%   91.61%   -0.01%     
==========================================
  Files         150      150              
  Lines       48798    48807       +9     
==========================================
+ Hits        44709    44716       +7     
- Misses       4089     4091       +2
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.99% <ø> (-0.01%)` | :arrow_down: |
| #single | `41.73% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/19626?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/19626/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.17% <0%> (-0.26%)` | :arrow_down: |
| [pandas/core/dtypes/dtypes.py](https://codecov.io/gh/pandas-dev/pandas/pull/19626/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2R0eXBlcy5weQ==) | `96.08% <0%> (ø)` | :arrow_up: |
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/19626/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.2% <0%> (+0.07%)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/19626/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `83.85% <0%> (+0.2%)` | :arrow_up: |

------

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

lgtm. ping ongreen.
Ping
thanks
some warnings as a result of this change

```
pandas/tests/scalar/timestamp/test_timezones.py::TestTimestampTZOperations::()::test_tz_localize_pushes_out_of_bounds
  /home/travis/build/pandas-dev/pandas/pandas/tests/scalar/timestamp/test_timezones.py:32: RuntimeWarning: overflow encountered in long_scalars
    Timestamp.min.tz_localize('Asia/Tokyo')
  /home/travis/build/pandas-dev/pandas/pandas/tests/scalar/timestamp/test_timezones.py:39: RuntimeWarning: overflow encountered in long_scalars
    Timestamp.max.tz_localize('US/Pacific')
```
when you have a chance can you look at the warnings above: https://github.com/pandas-dev/pandas/pull/19626#issuecomment-364762511