Opened 13 months ago

Closed 7 months ago

Last modified 7 months ago

#28403 closed Cleanup/optimization (fixed)

Improve the example for FORMAT_MODULE_PATH and add missing formats

Reported by: karyon Owned by: Ashaba John
Component: Documentation Version: 1.11
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

two issues with the 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.

Change History (10)

comment:1 Changed 13 months ago by Tim Graham

Summary: FORMAT_MODULE_PATH documentation lackingImprove the example for FORMAT_MODULE_PATH and add missing formats
Triage Stage: UnreviewedAccepted

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.

comment:2 Changed 13 months ago by karyon

To be specific, with "locale path" I meant the LOCALE_PATHS setting as far as I understand, the 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

Last edited 13 months ago by Tim Graham (previous) (diff)

comment:3 Changed 11 months ago by Ashaba John

Owner: changed from nobody to Ashaba John
Status: newassigned

comment:4 Changed 7 months ago by karyon

ashaba do you still plan to work on this?

comment:5 Changed 7 months ago by Tim Graham

Has patch: set

comment:6 Changed 7 months ago 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?

comment:7 Changed 7 months ago 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.
  1. make FORMAT_MODULE_PATH look into LOCALE_PATHS by default. Not sure whether that is nice since they are using different formats
  1. 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.

comment:8 Changed 7 months ago by Carlton Gibson

Triage Stage: AcceptedReady for checkin

comment:9 Changed 7 months ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 95fd5cf4:

Fixed #28403 -- Added missing formats in FORMAT_MODULE_PATH docs.

comment:10 Changed 7 months ago by Tim Graham <timograham@…>

In c6c73e3:

[2.0.x] Fixed #28403 -- Added missing formats in FORMAT_MODULE_PATH docs.

Backport of 95fd5cf459dd23d18e9ef8e1a03eb820fe7205ce from master

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