grid_file -- Tools for representing files stored in GridFS#

Tools for representing files stored in GridFS.

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

在 4.0 版本发生变更: Removed the disable_md5 parameter. See DISABLE_MD5参数已删除 for details.

在 3.7 版本发生变更: Added the disable_md5 parameter.

在 3.6 版本发生变更: Added session parameter.

在 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 separators.

class gridfs.grid_file.GridOut(root_collection: Collection, file_id: int | None = None, file_document: Any | None = None, session: ClientSession | None = 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

在 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.

在 3.6 版本发生变更: Added session parameter.

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

在 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.

在 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 bytes If size is negative or omitted all data is read.

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

在 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.

在 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: int | None = 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: Collection, filter: Mapping[str, Any] | None = None, skip: int = 0, limit: int = 0, no_cursor_timeout: bool = False, sort: Any | None = None, batch_size: int = 0, session: ClientSession | None = None)#

Create a new cursor, similar to the normal Cursor.

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

参见

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