grid_file – Tools for representing files stored in GridFS

Tools for representing files stored in GridFS.

class gridfs.grid_file.GridIn(root_collection: pymongo.collection.Collection, session: Optional[pymongo.client_session.ClientSession] = None, **kwargs: Any)

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: 255 kb)

  • "encoding": encoding used for this file. Any str that is written to the file will be converted to bytes.

Parameters
  • root_collection: root collection to write to

  • session (optional): a ClientSession to use for all commands

  • **kwargs: Any (optional): file level options (see above)

Changed in version 4.0: Removed the disable_md5 parameter. See disable_md5 parameter is removed for details.

Changed in version 3.7: Added the disable_md5 parameter.

Changed in version 3.6: Added session parameter.

Changed in version 3.0: root_collection must use an acknowledged write_concern

_id: Any

The '_id' value for this file.

This attribute is read-only.

abort() None

Remove all chunks/files that may have been uploaded and close.

property chunk_size: Any

Chunk size for this file.

This attribute is read-only.

close() None

Flush the file and close it.

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

property closed: bool

Is this file closed?

property content_type: Any

Mime-type for this file.

property filename: Any

Name of this file.

property length: Any

Length (in bytes) of this file.

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

property md5: Any

MD5 of the contents of this file if an md5 sum was created.

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

property name: Any

Alias for filename.

property upload_date: Any

Date that this file was uploaded.

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

write(data: Any) None

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 str 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 bytes, a file-like object, or an instance of str. 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

writelines(sequence: Iterable[Any]) None

Write a sequence of strings to the file.

Does not add seperators.

class gridfs.grid_file.GridOut(root_collection: pymongo.collection.Collection, file_id: Optional[int] = None, file_document: Optional[Any] = None, session: Optional[pymongo.client_session.ClientSession] = None)

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 (optional): value of "_id" for the file to read

  • file_document (optional): file document from root_collection.files

  • session (optional): a ClientSession to use for all commands

Changed in version 3.8: For better performance and to better follow the GridFS spec, GridOut now uses a single cursor to read all the chunks in the file.

Changed in version 3.6: Added session parameter.

Changed in version 3.0: Creating a GridOut does not immediately retrieve the file metadata from the server. Metadata is fetched when first needed.

_id: Any

The '_id' value for this file.

This attribute is read-only.

__iter__() gridfs.grid_file.GridOut

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

The iterator will return lines (delimited by b'\n') of bytes. This can be useful when serving files using a webserver that handles such an iterator efficiently.

Changed in version 3.8: The iterator now raises CorruptGridFile when encountering any truncated, missing, or extra chunk in a file. The previous behavior was to only raise CorruptGridFile on a missing chunk.

Changed in version 4.0: The iterator now iterates over lines in the file, instead of chunks, to conform to the base class io.IOBase. Use GridOut.readchunk() to read chunk by chunk instead of line by line.

property aliases: Any

List of aliases for this file.

This attribute is read-only.

property chunk_size: Any

Chunk size for this file.

This attribute is read-only.

close() None

Make GridOut more generically file-like.

property content_type: Any

Mime-type for this file.

This attribute is read-only.

property filename: Any

Name of this file.

This attribute is read-only.

fileno() NoReturn

Returns underlying file descriptor if one exists.

OSError is raised if the IO object does not use a file descriptor.

flush() None

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

isatty() bool

Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.

property length: Any

Length (in bytes) of this file.

This attribute is read-only.

property md5: Any

MD5 of the contents of this file if an md5 sum was created.

This attribute is read-only.

property metadata: Any

Metadata attached to this file.

This attribute is read-only.

property name: Any

Alias for filename.

This attribute is read-only.

read(size: int = - 1) bytes

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

Changed in version 3.8: This method now only checks for extra chunks after reading the entire file. Previously, this method would check for extra chunks on every call.

readable() bool

Return whether object was opened for reading.

If False, read() will raise OSError.

readchunk() bytes

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

readline(size: int = - 1) bytes

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

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

seek(pos: int, whence: int = 0) int

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.

Changed in version 4.1: The method now returns the new position in the file, to conform to the behavior of io.IOBase.seek().

seekable() bool

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

tell() int

Return the current position of this file.

truncate(size: Optional[int] = None) NoReturn

Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Returns the new size.

property upload_date: Any

Date that this file was first uploaded.

This attribute is read-only.

writable() bool

Return whether object was opened for writing.

If False, write() will raise OSError.

writelines(lines: Any) NoReturn

Write a list of lines to stream.

Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end.

class gridfs.grid_file.GridOutCursor(collection: pymongo.collection.Collection, filter: Optional[Mapping[str, Any]] = None, skip: int = 0, limit: int = 0, no_cursor_timeout: bool = False, sort: Optional[Any] = None, batch_size: int = 0, session: Optional[pymongo.client_session.ClientSession] = None)

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

The MongoDB documentation on cursors.

add_option(*args: Any, **kwargs: Any) NoReturn

Set arbitrary query flags using a bitmask.

To set the tailable flag: cursor.add_option(2)

next() gridfs.grid_file.GridOut

Get next GridOut object from cursor.

remove_option(*args: Any, **kwargs: Any) NoReturn

Unset arbitrary query flags using a bitmask.

To unset the tailable flag: cursor.remove_option(2)