Opened 14 years ago

Closed 14 years ago

Last modified 13 years ago

#14905 closed (fixed)

models.FileField links to url attribute, which is undocumented.

Reported by: Keryn Knight <keryn@…> Owned by: nobody
Component: Documentation Version: dev
Severity: Keywords: filefield url easy-pickings
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

As part of the documentation callout on FileField.storage found in the Model Field Types documentation here, reference is made to the FileField.url attribute, which links to the documentation on the File class itself, where it is decidedly absent.

Following the rabbit hole from the original note on the modelfields through the Managing Files documentation, and on to the how-to on writing a custom storage backend (where a note is made that any custom solution must implement the url() method) we finally end up at the Storage API which does discuss the method.

It's a convoluted process, and I think the ref documentation on File should either document the attribute, or the model FileField reference should link to the documentation for the Storage API itself.

I can attempt to work up a documentation patch if the ticket has merit.

Attachments (1)

django-documentation-14990.diff (1.2 KB ) - added by Keryn Knight <keryn@…> 14 years ago.
documentation changes, svn diff against revision 14990

Download all attachments as: .zip

Change History (6)

comment:1 by Gabriel Hurley, 14 years ago

milestone: 1.3
Triage Stage: UnreviewedAccepted

The answer is much simpler here: all three of those attributes are mis-linked. They should reference django.core.files.storage.Storage instead of django.core.files.File.

There was recently a ticket that pointed out that url wasn't an attribute on django.core.files.File at all, and the docs were subsequently reworked to remove the reference from the File API page.

What surprises me is that the crossref link to that anchor on the page still resolved itself somehow. Whoever commits a fix for this, please build the docs locally to make sure links to django.core.files.File.url no longer resolve. I'm hoping it was just a bit of bad caching that kept the link there this time.

by Keryn Knight <keryn@…>, 14 years ago

documentation changes, svn diff against revision 14990

comment:2 by Keryn Knight <keryn@…>, 14 years ago

Has patch: set
Keywords: easy-pickings added

I've attempted a documentation patch, although I'm still not sure it's correct — all three cannot be mis-linked, as far as I can tell, because there's no documentation on the name attribute on Storage implementations. For better or worse then, I've left the name attribute pointing at django.core.files.File , and updated the others, adding the caveat that it's up to the Storage class in use to implement them.

I'm adding it as easy-pickings, because even if the current patch isn't workable, it shouldn't be hard for someone perhaps wiser in the file/storage internals to improve.

comment:3 by Gabriel Hurley, 14 years ago

Resolution: fixed
Status: newclosed

(In [15088]) Fixed #14905 -- Corrected some misleading linking and language in the FileField docs. Thanks to Keryn Knight for the report and draft patch.

comment:4 by Gabriel Hurley, 14 years ago

(In [15089]) [1.2.X] Fixed #14905 -- Corrected some misleading linking and language in the FileField docs. Thanks to Keryn Knight for the report and draft patch.

Backport of [15088] from trunk.

comment:5 by Jacob, 13 years ago

milestone: 1.3

Milestone 1.3 deleted

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