#30466: FieldFile.save documentation is misleading
-----------------------------------------+------------------------
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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/051.97319de203df990dcb370e22eff135e4%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
