txmongo._gridfs package

Submodules

txmongo._gridfs.errors module

Exceptions raised by the gridfs package

exception txmongo._gridfs.errors.CorruptGridFile[source]

Bases: txmongo._gridfs.errors.GridFSError

Raised when a file in GridFS is malformed.

exception txmongo._gridfs.errors.GridFSError[source]

Bases: Exception

Base class for all GridFS exceptions.

New in version 1.5.

exception txmongo._gridfs.errors.NoFile[source]

Bases: txmongo._gridfs.errors.GridFSError

Raised when trying to read from a non-existent file.

New in version 1.6.

exception txmongo._gridfs.errors.UnsupportedAPI[source]

Bases: txmongo._gridfs.errors.GridFSError

Raised when trying to use the old GridFS API.

In version 1.6 of the PyMongo distribution there were backwards incompatible changes to the GridFS API. Upgrading shouldn’t be difficult, but the old API is no longer supported (with no deprecation period). This exception will be raised when attempting to use unsupported constructs from the old API.

New in version 1.6.

txmongo._gridfs.grid_file module

Tools for representing files stored in GridFS.

class txmongo._gridfs.grid_file.GridIn(root_collection, **kwargs)[source]

Bases: object

Class to write data to GridFS.

chunk_size

Chunk size for this file.

This attribute is read-only.

close()[source]

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.

This attribute can only be set before close() has been called.

filename

Name of this file.

This attribute can only be set before close() has been called.

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.

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)[source]

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()).

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 or a file-like object.

Parameters:
  • data: string of bytes or file-like object to be written to the file
writelines(sequence)[source]

Write a sequence of strings to the file.

Does not add separators.

class txmongo._gridfs.grid_file.GridOut(root_collection, doc)[source]

Bases: object

Class to read data out of GridFS.

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()[source]
content_type

Mime-type for 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

Name of this file.

This attribute is read-only.

read(size=-1)[source]

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

The bytes are returned as an instance of str. If size is negative or omitted all data is read.

Parameters:
  • size (optional): the number of bytes to read
seek(pos, whence=0)[source]

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()[source]

Return the current position of this file.

upload_date

Date that this file was first uploaded.

This attribute is read-only.

class txmongo._gridfs.grid_file.GridOutIterator(grid_out, chunks)[source]

Bases: object

next()

Module contents

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.

class txmongo._gridfs.GridFS(database, collection='fs')[source]

Bases: object

An instance of GridFS on top of a single Database.

count(filename)[source]

Count the number of versions of a given file. Returns an integer number of versions of the file in GridFS whose filename matches filename, or raises NoFile if the file doesn’t exist. :Parameters:

  • filename: "filename" of the file to get version count of
delete(file_id)[source]

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.

Parameters:
  • file_id: "_id" of the file to delete

New in version 1.6.

get(file_id)[source]

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)[source]

Get a file from GridFS by "filename".

Returns the most recently uploaded file in GridFS with the name filename as an instance of GridOut. Raises NoFile if no such 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

New in version 1.6.

get_version(filename=None, version=-1)[source]

Get a file from GridFS by "filename". 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. Note that searching by random (unindexed) meta data is not supported here. Raises NoFile if no such version of that file exists. :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)
indexes_created()[source]

Returns a defer on the creation of this GridFS instance’s indexes

list()[source]

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

Changed in version 1.6: Removed the collection argument.

new_file(**kwargs)[source]

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().

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

New in version 1.6.

put(data, **kwargs)[source]

Put data in GridFS as a new file.

Equivalent to doing:

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

data can be either an instance of str or a file-like object providing a read() method. Any keyword arguments will be passed through to the created file - see GridIn() for possible arguments. Returns the "_id" of the created file.

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

New in version 1.6.