grid_file – Tools for representing files stored in GridFS — PyMongo 2.7.2 documentation

# `grid_file` – Tools for representing files stored in GridFS

Tools for representing files stored in GridFS.

class `gridfs.grid_file.` `GridIn`(root_collection, **kwargs)

  Write a file to GridFS

  Application developers should generally not need to instantiate this class directly - instead see the methods provided by `GridFS`.

  Raises `TypeError` if root_collection is not an instance of `Collection`.

  Any of the file level options specified in the GridFS Spec may be passed as keyword arguments. Any additional keyword arguments will be set as additional fields on the file document. Valid keyword arguments include:

  > - `"_id"`: unique ID for this file (default: `ObjectId`) - this `"_id"` must not have already been used for another file
  > - `"filename"`: human name for the file
  > - `"contentType"` or `"content_type"`: valid mime-type for the file
  > - `"chunkSize"` or `"chunk_size"`: size of each of the chunks, in bytes (default: 256 kb)
  > - `"encoding"`: encoding used for this file. In Python 2, any `unicode` that is written to the file will be converted to a `str`. In Python 3, any `str` that is written to the file will be converted to `bytes`.

  If you turn off write-acknowledgment for performance reasons, it is critical to wrap calls to `write()` and `close()` within a single request:

      >>> from pymongo import MongoClient
      >>> from gridfs import GridFS
      >>> client = MongoClient(w=0) # turn off write acknowledgment
      >>> fs = GridFS(client.database)
      >>> gridin = fs.new_file()
      >>> request = client.start_request()
      >>> try:
      ...     for i in range(10):
      ...         gridin.write('foo')
      ...     gridin.close()
      ... finally:
      ...     request.end()

  In Python 2.5 and later this code can be simplified with a with-statement, see Requests for more information.

  Parameters: | root_collection: root collection to write to **kwargs (optional): file level options (see above)

  `_id`

    The `'_id'` value for this file.

    This attribute is read-only.

  `chunk_size`

    Chunk size for this file.

    This attribute is read-only.

  `close`()

    Flush the file and close it.

    A closed file cannot be written any more. Calling `close()` more than once is allowed.

  `closed`

    Is this file closed?

  `content_type`

    Mime-type for this file.

  `filename`

    Name of this file.

  `length`

    Length (in bytes) of this file.

    This attribute is read-only and can only be read after `close()` has been called.

  `md5`

    MD5 of the contents of this file (generated on the server).

    This attribute is read-only and can only be read after `close()` has been called.

  `name`

    Alias for filename.

  `upload_date`

    Date that this file was uploaded.

    This attribute is read-only and can only be read after `close()` has been called.

  `write`(data)

    Write data to the file. There is no return value.

    data can be either a string of bytes or a file-like object (implementing `read()`). If the file has an `encoding` attribute, data can also be a `unicode` (`str` in python 3) instance, which will be encoded as `encoding` before being written.

    Due to buffering, the data may not actually be written to the database until the `close()` method is called. Raises `ValueError` if this file is already closed. Raises `TypeError` if data is not an instance of `str` (`bytes` in python 3), a file-like object, or an instance of `unicode` (`str` in python 3). Unicode data is only allowed if the file has an `encoding` attribute.

    Parameters: | data: string of bytes or file-like object to be written to the file

    New in version 1.9: The ability to write `unicode`, if the file has an `encoding` attribute.

  `writelines`(sequence)

    Write a sequence of strings to the file.

    Does not add seperators.

class `gridfs.grid_file.` `GridOut`(root_collection, file_id=None, file_document=None, _connect=True)

  Read a file from GridFS

  Application developers should generally not need to instantiate this class directly - instead see the methods provided by `GridFS`.

  Either file_id or file_document must be specified, file_document will be given priority if present. Raises `TypeError` if root_collection is not an instance of `Collection`.

  Parameters: | root_collection: root collection to read from file_id: value of `"_id"` for the file to read file_document: file document from root_collection.files

  New in version 1.9: The file_document parameter.

  `_id`

    The `'_id'` value for this file.

    This attribute is read-only.

  `__iter__`()

    Return an iterator over all of this file’s data.

    The iterator will return chunk-sized instances of `str` (`bytes` in python 3). This can be useful when serving files using a webserver that handles such an iterator efficiently.

  `aliases`

    List of aliases for this file.

    This attribute is read-only.

  `chunk_size`

    Chunk size for this file.

    This attribute is read-only.

  `close`()

    Make GridOut more generically file-like.

  `content_type`

    Mime-type for this file.

    This attribute is read-only.

  `filename`

    Name of this file.

    This attribute is read-only.

  `length`

    Length (in bytes) of this file.

    This attribute is read-only.

  `md5`

    MD5 of the contents of this file (generated on the server).

    This attribute is read-only.

  `metadata`

    Metadata attached to this file.

    This attribute is read-only.

  `name`

    Alias for filename.

    This attribute is read-only.

  `read`(size=-1)

    Read at most size bytes from the file (less if there isn’t enough data).

    The bytes are returned as an instance of `str` (`bytes` in python 3). If size is negative or omitted all data is read.

    Parameters: | size (optional): the number of bytes to read

  `readchunk`()

    Reads a chunk at a time. If the current position is within a chunk the remainder of the chunk is returned.

  `readline`(size=-1)

    Read one line or up to size bytes from the file.

    Parameters: | size (optional): the maximum number of bytes to read

    New in version 1.9.

  `seek`(pos, whence=0)

    Set the current position of this file.

    Parameters: | pos: the position (or offset if using relative positioning) to seek to whence (optional): where to seek from. `os.SEEK_SET` (`0`) for absolute file positioning, `os.SEEK_CUR` (`1`) to seek relative to the current position, `os.SEEK_END` (`2`) to seek relative to the file’s end.

  `tell`()

    Return the current position of this file.

  `upload_date`

    Date that this file was first uploaded.

    This attribute is read-only.

class `gridfs.grid_file.` `GridFile`(*args, **kwargs)

  No longer supported.

  Changed in version 1.6: The GridFile class is no longer supported.

class `gridfs.grid_file.` `GridOutCursor`(collection, spec=None, skip=0, limit=0, timeout=True, sort=None, max_scan=None, read_preference=None, tag_sets=None, secondary_acceptable_latency_ms=None, compile_re=True)

  Create a new cursor, similar to the normal `Cursor`.

  Should not be called directly by application developers - see the `GridFS` method `find()` instead.

  See also

  See general MongoDB documentation

  cursors

  `next`()

    Get next GridOut object from cursor.