grid_file – Tools for representing files stored in GridFS

Tools for representing files stored in GridFS.

class gridfs.grid_file.GridIn(root_collection, session=None, **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: 255 kb)

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

Parameters:

  • root_collection (Collection) – root collection to write to

  • session (Optional[ClientSession]) – a ClientSession to use for all commands

  • kwargs (Any) – Any: 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()

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

Return type:

None

property chunk_size: Any

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.

Return type:

None

property closed: bool

Is this file closed?

property content_type: Any

DEPRECATED, will be removed in PyMongo 5.0. 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

DEPRECATED, will be removed in PyMongo 5.0. 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)

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 (Any) – string of bytes or file-like object to be written to the file

Return type:

None

writelines(sequence)

Write a sequence of strings to the file.

Does not add separators.

Parameters:

sequence (Iterable[Any])

Return type:

None

class gridfs.grid_file.GridOut(root_collection, file_id=None, file_document=None, session=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 (Collection) – root collection to read from

  • file_id (Optional[int]) – value of "_id" for the file to read

  • file_document (Optional[Any]) – file document from root_collection.files

  • session (Optional[ClientSession]) – 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__()

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.

Return type:

GridOut

property aliases: Any

DEPRECATED, will be removed in PyMongo 5.0. 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()

Make GridOut more generically file-like.

Return type:

None

property content_type: Any

DEPRECATED, will be removed in PyMongo 5.0. Mime-type for this file.

This attribute is read-only.

property filename: Any

Name of this file.

This attribute is read-only.

fileno()

Returns underlying file descriptor if one exists.

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

Return type:

NoReturn

flush()

Flush write buffers, if applicable.

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

Return type:

None

isatty()

Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.

Return type:

bool

property length: Any

Length (in bytes) of this file.

This attribute is read-only.

property md5: Any

DEPRECATED, will be removed in PyMongo 5.0. 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=-1)

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

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

Parameters:

size (int) – the number of bytes to read

Return type:

bytes

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

Return whether object was opened for reading.

If False, read() will raise OSError.

Return type:

bool

readchunk()

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

Return type:

bytes

readline(size=-1)

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

Parameters:

size (int) – the maximum number of bytes to read

Return type:

bytes

seek(pos, whence=0)

Set the current position of this file.

Parameters:

  • pos (int) – the position (or offset if using relative positioning) to seek to

  • whence (int) – 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.

Return type:

int

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

Return whether object supports random access.

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

Return type:

bool

tell()

Return the current position of this file.

Return type:

int

truncate(size=None)

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.

Parameters:

size (int | None)

Return type:

NoReturn

property upload_date: Any

Date that this file was first uploaded.

This attribute is read-only.

writable()

Return whether object was opened for writing.

If False, write() will raise OSError.

Return type:

bool

writelines(lines)

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.

Parameters:

lines (Any)

Return type:

NoReturn

class gridfs.grid_file.GridOutCursor(collection, filter=None, skip=0, limit=0, no_cursor_timeout=False, sort=None, batch_size=0, session=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.

Parameters:
add_option(*args, **kwargs)

Set arbitrary query flags using a bitmask.

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

Parameters:
Return type:

NoReturn

next()

Get next GridOut object from cursor.

Return type:

GridOut

remove_option(*args, **kwargs)

Unset arbitrary query flags using a bitmask.

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

Parameters:
Return type:

NoReturn