[Django] #28403: FORMAT_MODULE_PATH documentation lacking
Django
------------------------------------------------+------------------------
Reporter: karyon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.11
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
two issues with the
[https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-
FORMAT_MODULE_PATH documentation for FORMAT_MODULE_PATH]:
first, it suggests to create this directory structure:
{{{
mysite/
formats/
__init__.py
en/
__init__.py
formats.py
}}}
since i didn't like adding a new {{{formats}}} folder for that, i first
did not use {{{FORMAT_MODULE_PATH}}}. then i realized i could use the
locale path for that, and then i saw that even django itself does that.
so, my first suggestion is to replace {{{formats/}}} by {{{locale/}}} in
that directory structure, and maybe even explicitly add a sentence how the
locale directory can be used for the formats.
second, the docs say something about "available formats are:" and then a
long list of settings. to me it seems like {{{DATE_INPUT_FORMATS}}} and
{{{DATETIME_INPUT_FORMATS}}} are missing from this list. if they were
excluded for a specific reason, that should be stated there as well.
--
Ticket URL: <https://code.djangoproject.com/ticket/28403>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
--------------------------------------+------------------------------------
Reporter: karyon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.11
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham):
* stage: Unreviewed => Accepted
Comment:
Is there a need to use `FORMAT_MODULE_PATH` if you use the `locale`
structure? Are you adding other files in there besides formats? I don't
know enough one way or another to say that the original decision to use a
directory called `formats` isn't better. Perhaps you can propose a patch
to clarify exactly what you did differently.
The second point about the missing formats seems valid. For future
reference, I'd have created two tickets rather than grouping somewhat
related issues together.
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:1>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.11
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by karyon):
to be specific, with "locale path" i meant the
[https://docs.djangoproject.com/en/dev/ref/settings/#locale-paths
LOCALE_PATHS setting] as far as i understand, the [
https://github.com/django/django/blob/550cb3a365dee4edfdd1563224d5304de2a57fda/django/utils/formats.py#L62
code for determining the format locale locations] does not look into
LOCALE_PATHS. so yes, as far as i understand one has to specify
FORMAT_MODULE_PATH besides LOCALE_PATHS.
i'm using LOCALE_PATHS for translations. initially i though that any
project using FORMAT_MODULE_PATH also has translations and therefore uses
LOCALE_PATHS anyways, but from a quick github search that doesn't seem to
be the case. so now i wouldn't replace {{{formats}}} by {{{locale}}}, but
rather simply mention that the locale structure can be used.
actually from my point of view it would make sense to merge these
settings. you specify where the locales are, and in there there might be
translations and/or formats. or, one could at least make
FORMAT_MODULE_PATH look into LOCALE_PATHS by default. however, the former
is a python path while the latter is a normal path with slashes. but
maybe, since this has been like that for 8 years according to git blame,
maybe this doesn't need fixing :)
https://github.com/django/django/blob/550cb3a365dee4edfdd1563224d5304de2a57fda/django/utils/formats.py#L62
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:2>
Django
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.11
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Ashaba John):
* status: new => assigned
* owner: nobody => Ashaba John
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by karyon):
ashaba do you still plan to work on this?
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham):
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/9399 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Carlton Gibson):
Patch seems good for adding the missing settings. We should probably take
that.
I'm not sure about the comment about re-using locale paths... (There is
obviously some overlap between the two settings, but a clean up is a
separate issue, maybe worth the effort or not.)
@karyon: what's your thought on this now?
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by karyon):
+1 on merging the PR.
the way i see it the possible solutions for the other part are:
1. merge the two settings. might not be worth it, and maybe there's some
reason we didn't see yet to not merge them.
2. make FORMAT_MODULE_PATH look into LOCALE_PATHS by default. Not sure
whether that is nice since they are using different formats
3. the minimum we can do is mention in the docs for FORMAT_MODULE_PATH
that it can be set to the same path (albeit in a different format) as
LOCALE_PATHS to re-use the directory structure.
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Carlton Gibson):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Component: Documentation | Version: 1.11
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"95fd5cf459dd23d18e9ef8e1a03eb820fe7205ce" 95fd5cf4]:
{{{
#!CommitTicketReference repository=""
revision="95fd5cf459dd23d18e9ef8e1a03eb820fe7205ce"
Fixed #28403 -- Added missing formats in FORMAT_MODULE_PATH docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: karyon | Owner: Ashaba
Type: | John
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"c6c73e340178d54fa89202eea2a6666dc894646e" c6c73e3]:
{{{
#!CommitTicketReference repository=""
revision="c6c73e340178d54fa89202eea2a6666dc894646e"
[2.0.x] Fixed #28403 -- Added missing formats in FORMAT_MODULE_PATH docs.
Backport of 95fd5cf459dd23d18e9ef8e1a03eb820fe7205ce from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/28403#comment:10>