Add doc examples of handling files and their lifecycles with FileField/models.

[Thomas Grainger]

Currently the documentation on how to do various file operations isn't documented eg:

• I've got some file contents as a string and a model instance with a file field, I want to set the content of the instances' file to the value of the string
• I've got a file like object and I'd like to transform it line by line then append it to the file of a model field.

In all cases:

• properly managing the file lifetime open/close so that it works on non-reference counting python implementations like PyPy
• cleaning up the FieldFile so that other code that accesses the file still works
• never using up too much memory by reading a whole file into memory

Also, are some methods like: instance.file.read() without an associated with instance.file.open() always dangerous - and should they be deprecated?

Should the Django File instances operate more like pathlib.PurePath ? in that .read() opens the file, reads the content then closes it, and .write() opens the file, writes the file, then closes it.

[Tim Graham]

I guess docs/topics/files.txt might be the place for additional documentation.

As for your questions, they seem better asked on the DevelopersMailingList. As Python hasn't documented methods like read(), I doubt Django would but maybe there's some nuance that I missed.

[Chris Adams]

I'm happy to have a go at this.

I'm started in this branch here, adding some docs for common use cases outlined above:

• set a file by passing the file path to the instance
• set a file by making a brand new file with ContentFile
• update a file by opening in a context manager, editing the file in memory then saving
• work with a large file, using the iter in a loop
• work with a large file, in chunks, using chunks()

I wasn't sure what this referred to though - can you give me any pointers?

cleaning up the FieldFile so that other code that accesses the file still works

​https://github.com/django/django/pull/11227

For what it's worth, I'm really in favour of the pathlib instance.file.read() syntax as outlined above - not having to faff with context managers is really nice syntactic sugar.

[Mariusz Felisiak]

​PR