Make Calendar.itermonthdates() behave consistently in edge cases

[abalkin]

BPO	28292
Nosy	@rhettinger, @abalkin, @serhiy-storchaka, @zhangyangyu, @lijp_003@163.com, @aeros
PRs	Closes bpo-28292: Implemented Calendar.itermonthdays3() and itermonthdays4(). #4079 bpo-28292: Mark calendar.py helper functions as private. #15113 [3.8] bpo-28292: Mark calendar.py helper functions as private. (GH-15113) #15116
Dependencies	bpo-26650: calendar: OverflowErrors for year == 1 and firstweekday > 0 bpo-28253: calendar.prcal(9999) output has a problem

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/abalkin'
closed_at = <Date 2019-08-04.20:29:07.374>
created_at = <Date 2016-09-28.03:01:58.463>
labels = ['3.7', 'type-bug', 'library']
title = 'Make Calendar.itermonthdates() behave consistently in edge cases'
updated_at = <Date 2019-08-04.20:34:59.803>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2019-08-04.20:34:59.803>
actor = 'rhettinger'
assignee = 'belopolsky'
closed = True
closed_date = <Date 2019-08-04.20:29:07.374>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2016-09-28.03:01:58.463>
creator = 'belopolsky'
dependencies = ['26650', '28253']
files = []
hgrepos = []
issue_num = 28292
keywords = ['patch']
message_count = 18.0
messages = ['277577', '277584', '277644', '277662', '304735', '304775', '304776', '304777', '304930', '347758', '347771', '347772', '347774', '347810', '347851', '347863', '349000', '349002']
nosy_count = 6.0
nosy_names = ['rhettinger', 'belopolsky', 'serhiy.storchaka', 'xiang.zhang', 'jiangping.li', 'aeros']
pr_nums = ['4079', '15113', '15116']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue28292'
versions = ['Python 3.7']

[abalkin]

The Calendar.itermonthdates() method is defined as follows:

"Return an iterator for one month. The iterator will yield datetime.date values and will always iterate through complete weeks, so it will yield dates outside the specified month."

However, for the two months at the extremes of datetime.date range, 0001-01 and 9999-12, the dates outside the specified month may not be representable as datetime.date instances.

The current implementation is inconsistent: itermonthdates(1, 1) may raise an OverflowError (see bpo-26650), while itermonthdates(9999, 12) may yield an incomplete week (see bpo-28253.)

This issue supersedes bpo-26650 and bpo-28253.

[serhiy-storchaka]

Possible solutions (in any case the documentation needs changes):

1. Raise OverflowError at both ends (revert issue15421patch). The method becomes unusable for two extreme months.

2. Yield an incomplete week at both ends (apply the patch from bpo-26650). This can cause silent producing incorrect result in third-party programs.

3. Yield None for unrepresentable dates. This is more useful than raising OverflowError, and noisily fails, but third-party code should be changed to support extreme cases.

4. Yield dummy date instance for unrepresentable dates (apply the patch from bpo-28253). If we are lucky, the third-party code will just work, without any changes. If we are not lucky, this makes debugging harder.

5. Make datetime.date supporting a date outside current limits. This is a can of worms (numbering years B.D., output and parsing dates with negative and more than 4-digit years).

Examples of the usage of itermonthdates():

https://github.com/sunlightlabs/django-locksmith/blob/master/locksmith/hub/dataviews.py
https://github.com/quandyfactory/Quandy/blob/master/quandy.py
https://github.com/takanory/plone.app.event/blob/master/plone/app/event/portlets/portlet_calendar.py
https://github.com/gerow/gnome-shell-google-calendar/blob/master/gnome-shell-google-calendar.py
https://bitbucket.org/benallard/msgboard/src/1c08fa3ba040f8151d0e28130b01b30e0595e448/msgboard/controller.py?at=default

[abalkin]

I would like to take the #1 approach, and also implement an itermonthdays3() generator that would be like itermonthdates(), but return 3-tuples (year, month, day) instead of datetime.date objects.

The name "itermonthdays3" is subject to discussion, but it fits with the existing "itermonthdays" and "itermonthdays2" that yield integers and 2-tuples respectively. An alternative, but slightly longer name would be "itermonthdatetuples".

itermonthdates() can then be reimplemented as

def itermonthdates(self, year, month):
    for y, m, d in self.itermonthdays3(year, month):
        yield datetime.date(y, m, d)

with the obvious out of bounds behavior.

[serhiy-storchaka]

LGTM. Maybe add also itermonthdays4() that yields 4-tuples (year, month, day, day_of_week)? I seen a code that filters out weekends from itermonthdates().

[serhiy-storchaka]

Do you mind to create a pull request Alexander?

[abalkin]

Let me look into this. It's been a while ...

[abalkin]

1. Raise OverflowError at both ends (revert issue15421patch). The method becomes unusable for two extreme months.

The bpo-15421 patch was committed in 85710a4.

[abalkin]

I submitted PR 4079. Serhiy, please review the logic and if this matches what we discussed a year ago, I will add the docs and NEWS entries.

[abalkin]

New changeset fdd9b21 by Alexander Belopolsky in branch 'master':
Closes bpo-28292: Implemented Calendar.itermonthdays3() and itermonthdays4(). (bpo-4079)
fdd9b21

[rhettinger]

Please mark all the non-public helper functions as being private by using a leading underscore for their names. The __all__ listing is correct but is insufficient. Note, the module already used the leading underscore convention for the some of the non-public helper classes.

Already, we have a user confused by this: https://twitter.com/andreportela85/status/1148956749652738049