neosqlite.objectid module

ObjectId implementation for NeoSQLite that follows MongoDB’s specification.

Based on MongoDB’s ObjectId specification: - 4 bytes: timestamp (seconds since Unix epoch) - 5 bytes: random value (generated once per process) - 3 bytes: counter (incrementing from a random value)

This implementation provides full compatibility with MongoDB ObjectIds while being optimized for NeoSQLite’s local-only architecture.

class neosqlite.objectid.ObjectId(oid: str | bytes | ObjectId | int | None = None)[source]

Bases: object

A MongoDB-compatible ObjectId implementation for NeoSQLite.

This class generates 12-byte identifiers following MongoDB’s specification: - 4 bytes: timestamp (seconds since Unix epoch) - 5 bytes: random value (generated once per process) - 3 bytes: counter (incrementing from a random value)

Provides full compatibility with MongoDB ObjectIds while working with NeoSQLite.

_random_bytes: bytes | None = None
_counter: int | None = None
_counter_lock = <unlocked _thread.lock object>
__init__(oid: str | bytes | ObjectId | int | None = None)[source]

Initialize a new ObjectId.

Parameters:

oid – Can be a 12-byte binary representation, a 24-character hex string, another ObjectId instance, an integer (which replaces the timestamp), or None to generate a new ObjectId.

Raises:

  • TypeError – If the input type is not supported

  • ValueError – If the input format is invalid

classmethod _generate_new_id() → bytes[source]

Generate a new 12-byte ObjectId value according to MongoDB specification.

This method creates a unique 12-byte identifier consisting of: - 4 bytes: timestamp (seconds since Unix epoch) - 5 bytes: random value (generated once per process) - 3 bytes: counter (incrementing from a random value)

The method ensures thread safety by using a lock when accessing shared random bytes and counter values. The random bytes are generated once per process, and the counter is incremented for each new ObjectId.

Returns:

A new 12-byte ObjectId value

Return type:

bytes

classmethod _generate_new_id_with_timestamp(timestamp: int) → bytes[source]

Generate a new 12-byte ObjectId value with a specific timestamp according to MongoDB specification.

This method creates a unique 12-byte identifier with the provided timestamp and following MongoDB’s format: - 4 bytes: provided timestamp (instead of current time) - 5 bytes: random value (generated once per process) - 3 bytes: counter (incrementing from a random value)

The method ensures thread safety by using a lock when accessing shared random bytes and counter values. The random bytes are generated once per process, and the counter is incremented for each new ObjectId.

Parameters:

timestamp – An integer representing the Unix timestamp to use for the ObjectId

Returns:

A new 12-byte ObjectId value with the specified timestamp

Return type:

bytes

classmethod is_valid(oid: Any) → bool[source]

Check if the given value is a valid ObjectId.

Parameters:

oid – Value to validate

Returns:

True if the value is a valid ObjectId, False otherwise

property binary: bytes

Get the binary representation of this ObjectId.

property hex: str

Get the hexadecimal string representation of this ObjectId.

generation_time() → float[source]

Get the generation time of this ObjectId as a Unix timestamp.

Returns:

Unix timestamp of when this ObjectId was created

encode_for_storage() → dict[source]

Encode the ObjectId for JSON storage compatibility with NeoSQLite.

Returns:

A dictionary representation for JSON storage

classmethod decode_from_storage(encoded_data: dict) → ObjectId[source]

Decode an ObjectId from JSON storage format.

Parameters:

encoded_data – Dictionary representation from JSON storage

Returns:

An ObjectId instance