Opened 2 years ago

Last modified 16 months ago

#29607 assigned Cleanup/optimization

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

Reported by: Thomas Grainger Owned by: Chris Adams
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Chris Adams Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

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.

Change History (4)

comment:1 Changed 2 years ago by Tim Graham

Component: UncategorizedDocumentation
Summary: detailed documentation/cookbook on how to handle files and their lifecycles in modelsAdd doc exmaples of handling files and their lifecycles in models (FileField)
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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.

comment:2 Changed 2 years ago by Tim Graham

Summary: Add doc exmaples of handling files and their lifecycles in models (FileField)Add doc examples of handling files and their lifecycles with FileField/models

comment:3 Changed 16 months ago by Chris Adams

Cc: Chris Adams added
Owner: changed from nobody to Chris Adams
Status: newassigned

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.

comment:4 Changed 16 months ago by felixxm

Has patch: set
Patch needs improvement: set
Summary: Add doc examples of handling files and their lifecycles with FileField/modelsAdd doc examples of handling files and their lifecycles with FileField/models.
Version: 2.0master
Note: See TracTickets for help on using tickets.
Back to Top