neosqlite.collection.type_utils module

Shared type checking and conversion utilities for the collection package.

This module consolidates type-related utility functions that are used across multiple submodules (expr_evaluator, query_helper, etc.) to avoid code duplication and provide a single source of truth for type operations.

neosqlite.collection.type_utils._convert_to_int(value: Any) → Any

Convert value to int.

neosqlite.collection.type_utils._convert_to_long(value: Any) → Any

Convert value to long (64-bit int).

neosqlite.collection.type_utils._convert_to_double(value: Any) → Any

Convert value to double (float).

neosqlite.collection.type_utils._convert_to_decimal(value: Any) → Any

Convert value to decimal (float, as SQLite lacks Decimal128).

neosqlite.collection.type_utils._convert_to_string(value: Any) → Any

Convert value to string.

neosqlite.collection.type_utils._convert_to_bool(value: Any) → Any

Convert value to bool.

neosqlite.collection.type_utils._convert_to_objectid(value: Any) → Any

Convert value to ObjectId.

neosqlite.collection.type_utils._convert_to_bindata(value: Any) → Any

Convert value to Binary (binData).

neosqlite.collection.type_utils._convert_to_bsonbindata(value: Any) → Any

Convert value to Binary (bsonBinData).

neosqlite.collection.type_utils._convert_to_regex(value: Any) → Any

Convert value to regex pattern.

neosqlite.collection.type_utils._convert_to_bsonregex(value: Any) → Any

Convert value to regex pattern (bsonRegex).

neosqlite.collection.type_utils._convert_to_date(value: Any) → Any

Convert value to date (returns as-is; proper conversion requires parsing).

neosqlite.collection.type_utils._convert_to_null(value: Any) → None

Convert any value to None.

neosqlite.collection.type_utils.get_bson_type(value: Any) → str

Get BSON type name for a value.

Parameters:

value – The value to check

Returns:

BSON type name (e.g., ‘null’, ‘bool’, ‘int’, ‘double’, ‘string’, ‘array’, ‘object’)

neosqlite.collection.type_utils._is_expression(value: Any) → bool

Check if value is an aggregation expression.

An expression is a dict with exactly one key starting with ‘$’ that is not a reserved field name.

Parameters:

value – Value to check

Returns:

True if value is an expression, False otherwise

Examples

>>> _is_expression({"$sin": "$angle"})
True
>>> _is_expression({"$field": "value"})  # Reserved
False
>>> _is_expression("$field")
False
>>> _is_expression(42)
False

neosqlite.collection.type_utils._is_field_reference(value: Any) → bool

Check if value is a field reference.

Field references start with ‘$’ but are not expressions (i.e., they’re simple strings like “$field” or “$nested.field”).

Parameters:

value – Value to check

Returns:

True if value is a field reference, False otherwise

Examples

>>> _is_field_reference("$field")
True
>>> _is_field_reference("$nested.field")
True
>>> _is_field_reference("$$ROOT")
False
>>> _is_field_reference({"$sin": "$angle"})
False

neosqlite.collection.type_utils._is_literal(value: Any) → bool

Check if value is a literal (not an expression or field reference).

Literals include: numbers, strings, booleans, None, arrays, and plain dicts.

Parameters:

value – Value to check

Returns:

True if value is a literal, False otherwise

Examples

>>> _is_literal(42)
True
>>> _is_literal("string")
True
>>> _is_literal(True)
True
>>> _is_literal(None)
True
>>> _is_literal([1, 2, 3])
True
>>> _is_literal("$field")
False

neosqlite.collection.type_utils._is_numeric_value(value: Any) → bool

Check if a value is numeric (int or float) or can be converted to a numeric value.

This function determines if a value can be safely used in arithmetic operations like $inc and $mul. It considers: - int and float values as numeric (excluding bool, NaN, and infinity) - None as non-numeric (would cause issues in arithmetic) - String representations of numbers as non-numeric (to match MongoDB behavior)

Parameters:

value – The value to check

Returns:

True if the value is numeric, False otherwise

Return type:

bool

neosqlite.collection.type_utils.validate_session(session: Any | None, connection: Any) → None

Validate that the session belongs to this connection.

Parameters:

• session – ClientSession instance or None

• connection – The parent Connection or sqlite3.Connection object to validate against

Raises:

ValueError – If the session belongs to a different connection