neosqlite.gridfs.grid_file module¶

class neosqlite.gridfs.grid_file.GridIn(db: Connection, bucket_name: str, chunk_size_bytes: int, filename: str, metadata: dict[str, Any] | None = None, file_id: ObjectId | int | None = None, disable_md5: bool = False, write_concern: dict[str, Any] | None = None, content_type: str | None = None, aliases: list[str] | None = None)[source]¶

Bases: object

A file-like object for writing data to GridFS.

This class provides a writable interface for storing files in GridFS.

__init__(db: Connection, bucket_name: str, chunk_size_bytes: int, filename: str, metadata: dict[str, Any] | None = None, file_id: ObjectId | int | None = None, disable_md5: bool = False, write_concern: dict[str, Any] | None = None, content_type: str | None = None, aliases: list[str] | None = None)[source]¶

Initialize a new GridIn instance.

Parameters:

db – SQLite database connection
bucket_name – The bucket name for the GridFS files
chunk_size_bytes – The chunk size in bytes
filename – The name of the file
metadata – Optional metadata for the file
file_id – Optional custom file ID
disable_md5 – Disable MD5 checksum calculation for performance
write_concern – Write concern settings (simulated for compatibility)
content_type – Optional MIME type of the file
aliases – Optional list of alternative names for the file

_serialize_aliases() → str | None[source]¶

Serialize aliases to JSON string.

Returns:: JSON string representation or None

_serialize_metadata(metadata: dict[str, Any] | None) → str | None[source]¶

Serialize metadata to JSON string.

Parameters:: metadata – Metadata dictionary to serialize
Returns:: JSON string representation or None

_deserialize_metadata(metadata_str: str | None) → dict[str, Any] | None[source]¶

Deserialize metadata from JSON string.

Parameters:: metadata_str – JSON string representation of metadata
Returns:: Metadata dictionary or None

_deserialize_aliases(aliases_str: str | None) → list[str] | None[source]¶

Deserialize aliases from JSON string.

Parameters:: aliases_str – JSON string representation of aliases
Returns:: List of alias strings or None

_force_sync_if_needed()[source]¶: Force database synchronization if write concern requires it.

write(data: bytes | bytearray) → int[source]¶

Write data to the GridIn stream.

Parameters:: data – The data to write
Returns:: The number of bytes written

_flush_chunk() → None[source]¶

Flush a chunk from the buffer to the database.

This method extracts a chunk of data from the internal buffer and writes it to the chunks collection in the database. If this is the first chunk being written and no file ID has been set, it creates the corresponding file document first. The chunk is inserted with its sequence number and associated with the file ID.

_create_file_document() → None[source]¶

Create the file document in the files collection.

This method creates a new file document in the GridFS files collection with the necessary metadata. It handles both ObjectId and integer file IDs, storing them appropriately in the database. The method stores the filename, chunk size, upload date, and serialized metadata. If no file ID is provided, it generates a new ObjectId for the file.

_get_file_id() → int[source]¶

Get the file ID, creating the file document if necessary.

This method returns the integer ID of the file, which is used internally for database operations. If the file document hasn’t been created yet, it creates one first. The method handles both ObjectId and integer file IDs, looking up the corresponding integer ID in the database when needed.

Returns:: The integer ID of the file for database operations
Return type:: int
Raises:: RuntimeError – If the file cannot be found in the database

close() → None[source]¶

Close the GridIn stream and finalize the file storage.

This method flushes any remaining data in the buffer to the database, completes the file document with final metadata including length and MD5 hash, and ensures the file is properly stored in GridFS. If no chunks have been written yet, it still creates the file document. The method also handles database synchronization if required by the write concern settings.

class neosqlite.gridfs.grid_file.GridOut(db: Connection, bucket_name: str, file_id: ObjectId | int)[source]¶

Bases: object

A file-like object for reading data from GridFS.

This class provides a readable interface for retrieving files from GridFS.

__init__(db: Connection, bucket_name: str, file_id: ObjectId | int)[source]¶

Initialize a new GridOut instance.

Parameters:

db – SQLite database connection
bucket_name – The bucket name for the GridFS files
file_id – The ID of the file to read (ObjectId or integer)

property _id¶: Get the file’s actual ID, which may be an ObjectId or integer.

property _file_id¶: Get the file’s actual ID that represents what the user expects as the ID. For compatibility with the original API, this returns the actual ID (ObjectId or int).

_deserialize_metadata(metadata_str: str | None) → dict[str, Any] | None[source]¶

Deserialize metadata from JSON string.

Parameters:: metadata_str – JSON string representation of metadata
Returns:: Metadata dictionary or None

_deserialize_aliases(aliases_str: str | None) → list[str] | None[source]¶

Deserialize aliases from JSON string.

Parameters:: aliases_str – JSON string representation of aliases
Returns:: List of alias strings or None

read(size: int = -1) → bytes[source]¶

Read data from the GridOut stream.

Parameters:: size – The number of bytes to read (-1 for all remaining data)
Returns:: The data read from the stream

_load_chunk() → None[source]¶: Load the chunk containing the current position.

property filename: str¶: Get the filename.

property length: int¶: Get the length of the file in bytes.

property chunk_size: int¶: Get the chunk size in bytes.

property upload_date: str¶: Get the upload date.

property md5: str¶: Get the MD5 hash of the file.

property metadata: dict[str, Any] | None¶: Get the metadata of the file.

property content_type: str | None¶: Get the content type (MIME type) of the file.

property aliases: list[str] | None¶: Get the aliases (alternative names) for the file.

close() → None[source]¶: Close the GridOut stream.

class neosqlite.gridfs.grid_file.GridOutCursor(db: Connection, bucket_name: str, filter: dict[str, Any])[source]¶

Bases: object

A cursor for iterating over GridFS files.

This class provides an iterator interface for retrieving file documents from GridFS.

__init__(db: Connection, bucket_name: str, filter: dict[str, Any])[source]¶

Initialize a new GridOutCursor instance.

Parameters:

db – SQLite database connection
bucket_name – The bucket name for the GridFS files
filter – The filter to apply when searching for files