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

[Keryn Knight <keryn@…>]

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.

[Gabriel Hurley]

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.

[Keryn Knight <keryn@…>]

documentation changes, svn diff against revision 14990

[Keryn Knight <keryn@…>]

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.

[Gabriel Hurley]

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

[Gabriel Hurley]

(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.

[Jacob]

Milestone 1.3 deleted