FieldFile.save documentation is misleading

[gcbirzan]

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.

[Carlton Gibson]

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