Opened 10 years ago

Closed 10 years ago

#3646 closed (fixed)

ABSOLUTE_URL_OVERRIDES docs are inconsistent with how they actually work

Reported by: James Bennett Owned by: Jacob
Component: Documentation Version: master
Severity: Keywords:
Cc: nsteinmetz@… Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description (last modified by James Bennett)

The docs for the ABSOLUTE_URL_OVERRIDES setting state that the keys in that dictionary should be of the form app_label.modelname, with the model name capitalized, but the code in django/db/models/ which curries get_absolute_url looks for app_label.module_name, and module_name is normalized to lower-case by that point.

So, for example, the docs say to use weblog.Entry as a key in ABSOLUTE_URL_OVERRIDES, but get_absolute_url will actually look for weblog.entry.

I'm of two minds on how to solve this; the naive solution is to have the curried get_absolute_url look for opts.module_name.capitalize(), since that will make it consistent with the examples in the docs, but it's entirely possible that someone will create a model class with an all-lowercase name (which is, I assume, why module_name is normalizing it to lowercase), in which case the better solution is to change the docs.

Attachments (1)

3646.diff (725 bytes) - added by James Bennett 10 years ago.
Documentation patch to resolve this

Download all attachments as: .zip

Change History (9)

comment:1 Changed 10 years ago by James Bennett

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedDesign decision needed

comment:2 Changed 10 years ago by James Bennett

Description: modified (diff)

comment:3 Changed 10 years ago by James Bennett

Description: modified (diff)

comment:4 Changed 10 years ago by James Bennett

(and in a wonderfully ironic twist of fate, this is partially my fault, because it was my documentation patch in #3226 which made the docs inconsistent with the actual code...)

comment:5 Changed 10 years ago by anonymous

Cc: nsteinmetz@… added

comment:6 Changed 10 years ago by Malcolm Tredinnick

Triage Stage: Design decision neededAccepted

Of the two choices, we should prefer fixing the docs: use the lower-case version and point out that people must use the lower-case version.

The capitalize() version won't work for a model called MyModel. Camel- case class names is pretty common in Python (even PEP-8 compatible).

The ideal solution would be a third option: take the key and lower-case it before comparing to the module_name. Then people can use the real Python import path in the settings file and not have to worry about Django's slightly odd "real men don't use capital letters" approach to lower-casing every name in sight. Can't immediately see how to do that in just a line or two in django. db.models.base.get_absolute_url(), though.

Changed 10 years ago by James Bennett

Attachment: 3646.diff added

Documentation patch to resolve this

comment:7 Changed 10 years ago by James Bennett

Component: MetasystemDocumentation
Owner: changed from Adrian Holovaty to Jacob
Triage Stage: AcceptedReady for checkin

comment:8 Changed 10 years ago by Malcolm Tredinnick

Resolution: fixed
Status: newclosed

(In [4672]) Fixed #3646 -- Corrected documentation for ABSOLUTE_URL_OVERRIDES. Patch from
James Bennett.

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