id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
30466	FieldFile.save documentation is misleading	gcbirzan	nobody	"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."	Bug	closed	Documentation	2.2	Normal	wontfix			Unreviewed	0	0	0	0	0	0