GridFS

MongoKit implements GridFS support and brings some helpers to facilitate the use of relative small files.

Let’s create a document Doc which have two attachment in GridFS named as source and template:

>>> from mongokit import *
>>> class Doc(Document):
...        structure = {
...            'title':unicode,
...        }
...        gridfs = ['source', 'template']

new in version 0.5.4

The gridfs API as slightly changed. You might want to be able to add file in gridfs on the fly without knowing their name. The new API allow to add “containers” to gridfs. So, the gridfs declaration look like this

gridfs = {
  'files':['source', 'template'],
  'containers': ['images'],
}

As you can see, nothing hard. We just declare our attachment files in the gridfs attribute. Filling this attribute will generate an fs attribute at runtime. This fs attribute is actually an object which deal with GridFS.

>>> connection = Connection()
>>> connection.register([Doc])
>>> doc = connection.test.tutorial.Doc()
>>> doc['title'] = u'Hello'
>>> doc.save()

Before using gridfs attachment, you have to save the document. This is required as under the hood, mongokit use the document _id to link with GridFS files.

The simple way

All gridfs attachments are accessible via the fs object. Now, we can fill the source and template:

>>> doc.fs.source = "Hello World !"
>>> doc.fs.template = "My pretty template"

And that’s it ! By doing this, MongoKit will open a GridFile, fill it with the value, and close it.

Note that you have to be carefull to the type : attachments only accept string.

You can read any attachment in a very simple way :

>>> doc.fs.source
'Hello World !'

new in version 0.5.4

You can add any image you want to the container “images”:

>>> doc.fs.images['image1.png'] = "..."
>>> doc.fs.images['image1.png']
'...'
>>> doc.fs.images['image2.png'] = '...'

This is very usefull when you want of store a number of file but you don’t know their names.

new in version 0.5.4

If you have python-magic installed (sudo easy_install -U python-magic), the content-type of the file is automatically guessed. To access to it, you have to use the “full way”.

new in version 0.5.4

If you do not know stored file names, you can list them with list:

>>> doc.fs.list()
['source', 'template']

or by iteration :

>>> for file_name in doc.fs:
...     print file_name

You can list a container as well. In this case, the container name is shown : container_name/file_name

>>> doc.fs.images.list():
['images/image1.png', 'images/image2.png']

>>> for file_name in doc.fs.images:
...     print file_name

The full way

While the previous method is very easy, it might not be enougth if you’re dealing with very big files or want to use some file related feature (for instance, using seek to not have to load all the file in memory)

You can do that with using the open() method on the fs object. The open() method take the file name and the opened mode (‘r’ for read, ‘w’ for write) :

>>> f = doc.fs.open("source", 'w')
>>> f.write("Hello World again !")
>>> f.close()

Caution ! Don’t forget to close the file or every else will be blocked. If you experiencing some general blocking, you might check if you don’t forget to close an opened file.

>>> doc.fs.source
'Hello World again !'

new in version 0.5.4

You can add any image you want to the container “images”:

>>> f = doc.fs.images.open('image1.png', 'w')
>>> f.write('...')
>>> f.close()
>>> f = doc.fs.images.open('image1.png')
>>> f.read()
'...'
>>> f.close()

new in version 0.5.4

You can get the content-type (mime type) of a file :

>>> f = doc.fs.open("source", 'w')
>>> f.write("Hello World again !")
>>> f.content_type
'text/plain; charset=us-ascii'
>>> f.close()