DOC: Clarify documentation of 'ambiguous' parameter
State: closed

when first reading the docs, the `ambiguous` parameter was not clear to me. I propose to add a line of documentation and include an example that exactly indicates the issue that the `ambiguous` parameter solves.


Labels:
name: Docs
name: Datetime
description: Datetime data dtype

Comments:
Hello @bartaelterman! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/arrays/datetimes.py`](https://github.com/bartaelterman/pandas/blob/b1026c389b32e95d9e439b3b2fa0e16252908588/pandas/core/arrays/datetimes.py) !

 - There are no PEP8 issues in the file [`pandas/core/generic.py`](https://github.com/bartaelterman/pandas/blob/b1026c389b32e95d9e439b3b2fa0e16252908588/pandas/core/generic.py) !

 - There are no PEP8 issues in the file [`pandas/core/indexes/datetimes.py`](https://github.com/bartaelterman/pandas/blob/b1026c389b32e95d9e439b3b2fa0e16252908588/pandas/core/indexes/datetimes.py) !



##### Comment last updated on October 31, 2018 at 23:04 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23408?src=pr&el=h1) Report
> Merging [#23408](https://codecov.io/gh/pandas-dev/pandas/pull/23408?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/184bcd3386a835d058a802d18a8b6d201df4a584?src=pr&el=desc) will **increase** coverage by `0.03%`.
> The diff coverage is `96.29%`.

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

```diff
@@            Coverage Diff             @@
##           master   #23408      +/-   ##
==========================================
+ Coverage   92.18%   92.21%   +0.03%     
==========================================
  Files         161      161              
  Lines       51160    51173      +13     
==========================================
+ Hits        47161    47190      +29     
+ Misses       3999     3983      -16
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.65% <96.29%> (+0.03%)` | :arrow_up: |
| #single | `42.23% <22.22%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/23408?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `96.43% <ø> (ø)` | :arrow_up: |
| [pandas/core/arrays/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lcy5weQ==) | `97.9% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.81% <96.29%> (+0.02%)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.87% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/dtypes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2Jhc2UucHk=) | `100% <0%> (ø)` | :arrow_up: |
| [pandas/util/\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX2RlY29yYXRvcnMucHk=) | `91.34% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.46% <0%> (ø)` | :arrow_up: |
| [pandas/core/groupby/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9vcHMucHk=) | `96.79% <0%> (ø)` | :arrow_up: |
| [pandas/core/groupby/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9iYXNlLnB5) | `91.83% <0%> (ø)` | :arrow_up: |
| ... and [33 more](https://codecov.io/gh/pandas-dev/pandas/pull/23408/diff?src=pr&el=tree-more) | |

------

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

Could you copy this explanation to the other occurrences of this argument? It needs to be added to `Timestamp`, `DatetimeIndex` and `NaT`
@bartaelterman Thanks for the PR! 

In addition, what would also be very useful is an actual code example in an `Examples` section (feel free to add one in this PR, but also don't feel obliged, the PR is already an improvement)
Thanks for your feedback! I will wait for your reply on my comment above after which I will copy over the explanation to the other places. I'll look into the `Examples` section too.
@mroeschke I've updated the doc as discussed and added it to `Timestamp`, `DatetimeIndex` and `NaT`.
@jorisvandenbossche I've added a couple of examples. However I'm not comfortable with the Cython stuff...
If you have more remarks, I am happy to modify it further.
So the docstring test for NaT have failed but I'm not sure what's wrong: 

```
=================================== FAILURES ===================================
_____________________________ test_NaT_docstrings ______________________________

    def test_NaT_docstrings():
        # GH#17327
        nat_names = dir(NaT)
    
        # NaT should have *most* of the Timestamp methods, with matching
        # docstrings.  The attributes that are not expected to be present in NaT
        # are private methods plus `ts_expected` below.
        ts_names = dir(Timestamp)
        ts_missing = [x for x in ts_names if x not in nat_names and
                      not x.startswith('_')]
        ts_missing.sort()
        ts_expected = ['freqstr', 'normalize',
                       'to_julian_date',
                       'to_period', 'tz']
        assert ts_missing == ts_expected
    
        ts_overlap = [x for x in nat_names if x in ts_names and
                      not x.startswith('_') and
                      callable(getattr(Timestamp, x))]
        for name in ts_overlap:
            tsdoc = getattr(Timestamp, name).__doc__
            natdoc = getattr(NaT, name).__doc__
>           assert tsdoc == natdoc
E           AssertionError: assert '\n        Co...ne.\n        ' == '\n        Con...ne.\n        '
E             Skipping 383 identical leading characters in diff, use -v to show
E             -           When clocks moved backward due to DST, ambiguous times may arise.
E             -             For example in Central European Time (UTC+01), when going from 03:00 DST
E             -             to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC
E             -             and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter
E             -             dictates how ambiguous times should be handled.
E             - 
E             -             - bool contains flags to determine if time is dst or not (note
E             ? --
E             +           - bool contains flags to determine if time is dst or not (note
E                             that this flag is only applicable for ambiguous fall dst dates)
E                           - 'NaT' will return NaT for an ambiguous time
E                           - 'raise' will raise an AmbiguousTimeError for an ambiguous time
E               
E                       nonexistent : 'shift', 'NaT', default 'raise'
E                           A nonexistent time does not exist in a particular timezone
E                           where clocks moved forward due to DST.
E               
E                           - 'shift' will shift the nonexistent time forward to the closest
E                             existing time
E                           - 'NaT' will return NaT where there are nonexistent times
E                           - 'raise' will raise an NonExistentTimeError if there are
E                             nonexistent times
E               
E                           .. versionadded:: 0.24.0
E               
E                       errors : 'raise', 'coerce', default None
E                           - 'raise' will raise a NonExistentTimeError if a timestamp is not
E                              valid in the specified timezone (e.g. due to a transition from
E                              or to DST time). Use ``nonexistent='raise'`` instead.
E                           - 'coerce' will return NaT if the timestamp can not be converted
E                             into the specified timezone. Use ``nonexistent='NaT'`` instead.
E               
E                             .. deprecated:: 0.24.0
E               
E                       Returns
E                       -------
E                       localized : Timestamp
E               
E                       Raises
E                       ------
E                       TypeError
E                           If the Timestamp is tz-aware and tz is not None.

pandas/tests/scalar/test_nat.py:185: AssertionError
```
@bartaelterman in essence, the docstrings for `NaT` need to be the same as the docstrings for `Timestamp`, so you need to add your explanation of ambiguous in `nattype.pyx` for the `tz_localize` defined there.
Should I add the docstring also to `core/arrays/datetimes.py`? And in that case, shall I add the example with `dt.tz_localize()` there? It seems to me that would end up [here](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.dt.tz_localize.html#pandas.Series.dt.tz_localize) which seems appropriate.
Yes that'd be great @bartaelterman.

The examples look good.  Just looks like there's a doctest failure and pep8 issues.
The Travis build is still failing, but I'm not sure why. All tests seem to pass and I don't see an error message, except at the very end:
`The command "ci/code_checks.sh" exited with 2.`
Any ideas what's going wrong? Thanks
see https://travis-ci.org/pandas-dev/pandas/jobs/448947238#L2763

Some lines are too long.
Agreed. This is a useful change as is.