Fix truncated timepoint addition bug

[MetRonnie]

Closes #80
Closes #212

Built on #203

• Tests included
• Changelog entry included

[MetRonnie]

Note this does not fix cylc/cylc-flow#2382, presumably that is still a bug in cylc-flow

[MetRonnie]

Actually which should the behaviour be?

2019-01-15 + --01-15 = ?

1. 2019-01-15 - same point (current behaviour)
2. 2020-01-15 - next matching point (what I think it should be)

[MetRonnie]

Actually which should the behaviour be?

2019-01-15 + --01-15 = ?

1. 2019-01-15 - same point (current behaviour)
2. 2020-01-15 - next matching point (what I think it should be)

I think we have to maintain the current behaviour to avoid breaking next() in Cylc workflows - see cylc/cylc-flow#5777

(Technically we could change the behaviour here and add a workaround in Cylc, but that's more effort)

[MetRonnie]

Decision on 2019-01-15 + --01-15 (with greater clarity and precision):

The behaviour is to be:

2019-01-15T00:00:00 + --01-15
>>> 2019-01-15T00:00:00  # same datetime (we are exactly at midnight)

2019-01-15T00:00:01 + --01-15
>>> 2020-01-15T00:00:00  # next year 

This is because a truncated datetime should assume 0 for any unspecified time units, and 1 for any unspecified date units lower than what has been specified.

[wxtim]

Seems reasonable, code looks good and looks like it fixes the bug. Is it worth filling the gaps in the coverage whilst you're at it. I think it is.

[wxtim]

Sorry I failed to approve sooner. Please get a second reviewer or merge as you think appropriate.

[MetRonnie]

No worries, this has not been a top priority at the moment

[MetRonnie]

@oliver-sanders Poke (I just spent half a day investigating a bug with Cylc initial cycle point = next(---01) with a non-UTC timezone only to find it is fixed by this PR)

[oliver-sanders]

Sorry, this hasn't made the priority list.

[oliver-sanders]

I think I'm happy with the new method, makes sense, very thorough.

There's a disparity in how input types are handled in a lot of these methods when if not isinstance(self, X): raise NotImplementedError is used. Some specify the one valid type, others pick the looser object (the latter is technically correct and more compatible with inheritance, although we probably wouldn't have written it that way if starting anew).

[oliver-sanders]

Potentially breaking change.

[MetRonnie]

Which is why it is listed as such in the changelog

[oliver-sanders]

Testing this out with cylc-flow.

Have found one Cylc unit test that fails with this branch:

FAILED tests/unit/cycling/test_iso8601.py::test_user_guide_examples[next(-W-1; -W-3; -W-5)-20180314T0000Z] - AssertionError: assert '20180316T0000Z' == '20180314T0000Z'

Should check whether this change is correct.

Otherwise, all good.

[MetRonnie]

See cylc/cylc-flow#5928

[oliver-sanders]

Plz squash merge.

[MetRonnie]

(Latest force push only affects changelog as per review request)

(Edit: argh, accidentally pressed normal merge instead of squash, oh well)