Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#26217 closed Bug (fixed)

Docs for WeekArchiveView are misleading about %W

Reported by: Michal Petrucha Owned by: Michal Petrucha
Component: Documentation Version: 1.9
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The docs state:

The '%W' format uses the ISO week format and its week begins on a Monday. The '%W' format is the same in both the strftime() and the date.

However, as established in #7380, this is not true (another example is the week starting on 2015-11-16, which is week 47 according to date, but 46 according to strftime()). This section of the docs should be rephrased into a warning that '%W' and 'W' are not compatible with each other.

Change History (12)

comment:1 Changed 4 years ago by Tim Graham

Triage Stage: UnreviewedAccepted
Type: UncategorizedBug

Would be great if you could submit a patch since you apparently understand the issue.

comment:2 Changed 4 years ago by Michal Petrucha

Owner: changed from nobody to Michal Petrucha
Status: newassigned

I'll try to submit a PR later this week, unless somebody beats me to it.

comment:3 Changed 4 years ago by Michal Petrucha

comment:4 Changed 4 years ago by Tim Graham

Has patch: set

comment:5 Changed 4 years ago by Tim Graham

Patch needs improvement: set

Left some comments for improvement, please uncheck "Patch needs improvement" when updating.

comment:6 Changed 4 years ago by Michal Petrucha

Thanks for the feedback; I'm trying to incorporate it into the patch.

One interesting thing I found is that the GNU libc supports an additional format string, '%V', which uses the same ISO 8601 numbering as the 'W' format character of the date template filter. (http://linux.die.net/man/3/strftime) However, it is not documented in the Python docs for strftime, since the Python docs are limited to the C89 standard. On the other hand, '%V' was introduced in C99, which hopefully means that any reasonably recent system supports this format string.

Anyway, I think it might be worth adding support for '%V' in WeekArchiveView. That way we get a combination of out-of-the-box date formatters and parsers that work in templates and Python code alike. A potential pitfall is that requires a different year in certain corner cases with first and last weeks in a given year, which is '%G' for strftime and 'o' for date. This means a bit of special-casing would be required in WeekArchiveView, and clear docs pointing out the difference, but I still think it's worth it.

Is it okay to implement this in the current PR, or should I open a new one?

comment:7 Changed 4 years ago by Michal Petrucha

Patch needs improvement: unset

comment:8 Changed 4 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 468c6a3b:

[1.9.x] Fixed #26217 -- Added a warning about format strings to WeekArchiveView docs.

Backport of fe8ea3ba3ba709b3d6c39da046f0883a296e6441 from master

comment:9 Changed 4 years ago by Tim Graham <timograham@…>

In fe8ea3ba:

Fixed #26217 -- Added a warning about format strings to WeekArchiveView docs.

comment:10 Changed 4 years ago by Michal Petrucha

For the sake of completeness, in case someone stumbles upon this ticket, using '%V' as the format string to parse the week number is a dead end, because while strftime is a function specified in the C standard, strptime is not, which means CPython needs to include its own implementation of strptime, and that only implements the set of strftime format strings mandated by C89.

comment:11 Changed 4 years ago by Tim Graham <timograham@…>

In 2109975:

Refs #26217 -- Fixed typo in docs/ref/class-based-views/generic-date-based.txt.

comment:12 Changed 4 years ago by Tim Graham <timograham@…>

In d38da1cc:

[1.9.x] Refs #26217 -- Fixed typo in docs/ref/class-based-views/generic-date-based.txt.

Backport of 2109975e901440da70e29d0f330a600bc2d37e9a from master

Note: See TracTickets for help on using tickets.
Back to Top