[Django] #30466: FieldFile.save documentation is misleading
Django
-----------------------------------------+------------------------
Reporter: gcbirzan | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 2.2
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 |
-----------------------------------------+------------------------
From
https://docs.djangoproject.com/en/2.2/ref/models/fields/#django.db.models.fields.files.FieldFile.save
:
> This method takes a filename and file contents
It doesn't.
> Takes [...] content which is an object containing the file’s contents
Technically, a file-like object is an object containing the file's
contents. But that's a stretch, to be fair.
From reading the first part (and the name of the parameter), most people
would assume that the content parameter is the actual content of the file.
It's not until the note where you are told you might be wrong:
> Note that the content argument should be an instance of
django.core.files.File, not Python’s built-in file object
This part is even more misleading, since a file-like object (`io.BytesIO`)
works just fine. But, this is the only place where you find out the
`contents` parameter doesn't actually mean "file's contents", but actually
"`django.core.files.File-like` object (maybe) that contains contents".
I have some ideas on how to fix the documentation part (the parameter
name, while initially misleading, is not such a big deal as the name and
the '`content`' are both required parameters and most people are passing
them as positional args), but after some discussion in #django on
freenode, I'm not 100% sure that everyone agrees that the documentation is
misleading.
--
Ticket URL: <https://code.djangoproject.com/ticket/30466>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: gcbirzan | Owner: nobody
Type: Bug | Status: closed
Component: Documentation | Version: 2.2
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Carlton Gibson):
* status: new => closed
* resolution: => wontfix
Comment:
I think this is quite clear as is. (Or at least clear enough given the
depth of the domain, and the link to the Managing files guide.)
You're expected to read the whole thing. The terms are introduced and then
explained as it goes along.
If it were the other way round I think it would engender **more**
confusion:
> - "What's a django.core.files.File`?"
> - "Well it's an object containing the file's contents... — but let's dig
more."
At that point the linked Managing files docs are worth a read.
Happy to look at concrete suggestions but...
--
Ticket URL: <https://code.djangoproject.com/ticket/30466#comment:1>