gridfs – Tools for working with GridFS — PyMongo 2.5 documentation

### Navigation

- index
- modules |
- next |
- previous |
- PyMongo 2.5 documentation »
- API Documentation »

# `gridfs` – Tools for working with GridFS

GridFS is a specification for storing large objects in Mongo.

The `gridfs` package is an implementation of GridFS on top of `pymongo`, exposing a file-like interface.

See general MongoDB documentation

gridfs

class `gridfs.``GridFS`(database, collection='fs')

  Create a new instance of `GridFS`.

  Raises `TypeError` if database is not an instance of `Database`.

  Parameters : | database: database to use collection (optional): root collection to use

  New in version 1.6: The collection parameter.

  See general MongoDB documentation

  gridfs

  `delete`(file_id)

    Delete a file from GridFS by `"_id"`.

    Removes all data belonging to the file with `"_id"`: file_id.

    Warning

    Any processes/threads reading from the file while this method is executing will likely see an invalid/corrupt file. Care should be taken to avoid concurrent reads to a file while it is being deleted.

    Note

    Deletes of non-existent files are considered successful since the end result is the same: no file with that _id remains.

    Parameters : | file_id: `"_id"` of the file to delete

    New in version 1.6.

  `exists`(document_or_id=None, **kwargs)

    Check if a file exists in this instance of `GridFS`.

    The file to check for can be specified by the value of its `_id` key, or by passing in a query document. A query document can be passed in as dictionary, or by using keyword arguments. Thus, the following three calls are equivalent:

        >>> fs.exists(file_id)
        >>> fs.exists({"_id": file_id})
        >>> fs.exists(_id=file_id)

    As are the following two calls:

        >>> fs.exists({"filename": "mike.txt"})
        >>> fs.exists(filename="mike.txt")

    And the following two:

        >>> fs.exists({"foo": {"$gt": 12}})
        >>> fs.exists(foo={"$gt": 12})

    Returns `True` if a matching file exists, `False` otherwise. Calls to `exists()` will not automatically create appropriate indexes; application developers should be sure to create indexes if needed and as appropriate.

    Parameters : | document_or_id (optional): query document, or _id of the document to check for **kwargs (optional): keyword arguments are used as a query document, if they’re present.

    New in version 1.8.

  `get`(file_id)

    Get a file from GridFS by `"_id"`.

    Returns an instance of `GridOut`, which provides a file-like interface for reading.

    Parameters : | file_id: `"_id"` of the file to get

    New in version 1.6.

  `get_last_version`(filename=None, **kwargs)

    Get the most recent version of a file in GridFS by `"filename"` or metadata fields.

    Equivalent to calling `get_version()` with the default version (`-1`).

    Parameters : | filename: `"filename"` of the file to get, or None **kwargs (optional): find files by custom metadata.

    Changed in version 1.11: filename defaults to None;

    New in version 1.11: Accept keyword arguments to find files by custom metadata. See `get_version()`.

    New in version 1.6.

  `get_version`(filename=None, version=-1, **kwargs)

    Get a file from GridFS by `"filename"` or metadata fields.

    Returns a version of the file in GridFS whose filename matches filename and whose metadata fields match the supplied keyword arguments, as an instance of `GridOut`.

    Version numbering is a convenience atop the GridFS API provided by MongoDB. If more than one file matches the query (either by filename alone, by metadata fields, or by a combination of both), then version `-1` will be the most recently uploaded matching file, `-2` the second most recently uploaded, etc. Version `0` will be the first version uploaded, `1` the second version, etc. So if three versions have been uploaded, then version `0` is the same as version `-3`, version `1` is the same as version `-2`, and version `2` is the same as version `-1`.

    Raises `NoFile` if no such version of that file exists.

    An index on `{filename: 1, uploadDate: -1}` will automatically be created when this method is called the first time.

    Parameters : | filename: `"filename"` of the file to get, or None version (optional): version of the file to get (defaults to -1, the most recent version uploaded) **kwargs (optional): find files by custom metadata.

    Changed in version 1.11: filename defaults to None;

    New in version 1.11: Accept keyword arguments to find files by custom metadata.

    New in version 1.9.

  `list`()

    List the names of all files stored in this instance of `GridFS`.

    Changed in version 1.6: Removed the collection argument.

  `new_file`(**kwargs)

    Create a new file in GridFS.

    Returns a new `GridIn` instance to which data can be written. Any keyword arguments will be passed through to `GridIn()`.

    If the `"_id"` of the file is manually specified, it must not already exist in GridFS. Otherwise `FileExists` is raised.

    Parameters : | **kwargs (optional): keyword arguments for file creation

    New in version 1.6.

  `open`(*args, **kwargs)

    No longer supported.

    Changed in version 1.6: The open method is no longer supported.

  `put`(data, **kwargs)

    Put data in GridFS as a new file.

    Equivalent to doing:

        try:
            f = new_file(**kwargs)
            f.write(data)
        finally
            f.close()

    data can be either an instance of `str` (`bytes` in python 3) or a file-like object providing a `read()` method. If an encoding keyword argument is passed, data can also be a `unicode` (`str` in python 3) instance, which will be encoded as encoding before being written. Any keyword arguments will be passed through to the created file - see `GridIn()` for possible arguments. Returns the `"_id"` of the created file.

    If the `"_id"` of the file is manually specified, it must not already exist in GridFS. Otherwise `FileExists` is raised.

    Parameters : | data: data to be written as a file. **kwargs (optional): keyword arguments for file creation

    New in version 1.9: The ability to write `unicode`, if an encoding has been specified as a keyword argument.

    New in version 1.6.

  `remove`(*args, **kwargs)

    No longer supported.

    Changed in version 1.6: The remove method is no longer supported.

Sub-modules:

- `errors` – Exceptions raised by the `gridfs` package
- `grid_file` – Tools for representing files stored in GridFS

### Navigation

- index
- modules |
- next |
- previous |
- PyMongo 2.5 documentation »
- API Documentation »