improve doc of GridFS, emphasize that subsequent call to read() requires to rewind the file with seek(0)

This commit is contained in:
Bastien Gérard 2019-12-27 10:38:03 +01:00
parent b3dbb87c3c
commit e7c7a66cd1

View File

@ -10,8 +10,9 @@ Writing
GridFS support comes in the form of the :class:`~mongoengine.fields.FileField` field GridFS support comes in the form of the :class:`~mongoengine.fields.FileField` field
object. This field acts as a file-like object and provides a couple of object. This field acts as a file-like object and provides a couple of
different ways of inserting and retrieving data. Arbitrary metadata such as different ways of inserting and retrieving data. Arbitrary metadata such as
content type can also be stored alongside the files. In the following example, content type can also be stored alongside the files. The object returned when accessing a
a document is created to store details about animals, including a photo:: FileField is a proxy to `Pymongo's GridFS <https://api.mongodb.com/python/current/examples/gridfs.html#gridfs-example>`_
In the following example, a document is created to store details about animals, including a photo::
class Animal(Document): class Animal(Document):
genus = StringField() genus = StringField()
@ -34,6 +35,20 @@ field. The file can also be retrieved just as easily::
photo = marmot.photo.read() photo = marmot.photo.read()
content_type = marmot.photo.content_type content_type = marmot.photo.content_type
.. note:: If you need to read() the content of a file multiple times, you'll need to "rewind"
the file-like object using `seek`::
marmot = Animal.objects(genus='Marmota').first()
content1 = marmot.photo.read()
assert content1 != ""
content2 = marmot.photo.read() # will be empty
assert content2 == ""
marmot.photo.seek(0) # rewind the file by setting the current position of the cursor in the file to 0
content3 = marmot.photo.read()
assert content3 == content1
Streaming Streaming
--------- ---------