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

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

Previous topic

Next topic

This Page

grid_file – Tools for representing files stored in GridFS¶

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