omni-json-db: A Three-LESS (Schema-LESS + Server-LESS + SQL-LESS) High-Performance Database.

Provides rapid JSON and MsgPack serialization with robust concurrency controls for many-read single-write multithreading/multiprocessing environments.

class omni_json_db.JDb(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Bases: JDbReader

Main Database controller managing reading, writing, transaction rollbacks, and multi-part data compaction pipelines.

Ensures data consistency under high concurrent load using fine-grained file-level system locking primitives.

__delitem__(key)[source]

Physically drop or unlink selected record entries spaces from database index tracking registries.

Parameters:

key (Union[str, Any]) –

Unique entry character label token text descriptor, query filter conditional lambda function, regex sequence pattern, or subset iterable sequence.

str | int | float | bool | bytes
```
>>> del jdb['name']
```

Condition

>>> user = Query()
>>> del jdb[user.age >= 40]

slice | date | datetime

>>> del jdb[1:10:2]
>>> del jdb[-10.:]
>>> del jdb[:]
>>> del jdb[dt.date(2020,1,1)::r'key[0-9]']
>>> del jdb[:100:r'key[0-9]']
>>> del jdb[date(2020,1,1)]
>>> del jdb[datetime(2020,1,1)]

function(k,v)

>>> del jdb[lambda k,v: k.startswith('key')]
>>> del jdb[lambda k,v: v == 10] = val

function(k)
```
>>> del jdb[lambda k: k[0] == 'k']
```
re.Pattern
```
>>> del jdb[re.compile(r'key[0-9]')]
```

tuple | set | list | dict

>>> del jdb['a', 'b', 'c', 'd']
>>> del jdb[('a', 'b', 'c', 'd')]
>>> del jdb[{'a', 'b', 'c', 'd'}]
>>> del jdb[['a', 'b', 'c', 'd']]
>>> del jdb[{'a':0, 'b':1, 'c':2, 'd':3}]

Raises:

TypeError – If lookups evaluation candidates strike unrecognizable parameter types rules boundaries models.

Example

>>> del jdb[:] # delete all records
>>> del jdb['name']
>>> del jdb[lambda k,v: k.startswith('temp_')]

__iadd__(records)[source]

Batch load elements dictionaries mapping records directly in-place rewriting overlapping values lines.

Parameters:

records (Dict[str, Any]) –

Collection mapping identifiers to target value instances or iterable primitives arrays.

JDbReader
```
>>> jdb += other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb += {'a':1, 'b':2}
```

tuple | set | list == List[Any] == (val1, val2, ..)

>>> jdb += {'a', 'b'} # jdb.update_vals({'a', 'b'})
>>> jdb += ('a', 'b') # jdb.update_vals(('a', 'b'))
>>> jdb += ['a', 'b'] # jdb.update_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb += 'name' # jdb['name'] = None
```

Returns:

Self repository context manager interface handle reference.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb += {'new_key': 99}

__iand__(records)[source]

Batch update or override known elements row values data rows avoiding adding unknown outliers into index layers maps.

Parameters:

records (Dict[str, Any]) –

Translation adjustments dictionary mapping context models fields.

JDbReader
```
>>> jdb &= other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb &= {'a':1, 'b':2}
```

tuple | set | list == Tuple[Any] == (val1, val2, ..)

>>> jdb &= {'a', 'b'} # jdb.replace_vals({'a', 'b'})
>>> jdb &= ('a', 'b') # jdb.replace_vals(('a', 'b'))
>>> jdb &= ['a', 'b'] # jdb.replace_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb &= 'name' # jdb['name'] = None
```

Returns:

Self database environment framework instance configuration wrapper.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb &= {'key1': 99}
>>> jdb['key1']
99

__init__(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Initialize the transactional JDb controller object mapping configurations sheets models.

Parameters:

KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None], optional) –
File path, memory buffer, or network host.
- None | bytearray
  - JMemFiles() or JMemFiles(bytearray)
- str
  - ’’ = use JMemFiles() in memory
  - ’127.0.0.1:8001’ = use JNetFiles((‘127.0.0.1’, 8001))
  - ’database/test.jdb’ = use JDiskFiles(database/test.jdb)
- JDbReader = use JDb.files_obj
- JMemFiles | JNetFiles | JDiskFiles
data_type (Union[str, int, None], optional) –
Serialization format
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Compression algorithm to use.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
key_limit (Union[str, int, None], optional) –
Key table limitation constraint.
- ”no” = use DictKeyTable. (default).
- ”bt” = use BTreeKeyTable.
- ”l0”-“l5” = use LiteKeyTable.
- +ve: use PartialKeyTable.
cache_limit (int, optional) –
In-memory object cache limit.
- -1 = unlimited cache.
- 0 = no cache. (default)
- +ve = with cache.
max_file_size (Optional[int], optional) – Max size of a single data part.
min_value_size (Optional[int], optional) – Minimum byte size for value padding.
index_size (Optional[int], optional) – Fixed byte size for the key index records.
reserved_rate (Optional[float], optional) – Expansion buffer rate for data rows.
api_ver (Optional[int], optional) –
API structural version limit.
- 0 = oldest version.
- None = latest version. (default)
write_hook (Optional[Callable[[str, Any], bool]], optional) – Callback triggered before writing.
max_wsize (Optional[int], optional) – Search window for dead lines. Defaults to 4.
flags (Optional[JFlag], optional) – Enum flags for modifying revert/split behavior.
**kwargs – Extra arguments passed to internal components.

Raises:

TypeError – Raised if provided arguments are of the incorrect type.

Example

>>> jdb = JDb() # in-memory mode
>>> jdb = JDb('192.168.0.1:8181') # Network mode
>>> jdb = JDb('file.jdb') # file mode
>>> jdb = JDb('example.jdb', data_type='J+J', zip_type='gz')

__ior__(records)[source]

Batch insert unallocated entities matrices structures arrays in-place strictly bypassing existing nodes bounds.

Parameters:

records (Dict[str, Any]) –

Target context source map entries.

JDbReader
```
>>> jdb |= other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb |= {'a':1, 'b':2}
```

tuple | set | list == List[Any] == (val1, val2, ..)

>>> jdb |= {'a', 'b'} # jdb.insert_vals({'a', 'b'})
>>> jdb |= ('a', 'b') # jdb.insert_vals(('a', 'b'))
>>> jdb |= ['a', 'b'] # jdb.insert_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb |= 'name' # jdb['name'] = None
```

Returns:

Self proxy repository interface controller instance framework.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb |= {'new_key': 99}

__isub__(keys)[source]

Batch remove outstanding entries index references using LIFO strategy blocks optimization.

Parameters:

keys (Set[str]) –

Target dataset collection maps array or sibling JDbReader source instance candidate.

JDbReader
```
>>> jdb -= other_jdb
```
str | int | float | bool | bytes
```
>>> jdb -= "name" # jdb -= {"name"}
```

tuple | set | list | dict

>>> jdb -= {'a'', 'b'', 'c', 'd'}
>>> jdb -= ('a'', 'b'', 'c', 'd')
>>> jdb -= ['a'', 'b'', 'c', 'd']
>>> jdb -= {'a':0, 'd':1, 'c':2, 'd':3}

Returns:

Self instance with specified nodes decoupled completely.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb -= {'key1', 'key2', 'key3'}

__ixor__(keys)[source]

Revert or roll back transaction shifts processing selected node indicators parameters history blocks fields.

Parameters:

keys (Set[str]) –

Target indicator strings mapping historical recovery boundaries paths.

JDbReader
```
>>> jdb ^= other_jdb
```
str | int | float | bool | bytes
```
>>> jdb ^= 'name'
```

dict | tuple | set | list

>>> jdb ^= {'a', 'b'}
>>> jdb ^= ('a', 'b')
>>> jdb ^= ['a', 'b']
>>> jdb ^= {'a':1, 'b':2} # == {'a', 'b}

Returns:

Self chronologically synchronized operational workspace manager proxy.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1'] = 1
>>> jdb['key1'] = 99
>>> jdb ^= {'key1'}
>>> jdb['key1']
1

__setitem__(key, val)[source]

Commit or modify entry content mapping values utilizing scalar indicators, regex arrays or functions parameters.

Parameters:

key (Union[str, Any]) –

Target database lookups selection token lookup identifier or filter schema block query criteria fields.

str | int | float | bool | bytes
```
>>> jdb['name'] = val
```

Condition

>>> User = Query()
>>> jdb[User.name == 'Alice'] = val

slice | date | datetime

>>> jdb[1:10:2] = val
>>> jdb[-10.:] = val
>>> jdb[:] = val
>>> jdb[date(2020,1,1)::r'key[0-9]'] = val
>>> jdb[:100:r'key[0-9]'] = val
>>> jdb[date(2020,1,1)] = val
>>> jdb[datetime(2020,1,1)] = val

function(k,v)

>>> jdb[lambda k,v: k.startswith('key') and v > 0] = val
>>> jdb[lambda k,v: v == 10] = val

function(k)
```
>>> jdb[lambda k: k[0] == 'k'] = val
```
re.Pattern
```
>>> jdb[re.compile(r'key[0-9]')] = val
```

tuple | set | list | dict

>>> jdb['a', 'b', 'c', 'd'] = val | func
>>> jdb[('a', 'b'', 'c', 'd')] = val | func
>>> jdb[{'a', 'b'', 'c', 'd'}] = val | func
>>> jdb[['a', 'b'', 'c', 'd']] = val | func
>>> jdb[{'a':0, 'b':1, 'c':2, 'd':3}] = val | func

val (Any) –

Payload value context or updating mutation callback functional lambda routine.

any type but function
```
>>> jdb['name'] = val
```

function(k,v)

>>> jdb['name'] = lambda k,v : v+1
>>> jdb['name'] = lambda k,v : v+1 if v is not None else None # replace if exist
>>> jdb['name'] = lambda k,v : v if v is not None else 1 # insert if not exist

Raises:

TypeError – If input validation layers discover corrupted lambda parameter signatures rules or mismatched data types.

Example

>>> jdb['name'] = 'Charlie'
>>> jdb[lambda k,v: v == 10] = 11
>>> jdb[1:10:2] = "updated"

add(records, default_val=None, replace=True, insert=True, is_list=False, flags=None, max_wsize=None)[source]

Core serialization writing gatekeeper pipeline routing entries insertions or value replacements into database tracks layers maps.

Parameters:

records (Dict[str, Any]) – Repository container processing elements candidates maps records fields text tokens variables.
default_val (Optional[Any], optional) – Fallback value mapping variables context assigned if source candidate parses abstract. Defaults to None.
replace (bool, optional) – Overwrite pre-existing records keys if lookups discover shared matching indicators indices parameters logs. Defaults to True.
insert (bool, optional) – Generate brand new data records lines spaces if target descriptors evaluate absent from index pools. Defaults to True.
is_list (bool, optional) – Toggle switch adapting input types tracking sequences listing vs dictionaries tracking key-value parameters. Defaults to False.
flags (Optional[JFlag], optional) – strategic behavioral modifiers. Defaults to None.
max_wsize (Optional[int], optional) – Scan scope lookahead density limit constraining dead rows tracking checks loops fields. Defaults to None.

Returns:

Descriptive dictionary summary array tracking all successfully committed modified entries fields log data metrics records fields.

Return type:

Dict[str, Any]

Raises:

TypeError – If input validation candicates structures break system framework specifications classes.

add_group(key)[source]

Initialize an isolated nested cluster sub-database partition workspace domain.

Parameters:: key (str) – Subfolder tracking name selector token text string.
Returns:: The newly constructed partition node interface.
Return type:: JDb
Raises:: KeyError – If incoming cluster nomenclature violates basic string character constraints.

append(records, **kwargs)[source]

Batch append continuous sequence datasets mapping rows values content segments parts blocks anonymously utilizing sequence numbers as descriptors labels markers arrays sheets.

Parameters:

records (List[Any]) – Array container processing distinct values entries configurations records fields metrics.
**kwargs – Strategic flags variables modifiers parameters context settings blocks layers maps tracks systems.

Returns:

Generated mapping fields matching identity codes tokens integers sequences keys to individual saved objects data lines.

Return type:

Dict[str, Any]

backup(folder=None, data_type=None, zip_type=None, fast_mode=True, **kwargs)[source]

Clone structural matrix database state tracking sheets records fields exporting backups profiles to targeted destination folders clusters.

Parameters:

folder (Optional[str], optional) – Target system descriptor path code string identifier template context. Defaults to None.
data_type (Union[str, int, None], optional) –
Override layout specifications format setting selection index. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Override snapshot baseline row compression properties values limits rules. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
fast_mode (bool, optional) – Accelerate copy algorithms utilizing binary segment streams maps mirroring rules. Defaults to True.
**kwargs – Extra attributes routed down seamlessly to child construction factories.

Returns:

Initialized destination replica workspace proxy connection interface object.

Return type:

JDb

Example

>>> jdb = JDb('example.jdb', data_type='J+M', zip_type='gz')
>>> jdb += {f'key{v}':list(range(v)) for v in range(100)}
>>> bak_jdb = jdb.backup(folder='bak', data_type='S+S', zip_type='br')
>>> print(bak_jdb.date_type, bak_jdb.zip_type)
S+S br

change_KEY(KEY_type, api_ver=None)[source]

Transcode indexing layouts formats blueprint rules rewriting master entry trackers parameters configurations.

Parameters:

KEY_type (str) – Format encoding specification classification string token text (‘J’, ‘L’, ‘M’, ‘S’).
api_ver (Optional[int], optional) – Physical logical standard implementation layout version index number. Defaults to None.

Returns:

True if structure transposition completes altering the master file, False otherwise.

Return type:

bool

Raises:

ValueError – If target codes evaluate out of structural ranges definitions thresholds.

Example

>>> jdb = JDb(date_type='J+J')
>>> jdb.change_KEY('S')
>>> print(jdb.data_type)
S+J

check_error(parent='', level=0, fix_it=False, verbose=True)[source]

Validate logical structure integrity scan index layers maps checking anomalies corruptions cross-referencing files parameters indicators metrics models.

Parameters:

parent (str, optional) – Hierarchy node namespace trace tracking origin references variables tokens. Defaults to ‘’.
level (int, optional) – Deepness limitation parameter capping child database recursion lookahead cycles. Defaults to 0.
fix_it (bool, optional) – Trigger dynamic reconstruction algorithms rewriting mismatching structures headers rows templates objects. Defaults to False.
verbose (bool, optional) – Enable terminal diagnostics print traces mapping structural verification flows metrics grids windows panels fields fields logs. Defaults to True.

Returns:

Registry tracing all identified data alignment failures associated against internal sequence identifiers numbers lines.

Return type:

dict

chg_keys: Set

childs: Dict[str, JDbReader]

clear(agree='no', wait_sec=10, **kwargs)[source]

Obliterate data registries resetting storage files templates entirely to an empty layout framework.

Parameters:

agree (str, optional) – Validation security phrase. Must equal strictly string token ‘yes’ to proceed. Defaults to ‘no’.
wait_sec (int, optional) – Counting delay buffer allowing developers to abort using Ctrl-C indicators. Defaults to 10.
**kwargs – Extra settings overrides configuring properties mapped onto the fresh structural sheets.

Returns:

True if destruction and reallocation finalize properly, False otherwise.

Return type:

bool

clone_to(target, signal='.', fast_mode=True, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, data_type=None, zip_type=None, cache_limit=0, api_ver=None, **kwargs)[source]

Clone data mapping layouts structures templates from self source environment into target destination storage configurations drivers arrays frames.

Parameters:

target (Union[JDb, JFilesBase, str]) – Target storage manager engine wrapper, location token path text format layout selector string, or absolute instance proxy context.
signal (str, optional) – Heartbeat monitoring output string token mapped onto runtime console loops indicators text. Defaults to ‘.’.
fast_mode (bool, optional) – Engage raw binary stream optimization mechanics bypassing transcoders pipelines loops if schemas align uniformly. Defaults to True.
max_file_size (Optional[int], optional) – Custom destination storage capacity parameter setting data file segment bounds. Defaults to None.
min_value_size (Optional[int], optional) – Minimum alignment floor width constraint bounding row expansion buffers tracks. Defaults to None.
index_size (Optional[int], optional) – Fixed byte width defining destination row padding boundaries constraints markers fields. Defaults to None.
reserved_rate (Optional[float], optional) – Cushion expansion multiplier allocated across target workspace segments fields. Defaults to None.
data_type (Union[str, int, None], optional) –
Format coding classification token specifying serialization configurations layout schemas. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Targeted compression algorithm code token selection settings options values. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
cache_limit (int, optional) – Memory limitation constraint variables values bounding destination cache lookup objects registry. Defaults to 0.
api_ver (Optional[int], optional) – Logical logical operational standard blueprint standard iteration version identifier. Defaults to None.
**kwargs – Extra settings overrides routed down seamlessly onto compilation factory pipelines matrices.

Returns:

The initialized populated target destination session environment workspace model context.

Return type:

JDb

Raises:

TypeError – If input target elements candidates fail driver framework integration matching expectations rules profiles metrics tracks.

create_jdb(KEY_file)[source]

Spawn a child read-write companion database instance mimicking host properties models parameters grids.

Parameters:: KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None]) – File path or core buffer source stream.
Returns:: A relative fresh JDb session workspace environment instance.
Return type:: JDb

del_group(key)[source]

Exterminate a nested sub-database cluster namespace dropping structural tracking indicators permanently.

Parameters:: key (str) – Sub-space lookup target selector token text string.
Returns:: The destroyed group instance handle if successfully cleared, None fallback otherwise.
Return type:: Optional[JDb]

f_change_days(fp_dict, key, days=-1)[source]

Modify the timestamp of a specific Key at the low level without changing the data content.

Parameters:

fp_dict (Dict[int, IO]) – The file descriptor set for the current thread.
key (str) – The name of the target key.
days (Union[int, float, str, dt_date, datetime], optional) – The number of days, time object, or string representation of the date to be written. Defaults to -1.

Returns:

Returns True if the write is successful; returns False if it fails or the Key is not found.

Return type:

bool

f_delete(fp_dict, key, read_value=True, row=None, flags=None)[source]

Low-level pipeline method: physically unlink a specified entity, compact index arrays, and manage transaction rollbacks.

Parameters:

fp_dict (Dict[int, IO]) – Open file pointers maps repository.
key (str) – Unique entry identification lookup code label string.
read_value (bool, optional) – Unpack and return original data contents before discarding tracking pointers. Defaults to True.
row (Optional[int], optional) – Precise allocation row block offset index to bypass search indices. Defaults to None.
flags (Optional[JFlag], optional) – strategic behavioral modifiers flags. Defaults to None.

Returns:

The unlinked python value payload object, or group workspace if targeted entity maps a nested sub-database.

Return type:

Any

f_get_child(fp_dict, name)[source]

Low level routing factory resolving child detached storage pipelines inside current streams boundaries maps trackers.

Parameters:

fp_dict (Dict[int, IO]) – Active file pointers registration collection maps table.
name (str) – Named item node partition token text descriptor selector.

Returns:

Open operational child dataset workspace reference, or None if validation fails.

Return type:

Optional[JDb]

f_get_write_fp(fp_dict)[source]

Acquire and configure exclusive writing streams access permissions channels context maps matrices metrics.

Parameters:: fp_dict (Dict[int, IO]) – Active file handler dictionary tracking metrics variables configuration parameters.
Returns:: Consolidated processing context payload group returning core matrix, file map registers, main descriptor pointer, and timeline shift synchronization flag state.
Return type:: Tuple[JIo, Dict[int, IO], IO, bool]
Raises:: RuntimeError – If multi-threaded file locks context cannot initialize isolation guards blocks parameters thresholds numbers.

f_rename(fp_dict, key, new_key)[source]

Low-level pipeline method: alter unique index reference tokens text strings mapping keys metadata blocks layout configurations.

Parameters:

fp_dict (Dict[int, IO]) – Active file handler matrix registration array mapping pools handles.
key (str) – Existing unique query selector name token label string format context fields fields.
new_key (str) – Newly requested target character string identification indicator code text.

Returns:

True if identity name properties switch successfully inside tracking registers, False otherwise.

Return type:

bool

Raises:

KeyError – If destination identifier string token collides against pre-allocated records fields data layers.

f_undelete(fp_dict, key, row=None, flags=None)[source]

Low-level pipeline method: resurrect dropped or unlinked indices descriptors variables from dead logs sectors.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active handles arrays tables registers.
key (str) – Missing identifier text selector string to target and recover.
row (Optional[int], optional) – Precise hardware target slot alignment position index to bypass lookup cycles loops. Defaults to None.
flags (Optional[JFlag], optional) – strategic modifiers flags. Defaults to None.

Returns:

Core allocation parameters metadata tuple summarizing recovered slot parameters if successful, None otherwise.

Return type:

Optional[Tuple[int,int,int,int,int]]

f_unwrite(fp_dict, key, row=None, flags=None)[source]

Low-level pipeline method: roll back dynamic record modifications shifting indices properties maps back to legacy content points maps.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active system registers stream descriptor collections.
key (str) – Unique dictionary descriptive name string token format selector query fields.
row (Optional[int], optional) – Target layout position index bounding search rows loops. Defaults to None.
flags (Optional[JFlag], optional) – strategic modifiers behavioral flags. Defaults to None.

Returns:

Execution parameters logging adjusted item metrics parameters integers if successful, None otherwise.

Return type:

Optional[Tuple[int,int,int,int,int]]

f_write(fp_dict, key, val, days=-1, flags=None, max_wsize=None, compare=True)[source]

Low-level pipeline method: serialize, compress, and record dynamic Python value entries mapping into target filesystem tracks safely.

Parameters:

fp_dict (Dict[int, IO]) – Open file handles tracking collections metrics maps.
key (str) – Destination dictionary descriptor reference character token text string layout context.
val (Any) – Payload instance content python object structure to serialize.
days (int, optional) – Calendar modification timing tracking parameter representation number. Defaults to -1.
flags (Optional[JFlag], optional) – strategic behavioral modifiers flags. Defaults to None.
max_wsize (Optional[int], optional) – Maximum search lookahead steps window constraint index number. Defaults to None.
compare (bool, optional) – compare old value and new value before writing it. Defaults to True

Returns:

True if serialization persistence completes smoothly, False if transaction logic drops inputs.

Return type:

bool

Raises:

TypeError – If interceptor write hooks reject incoming inputs configuration candidate attributes.

f_write_bytes(fp_dict, key, val, days=-1, flags=None, max_wsize=None)[source]

Low-level pipeline method: directly commit raw un-serialized binary byte blocks into physical content sectors tracks.

Parameters:

fp_dict (Dict[int, IO]) – Current thread transactional context opens registries handles maps.
key (str) – Unique data record pointer lookup name token layout string.
val (bytes) – Raw uncompressed payload byte configuration data chunk array.
days (int, optional) – Compact timeline relative days counter index selection number. Defaults to -1.
flags (Optional[JFlag], optional) – Custom modifier bitflags overrides. Defaults to None.
max_wsize (Optional[int], optional) – Maximum search lookahead steps window constraint index number. Defaults to None.

Returns:

True if binary persistence pipelines execute smoothly, False fallback otherwise.

Return type:

bool

file_lock: FileLock

files_obj: JFilesBase

flags: JFlag

fp_table: Dict[int, dict]

from_csv(csv_file, key=None, flags=None, max_wsize=None, **kwargs)[source]

Import structured CSV text streams context sheets fields records translating tabular elements rows matrices back onto native database maps datasets collections.

Parameters:

csv_file (Union[str, IO]) – Source filesystem node address string path notation text or open stream descriptor channel container proxy.
key (Optional[str], optional) – Identity reference label indicating target unique row key column header text layout. Defaults to None.
flags (Optional[JFlag], optional) – strategic operational behavioral modifiers flags. Defaults to None.
max_wsize (Optional[int], optional) – Search window capacity constraint bounding dead structural entry lookahead scans width parameters. Defaults to None.
**kwargs – Extra parameters routed down seamlessly onto secondary underlying DictReader extraction components.

Returns:

Current context modified active database environment workspace proxy handle.

Return type:

JDb

from_ini(src)[source]

Parse configuration template sheets fields context records extracting variables settings structures from classic text INI files layout templates blocks rules.

Parameters:: src (Union[str, IO]) – Full target system text string path context layout parameters maps or active open file object stream interface pointer locator.
Returns:: Updated relational configuration workspace context handle.
Return type:: JDb

from_sqlite(src, batch_size=-1)[source]

Migrate SQLite transaction tables models matrices records mapping columns profiles straight into isolated nested database groups spaces partitions layers.

Parameters:

src (Union[str, Connection]) – Full database file system address string text path context layout parameters maps or active connection instance handle proxy.
batch_size (int, optional) – Iteration size constraint capping total rows fetched during single chunk cycles processes frames metrics. Defaults to -1.

Returns:

Updated relational engine state interface snapshot workspace.

Return type:

JDb

Raises:

TypeError – If input sources violate target standard database connection configurations criteria parameters properties fields.

from_toml(src)[source]

Parse TOML specification sheets structures arrays data profiles converting unified hierarchical trees structures documents models directly into record metrics paths context.

Parameters:: src (Union[str, IO]) – Target localization filename string path context blueprint text or open streaming object channel handle wrapper proxy.
Returns:: Updated dataset configurations management engine state.
Return type:: JDb
Raises:: ModuleNotFoundError – If the host runtime environment misses required third party parsing extensions framework dependencies libraries wrapper hooks.

fsize

insert(records, default_val=None, **kwargs)[source]

Batch write new elements parameters metrics ignoring existing records overlaps boundaries positions lines fields metrics logs maps.

Parameters:

records (Dict[str, Any]) – Core context source dictionary mapping indices properties fields.
default_val (Optional[Any], optional) – Fallback placeholder variable options parameters settings models. Defaults to None.
**kwargs – Extra transaction isolation modifiers parameters variables.

Returns:

Subset tracking entries successfully registered inside indices fields.

Return type:

Dict[str, Any]

insert_vals(records, **kwargs)[source]

Batch insert row value metrics collections anonymously into new entries indices slots.

Parameters:

records (List[Any]) – Sequence collection containing target entries values arrays fields indicators models tracks metrics.
**kwargs – Extra transactional parameter switches.

Returns:

Mapping catalog aligning sequence identities variables to generated records outputs.

Return type:

Dict[str, Any]

io: JIo

keys: JDbKey

lock

max_wsize: int

pop(key, default_val=None)[source]

Isolate, pop, and erase an individual item record from indices returning previous python object contents.

Parameters:

key (str) – Target dictionary lookup query choice token text string descriptor criteria.
default_val (Optional[Any], optional) – Fallback data assigned if lookup registers miss elements indicators. Defaults to None.

Returns:

Unpacked Python object value, or default_val if missing from storage tables.

Return type:

Any

Example

>>> previous_value = jdb.pop('key_to_remove', default_val=0)

recycle(parent='', level=0, merge=False, fill_zero=False, verbose=True)[source]

Purge unlinked dead storage slots rewriting physical indexes sheets to reclaim unallocated disk space footprints metrics.

Parameters:

parent (str, optional) – Hierarchy prefix namespace path denoting partition trees boundaries. Defaults to ‘’.
level (int, optional) – Recursion limitation deepness constraining nested children evaluation scopes paths rules. Defaults to 0.
merge (bool, optional) – Combine contiguous sparse gaps inside data segments layout storage files. Defaults to False.
fill_zero (bool, optional) – Overwrite unallocated physical tracks with structural zeroes vectors preventing leakage traces. Defaults to False.
verbose (bool, optional) – Enable terminal logging text parameters metrics visualization alerts. Defaults to True.

Example

>>> jdb.recycle(merge=False)

reinit(records, default_val=None, is_list=False, agree='no', wait_sec=10, **kwargs)[source]

Purge tracking maps drop active registers systematically rebuilding complete datasets layout configurations from scratch matching incoming records fields.

Parameters:

records (Dict[str, Any]) – Incoming context source matrix data candidates.
default_val (Optional[Any], optional) – Fallback variable context setting parameter assigned if structures evaluate blank. Defaults to None.
is_list (bool, optional) – Adjust entry evaluation tracks converting lists structures sequences anonymously vs mapping dictionaries keys fields text format. Defaults to False.
agree (str, optional) – Safeguard validation checkpoint rule phrase. Must equal strictly ‘yes’ to proceed. Defaults to ‘no’.
wait_sec (int, optional) – Interactive buffer countdown seconds threshold capping destruction loops parameters. Defaults to 10.
**kwargs – Extra attributes override keys passed down seamlessly to re-initialization routines.

Returns:

True if allocation routines commit the fresh structures records maps smoothly, False if checkpoint guards intercept execution paths tracks.

Return type:

bool

remove(*records)[source]

Batch decouple unlinking targeted index entry row selections extracting values payloads concurrently back onto general system pools.

Parameters:: *records (str) – Variadic references containing key strings tokens to systematically purge from active pools sheets.
Returns:: Dictionary mapping successfully deleted record elements strings identifiers back onto their contents maps arrays blocks.
Return type:: Dict[str, Any]

remove_fast(*records)[source]

Batch decouple index parameters keys ignoring payload decryption parsing stages optimizing deletion streams throughput processing speed metrics profiles.

Parameters:: *records (str) – Unique text identifier token references variadic selection arguments context layout parameters maps tracks systems layers.
Returns:: Registry containing successfully discarded items keys list mappings logs.
Return type:: Set[str]

rename(keys)[source]

Batch re-label items mapping old text identifier codes tokens parameters straight into new destination unique name strings indices.

Parameters:: keys (Dict[str, str]) – Translation target dictionary pairing former tags descriptors keys with freshly requested identifiers text.
Returns:: Catalog mapping all altered item names coordinates changes records fields logs properties context.
Return type:: Dict[str, str]
Raises:: TypeError – If input mapping elements fail standard structural collection constraints.

replace(records, default_val=None, **kwargs)[source]

Batch rewrite pre-existing record lines parameters properties fields metrics values profiles avoiding adding unknown outliers into index pools blocks.

Parameters:

records (Dict[str, Any]) – Target translation dictionary allocating adjustments details configurations rules models sheets text fields context layers frameworks grids.
default_val (Optional[Any], optional) – Fallback value. Defaults to None.
**kwargs – Extra execution runtime attributes.

Returns:

Replaced records data array tracking modified items coordinates parameters positions numbers blocks.

Return type:

Dict[str, Any]

replace_vals(records, **kwargs)[source]

Batch rewrite anonymous value elements sequences arrays avoiding appending unknown new index records lines.

Parameters:

records (List[Any]) – Input sequences collection mapping variables targets logs properties.
**kwargs – Extra hardware processing configuration overrides.

Returns:

Updated objects matrix maps summary results array tracking modified items.

Return type:

Dict[str, Any]

resize_index_size(index_size=0, extra_size=8, min_ver=True)[source]

Modify fixed tracking structural allocation padding bounding database row dimensions headers fields permanently.

Parameters:

index_size (int, optional) – Targeted byte allocation width constraint indicator. 0 forces dynamic scan configuration. Defaults to 0.
extra_size (int, optional) – Buffer allocation extension safety boundary width metrics. Defaults to 8.
min_ver (bool, optional) – Reset baseline synchronizations version markers indices. Defaults to True.

Returns:

Calculated final index padding dimension assigned across files structures.

Return type:

int

restore(folder='bak', fast_mode=True, **kwargs)[source]

Overwrite current repository layers tracking matrices components structures using elements matching chosen backup files templates.

Parameters:

folder (Union[str, JDb]) – File directory absolute lookup address string parameter or active source driver reader object workspace. Defaults to ‘bak’.
fast_mode (bool, optional) – Skip complex transposition steps if files properties mirror baseline configurations structures. Defaults to True.
**kwargs – Extra parameters routed forward seamlessly onto replication controllers.

Returns:

Current context active database session interface manager handle.

Return type:

JDb

Raises:

ValueError – If lookup coordinates target unallocated positions boundaries paths context lines.
TypeError – If input structural data candidate fails standard module validation checks.

Example

>>> jdb = JDb('example.jdb')
>>> jdb.restore(folder='bak')

revert(*records)[source]

Symmetrically execute recovery pipelines rolling back either variable values updates or item omissions based on history bounds logs.

Parameters:: *records (str) – Target text identifiers tracking variables contexts fields.
Returns:: Collection mapping keys fields onto recovery structural outcomes status codes.
Return type:: Dict[str, Any]

Example

>>> status = jdb.revert('target_key_1', 'target_key_2')

safe_line

set(key, val, flags=None, max_wsize=None)[source]

Write single entry content maps configuring transaction modifiers rules indices tracks.

Parameters:

key (str) –
Target unique key lookup choice token identifier text string.
- str
```
>>> jdb[ke)] = val
```
- int | float | bool
```
>>> jdb[str(key)] = val
```

val (Any) –

Scalar object layout payload or conditional update callback lambda routine context.

any type but function
```
>>> jdb['name'] = val
```

function(k,v)

>>> jdb['name'] = lambda k,v : v+1
>>> jdb['name'] = lambda k,v : v+1 if v is not None else None # replace if exist
>>> jdb['name'] = lambda k,v : v if v is not None else 1 # insert if not exist

flags (Optional[JFlag], optional) –
strategic behavioral modifiers. Defaults to None.
- REVERT = allow to revert
- SPLIT = allow to split largest row size to two
max_wsize (Optional[int], optional) –
Maximum search scope bounding lookahead sweeps across dead lines elements. Defaults to None.
- None = use default max_wsize (4)
- -ve = disable searching

Returns:

The committed data payload if changes successfully execute, old value context otherwise.

Return type:

Optional[Any]

Raises:

TypeError – If input candidate argument structures fail validation tests specifications models.

set_days(key, days)[source]

Modify tracking calendar timestamps elapsed days values logs stored within entry index parameters coordinates.

Parameters:

key (str) – Target descriptor lookups selection token lookup string classification label context.
days (Union[int, float, str, dt_date, datetime]) –
Timeline offset integer, calendar object instance, or formatted date text code.
- int : days since 1-1-1
```
>>> jdb.set_days('key', 1)
```
- str : ‘YYYY-MM-DD’ or ‘YYYY-MM-DD YYYY-MM-DD’
```
>>> jdb.set_days('key', "2000-01-01")
>>> jdb.set_days('key', "2000-01-01 2001-12-31")
```
- date | datetime
```
>>> jdb.set_days('key', date(2000, 1, 1))
>>> jdb.set_days('key', datetime(2000, 1, 1))
```
- float : timestamp

Returns:

True if modification markers indices write successfully, False fallback if errors strike connections.

Return type:

bool

set_n(records, default_val=None, replace=True, insert=True, **kwargs)[source]

Batch commit key-value collections mapping records into active database frames indexes lanes.

Parameters:

records (Dict[str, Any]) – Inputs target mapping records collections datasets.
default_val (Optional[Any], optional) – Fallback value mapping variables context if entries lookups evaluate abstract. Defaults to None.
replace (bool, optional) – Rewrite existing data points if indexes discover overlapping indicators matches parameters. Defaults to True.
insert (bool, optional) – Initialize unknown outliers creating fresh structural slots sheets fields records lines. Defaults to True.
**kwargs – Extra parameters routed down directly into underlying translation execution engines factories.

Returns:

Changed objects log maps summary array tracing modified elements paths.

Return type:

Dict[str, Any]

Raises:

TypeError – If input candidate collection elements break schema constraints maps parameters.

setdefault(key, val)[source]

Initialize chosen lookup strings with default values if currently missing from the index registries.

Parameters:

key (str) – Target text reference indicator lookup query string token context.
val (Any) – Fallback object template payload context rules data fields variables.

th_table: Dict[int, int]

to_csv(csv_file, key=None, **kwargs)[source]

Export internal data frames records fields matrices structures logs straight into tabular structured CSV data formats sheets files documents models.

Parameters:

csv_file (Union[str, IO]) – Target filename string locator path or open streaming file-like interface stream descriptor handle context.
key (Optional[str], optional) – Custom field token labeling the principal identifier index row data columns fields layout. Defaults to None.
**kwargs – Extra formatting parameters routed directly onto inner DictWriter configuration profiles blueprints rules options fields.

Returns:

True if extraction workflows finish completely without errors metrics profiles, False fallback otherwise.

Return type:

bool

unmodify(*records)[source]

Undo dynamic value row mutations rolling records states back onto prior chronological signatures logs on file layer.

Parameters:: *records (str) – Variadic sequence choosing target keys or groups tracking indicators strings to restore.
Returns:: Mapping dictionary summarizing all successfully restored entities linked along previous positions data.
Return type:: Dict[str, Any]

Example

>>> recovered_info = jdb.unremove('accidental_delete_key')

unremove(*records)[source]

Resurrect dropped index tracking references pulling deleted outlier components back into live databases index pools blocks.

Parameters:: *records (str) – Unique identifier token strings matching targeted deleted records candidates tracking keys data.
Returns:: Execution summary index tracing resurrected targets aligned with recovered layouts coordinates parameters logs.
Return type:: Dict[str, Any]

update(records, default_val=None, **kwargs)[source]

Batch load elements dictionaries mapping records directly in-place rewriting overlapping lines fields metrics fields.

Parameters:

records (Dict[str, Any]) – Datasets records dictionary mapping collections lines tracks.
default_val (Optional[Any], optional) – Fallback parameter value context fields variables. Defaults to None.
**kwargs – Strategic execution modifier attributes passed smoothly onto translation processors factories frameworks wrappers.

Returns:

Catalog tracing successfully updated dataset items.

Return type:

Dict[str, Any]

update_if(condition, patch)[source]

Merge patch into every record (dict value) matching condition.

Parameters:

conditon (Condition | dict) – Condition for key/date/value filtering.
patch (dict | Callable[[str,Any],Dict[str,Any]]) – if condition is matched, update the corresponding value.

Returns:

the number of records updated.

Return type:

int

Example

>>> jdb.update_if(Query().age <= 32, {'age':18, 'active':True})
>>> jdb.update_if(Query().age <= 99, lambda k,v : {'age':v['age']+1, status:v['age']<40})

update_vals(records, **kwargs)[source]

Batch update or append anonymous values collections entries into database lanes maps.

Parameters:

records (List[Any]) – Input items sequences list container.
**kwargs – Strategic transaction properties context configuration rules parameters trackers handles.

Returns:

Generated identity key dictionary tracks tracking saved row models.

Return type:

Dict[str, Any]

upgrade(folder='bak', data_type=None, zip_type=None, fast_mode=True, **kwargs)[source]

Migrate database models records maps layouts transforming internal formats properties fields seamlessly via proxy nodes staging tracks.

Parameters:

folder (str, optional) – Target temporary folder location token. Defaults to ‘bak’.
data_type (Union[str, int, None], optional) –
Override serialization schema standard encoding format settings. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Override compression layout parameters criteria markers fields. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
fast_mode (bool, optional) – Skip extraction loop algorithms stages if transcoders align uniformly. Defaults to True.
**kwargs – Extra parameters passed straight to construction modules.

Returns:

Updated system interface reference workspace engine.

Return type:

JDb

write_hook: Callable[[str, Any], bool]

static z_dumps(data, ret_type=None)[source]

convert any data into Json/Marshal/Pickle/Msgpack/YAML format

Parameters:

data (Any) –
target Python data
- support str/bytes/int/float/bool/None/dict/list/set/tuple/JDb
ret_type (str, optional) –
return format
- ”J” = JSON format (default)
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

converted data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> dumps([1,2], 'J')
>>> dumps([1,2], 'M')
>>> dumps([1,2], 'P')
>>> dumps([1,2], 'S')
>>> dumps([1,2], 'Y')

static z_loads(data, ret_type='J')[source]

convert Json/Marshal/Pickle/Msgpack/YAML bytes into Python data

Parameters:

data (Any) – Json/Msgpack/Marshal/Pickle bytes
ret_type (str, optional) –
return format
- ”J” = JSON format
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

Python data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> loads(dumps([1,2], 'J'), 'J') # Output: [1,2]
>>> loads(dumps([1,2], 'M'), 'M') # Output: [1,2]
>>> loads(dumps([1,2], 'P'), 'P') # Output: [1,2]
>>> loads(dumps([1,2], 'S'), 'S') # Output: [1,2]
>>> loads(dumps([1,2], 'Y'), 'J') # Output: [1,2]

static z_upgrade_API(KEY_path)[source]

Upgrade an older version of the database to the latest API structural format.

This method reads the existing database schema, resizes the index structure if necessary, migrates all tracking properties and physical indices to match the specifications of API_LATEST, and overwrites the legacy header. It ensures backward compatibility for older .jdb files by re-encoding the storage pipelines.

Parameters:: KEY_path (Union[str, JDb]) – The file path string to the legacy database, or an already initialized JDb instance that requires upgrading.
Returns:: The fully upgraded database controller instance running on the newest API format.
Return type:: JDb
Raises:: TypeError – If the provided KEY_path cannot be resolved into a valid JDb instance, or if the current API version is missing/invalid.

Example

>>> from omni_json_db import JDb
>>> # Upgrade a legacy database file to the latest API
>>> upgraded_db = JDb.z_upgrade_API('db/legacy_data.jdb')
>>> print(upgraded_db.io.api_ver)

static z_upgrade_KEY_day(KEY_path)[source]

Upgrade and rectify the legacy timeline tracking format (days) inside the database index.

This migration method patches older date formats (specifically targeting pre-2000 epoch offsets) within the index registries. It sequentially scans all allocated rows, updates the timestamp metadata values directly via bitwise masks, and rewrites the file header safely.

Parameters:: KEY_path (Union[str, JDbReader]) – The absolute file path to the database, or an active JDb/JDbReader instance wrapper.
Returns:: The database controller instance with fully rectified timeline index matrices.
Return type:: JDb
Raises:: TypeError – If the input target cannot be instantiated or validated as a proper JDb environment.

Example

>>> from omni_json_db import JDb
>>> # Fix timeline metadata constraints for an older database
>>> fixed_db = JDb.z_upgrade_KEY_day('db/old_timestamps.jdb')

class omni_json_db.JDbReader(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Bases: JDbBase

Read-only base class for JDb operations.

Handles data retrieval, filtering, and caching logic without allowing data modification. Designed for safe, concurrent read operations.

KEY_fopen(read_only=True)[source]

Context manager explicitly for opening and accessing the KEY structure file safely.

Parameters:: read_only (bool, optional) – Access mode request. Defaults to True.
Yields:: IO – The file pointer for the KEY table storage.

__add__(keys)[source]

Return the union of current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to add.
Returns:: The resulting union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb + {'new_user'}
{'user_1', 'user_2', 'new_user'}

__and__(keys)[source]

Return the intersection of current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to intersect with.
Returns:: The intersection set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb & {'user_1', 'missing_user'}
{'user_1'}

__contains__(keys)[source]

Check if the current key table is a superset of the provided keys.

Parameters:: keys (str | Set[str] | Condition) – A set of keys to check.
Returns:: True if all provided keys exist in the database, False otherwise.
Return type:: bool

Example

>>> jdb = JDb()
>>> jdb['user_1', 'user_2', 'user_3'] = 0
>>> {'user_1', 'user_2'} in jdb
>>> 'user_1 in jdb
>>> Query().age > 999 in jdb

__del__()[source]: Destructor to ensure all internal file descriptors and locks are safely released upon garbage collection.

__eq__(jdb)[source]

Compare the current keys/dict with another collection or database.

Parameters:

jdb (Union[set, dict, JDbReader, JDbKey]) –

The target to compare against.

JDb | dict: compare KEYs and VALs
set: compare KEYs only

Returns:

True if the keys are identical, False otherwise.

Return type:

bool

Example

>>> jdb = JDb()
>>> jdb['user_1', 'user_2'] = 0
>>> jdb == {'user_1', 'user_2'}
True

__getitem__(key)[source]

Retrieve data by key or filter data dynamically.

Parameters:

key (Set[str]) –

The identifier or condition mapping to locate specific values.

str | int | float | bool | bytes
>>> val = jdb['name']

Condition

>>> user = Query()
>>> data = jdb[user.name == 'Alice']

slice | date | datetime

>>> data = jdb[1:10:2]
>>> data = jdb[-10.:]
>>> data = jdb[:]
>>> data = jdb[dt.date(2020,1,1)::r'key[0-9]']
>>> data = jdb[:100:r'key[0-9]']

function(k,v)

>>> data = jdb[lambda k,v: k.startswith('key')]
>>> data = jdb[lambda k,v: v == 10]

function(k)
>>> data = jdb[lambda k: k[0] == 'k']

tuple | se | list | dict

>>> data = jdb[1, 2, 3, 'a']
>>> data = jdb[(1, 2, 3, 'a')]
>>> data = jdb[{1, 2, 3, 'a'}]
>>> data = jdb[[1, 2, 3, 'a']]
>>> data = jdb[{1:0, 2:1, 3:2, 'a':3}]

Returns:

The target value, or a dictionary of matched keys and values.

dict: mutliple keys with value

Any: target key’s value

Return type:

Union[Dict[str, Any], Any]

__init__(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Initialize the JDbReader instance with specific backend storage and formatting options.

Parameters:

KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None], optional) –
File path, memory buffer, or network host.
- None | bytearray
  - JMemFiles() or JMemFiles(bytearray)
- str
  - ’’ = use JMemFiles() in memory
  - ’127.0.0.1:8001’ = use JNetFiles((‘127.0.0.1’, 8001))
  - ’database/test.jdb’ = use JDiskFiles(database/test.jdb)
- JDbReader = use JDb.files_obj
- JMemFiles | JNetFiles | JDiskFiles
data_type (Union[str, int, None], optional) –
Serialization format
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Compression algorithm to use.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
key_limit (Union[str, int, None], optional) –
Key table limitation constraint.
- ”no” = use DictKeyTable. (default).
- ”bt” = use BTreeKeyTable.
- ”l0”-“l5” = use LiteKeyTable.
- +ve: use PartialKeyTable.
cache_limit (int, optional) –
In-memory object cache limit.
- -1 = unlimited cache.
- 0 = no cache. (default)
- +ve = with cache.
max_file_size (Optional[int], optional) – Max size of a single data part.
min_value_size (Optional[int], optional) – Minimum byte size for value padding.
index_size (Optional[int], optional) – Fixed byte size for the key index records.
reserved_rate (Optional[float], optional) – Expansion buffer rate for data rows.
api_ver (Optional[int], optional) –
API structural version limit.
- 0 = oldest version.
- None = latest version. (default)
write_hook (Optional[Callable[[str, Any], bool]], optional) – Callback triggered before writing.
max_wsize (Optional[int], optional) – Search window for dead lines. Defaults to 4.
flags (Optional[JFlag], optional) – Enum flags for modifying revert/split behavior.
**kwargs – Extra arguments passed to internal components.

Raises:

TypeError – Raised if provided arguments are of the incorrect type.

__iter__()[source]

Iterate over the keys present in the database.

Yields:: str – A database key.

__len__()[source]

Get the current number of valid records in the database.

Returns:: Total record count.
Return type:: int

__or__(keys)[source]

Return the union of current keys and the provided set using the bitwise OR operator.

Parameters:: keys (Set[str]) – The keys to unify.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb | {'new_user'}
{'user_1', 'user_2', 'new_user'}

__radd__(keys)[source]

Right-side addition (union) operation.

Parameters:: keys (Set[str]) – The set to add.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'new_user'} + jdb
{'user_1', 'user_2', 'new_user'}

__rand__(keys)[source]

Right-side bitwise AND (intersection) operation.

Parameters:: keys (Set[str]) – The set to intersect.
Returns:: The intersection set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'missing_user'} & jdb
{'user_1'}

__repr__()[source]

Return the string representation showing core parameters of the JDbReader instance.

Returns:: Descriptive text about the DB instance state and pointers.
Return type:: str

__ror__(keys)[source]

Right-side bitwise OR (union) operation.

Parameters:: keys (Set[str]) – The set to unify.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'new_user'} | jdb
{'user_1', 'user_2', 'new_user'}

__rsub__(keys)[source]

Right-side subtraction (difference) operation.

Parameters:: keys (Set[str]) – The baseline set.
Returns:: Elements in the given set but not in the database.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'new_user'} - jdb
{'new_user'}

__rxor__(keys)[source]

Right-side bitwise XOR (symmetric difference) operation.

Parameters:: keys (Set[str]) – The set to compare.
Returns:: The symmetric difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'new_user'} ^ jdb
{'user_2', 'new_user'}

__sub__(keys)[source]

Return the difference between current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to subtract.
Returns:: The resulting difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {f'user_{v+1}':v for v in range(3)}
>>> jdb - {'user_1'}
{'user_2', 'user_3'}

__xor__(keys)[source]

Return the symmetric difference between current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to compare.
Returns:: The symmetric difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb ^ {'user_1', 'new_user'}
{'user_2', 'new_user'}

property api_ver: int

Get the physical structural schema iteration version of the engine binary interface.

Returns:: Underlying logical structural iteration identification value.
Return type:: int

property cache_limit: int

Get the maximum number of items allowed in the read cache.

Returns:: The cache limit (0 implies off, -1 implies unlimited).
Return type:: int

can_lock()[source]

Validate if the storage medium filesystem architecture supports isolation parameters control.

Returns:: True if locks can be safely managed, False otherwise.
Return type:: bool

check_row(row_id=0, with_value=False)[source]

Inspect item layout metadata configurations across specific segment slots boundaries positions.

Parameters:

row_id (int, optional) – Target alignment index position integer. Defaults to 0.
with_value (bool, optional) – Load true content alongside structural layout configurations metrics. Defaults to False.

Returns:

Tuple containing binary allocation mapping profiles parameters or None.

Return type:

Optional[tuple]

check_status(keys)[source]

Evaluate status delta trackers processing system divergence tags across active entries collections.

Parameters:: keys (dict) – Target mapping assigning reference variables tokens to distinct version baseline thresholds.
Returns:: Dictionary associating identifiers with state change indicators (e.g., ‘+’, ‘-’, ‘!’).
Return type:: Dict[str, Tuple[str, int]]

check_version(version, max_version=None, with_value=False)[source]

Query modifications records parameters isolated within variable version sequence ranges markers.

Parameters:

version (int) – Floor execution sequence baseline constraint number.
max_version (Optional[int], optional) – Cutoff ceiling phase identifier number index. Defaults to None.
with_value (bool, optional) – Decouple data arrays forcing real row data content parsing execution. Defaults to False.

Returns:

Historical mapping records subset data.

Return type:

dict

chg_keys: Set

childs: Dict[str, JDbReader]

create_jdb(KEY_file)[source]

Spawn a relative reader instance sharing configuration models matching local presets.

Parameters:: KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None]) – Direct target path or source buffer.
Returns:: A newly spawned reader environment reference.
Return type:: JDbReader

property data_type: str

Get the format encoding specification string token representing the engine layout.

Returns:: Operational data schema classification code string (e.g., ‘J+S’).
Return type:: str

difference(keys)[source]

Exclude entries from native collection sets which match entries provided in inputs parameters.

Parameters:: keys (Set[str]) – Elements to strip away from internal arrays indices.
Returns:: Filtered difference array output.
Return type:: Set[str]

property dir_name: str

Get the parent directory path of the primary DB file.

Returns:: Directory path.
Return type:: str

f_close()[source]: Flush pending changes and systematically decouple file streams handles registers.

f_find_keys(fp_dict, pattern, **kwargs)[source]

Filter record namespaces utilizing regex compilation routines inside storage descriptor environments.

Parameters:

fp_dict (Dict[int, IO]) – Collection tracking active system streams pointers.
pattern (Union[str, Pattern]) – String token or compiled pattern layout blueprint matching queries.

Returns:

Filtered collection array tracking matching variables.

Return type:

Set[str]

f_get_child(fp_dict, name)[source]

Assemble child dataset references by evaluating storage descriptor arrays fields.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active registers tables.
name (str) – Selector token string matching underlying index rows data layers.

Returns:

Disconnected instance context or None.

Return type:

Optional[JDbReader]

f_get_fp(fp_dict)[source]

Resolve environment processing configuration mappings matching active isolation boundaries records.

Parameters:: fp_dict (Optional[Dict[int, IO]]) – Current session file pointer register collection array map or None.
Returns:: Primary processing engine engine block, register mappings, and master stream handles context.
Return type:: Tuple[JIo, Dict[int, IO], IO]

f_get_group(fp_dict, key)[source]

Extract partition headers from stream context buffers generating group space profiles models.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active handles arrays pool mapping current thread.
key (str) – Unique sub-space path allocation label selector string.

Returns:

Context bound group instance or None.

Return type:

Optional[JDbReader]

f_get_val_fp(fp_dict, file_id=None, req_size=None, max_fp=32)[source]

Manage active record segment storage files limiting concurrent hardware descriptive blocks allocation density.

Parameters:

fp_dict (Dict[int, IO]) – Active file handler matrix registration array mappings table.
file_id (Optional[int], optional) – Target segment classification index code identifier. Defaults to None.
req_size (Optional[int], optional) – request new file size
max_fp (int, optional) – System density boundary constraining total allocated storage streams descriptors. Defaults to 64.

Returns:

Target segment file stream controller instance, active section block index, and current capacity offset tracker.

Return type:

Tuple[IO, int, int]

f_key_iter(fp, slice_obj)[source]

Iterate over keys and their corresponding information.

Parameters:

fp_dict (Dict[int, IO]) – Active file handler matrix registration array mappings table.
slice_obj (Union[slice, dt_date, datetime, Condition]]) – slice object

Returns:

key, (row_id, file_id, offset, row_size, val_size, version, days, created_date, modified_date)

Return type:

Generator[str, tuple]

f_load_keys(fp_dict, force=False)[source]

Populate transactional key tables by evaluating raw data blocks tracking structures logs.

Parameters:

fp_dict (Dict[int, IO]) – Open file pointers collections tracking variables.
force (bool, optional) – Overrule native consistency timestamps forcing full stream reconstruction. Defaults to False.

f_open(read_only=True)[source]

Explicitly initialize and acquire transaction streams allocated to internal pools.

Parameters:: read_only (bool, optional) – If True, grabs shared reading channels. Otherwise requests exclusive system control flags. Defaults to True.
Returns:: Table tracking open IO objects bound to current thread session.
Return type:: Dict[int, IO]

f_read(fp_dict, key, default_val=None, row=None, copy=True)[source]

Low-level internal function to extract and deserialize a single data row via file pointers.

Parameters:

fp_dict (Dict[int, IO]) – Dictionary holding active open files.
key (Optional[str]) – The target key string.
default_val (Optional[Any], optional) – Fallback if missing. Defaults to None.
row (Optional[int], optional) – Precise row integer to skip indexing. Defaults to None.
copy (bool, optional) – Ensure safety by returning a deepcopy. Defaults to True.

Returns:

Deserialized object.

Return type:

Any

f_read_bytes(fp_dict, key)[source]

Extract compressed raw row values segments records bypassing standard engine factory loading steps.

Parameters:

fp_dict (Dict[int, IO]) – Current workspace active file descriptors map.
key (str) – Lookup selection parameter string identifier.

Returns:

Compressed or raw unparsed payload binary segment array block.

Return type:

bytes

f_read_row(fp_dict, row_id, with_value=False)[source]

Low level data chunk stream parsing factory isolating specific physical slot blocks parameters.

Parameters:

fp_dict (Dict[int, IO]) – Active file pointer table session.
row_id (int) – Hardware data sector alignment index value.
with_value (bool, optional) – Engage serialization routines unpacking real row contents blocks. Defaults to False.

Returns:

Segment tracking array schema mapping allocation boundaries metrics or None.

Return type:

Optional[tuple]

f_read_status(fp_dict, key, ver)[source]

Compare operational transactional signatures identifying delta indicators across historical timelines.

Parameters:

fp_dict (Dict[int, IO]) – Transaction registers maps array handles pool.
key (str) – Target reference lookup indicator selection token string.
ver (int) – Base reference comparison epoch phase index constraint value.

Returns:

Operational structural status code mapping paired with active transaction number index.

Return type:

Tuple[str, int]

f_read_version(fp_dict, version, max_version=None, with_value=False)[source]

Extract history lines and records bounded by version (sync/swap) IDs.

Parameters:

fp_dict (Dict[int, IO]) – Active file pointers.
version (int) – The starting threshold version.
max_version (Optional[int], optional) – The capping threshold version. Defaults to None.
with_value (bool, optional) – Whether to also extract the true value into the returned array. Defaults to False.

Returns:

A map of row-ID to a list containing metadata elements.

Return type:

Dict[str, list]

f_read_with_bytes(fp_dict, key)[source]

read value with unzip bytes

Parameters:

fp_dict (Optional, Dict[int, IO]) –
- None = use current thread
key (str) – read key from database

Returns:

key’s data and key’s unzip bytes

Return type:

Tuple[Any, bytes]

f_slice(fp_dict, key)[source]

Compute row and version iteration boundaries for a given slice or datetime constraint.

Parameters:

fp_dict (dict) – Active file pointer dictionary.
key (Union[dt_date, datetime, Condition, slice]) – The time or slice specification for filtering.

Returns:

A tuple containing (slice_obj, max_ver, min_ver, max_date, min_date, key_rules, chk_new_date).

Return type:

tuple

file_lock: FileLock

property file_name: str

Get the file name of the primary DB KEY file.

Returns:: File name.
Return type:: str

property file_table: Dict[int, int]

Get the internal file mapping metadata database table.

Returns:: A dictionary mapping file segment IDs to current offsets.
Return type:: Dict[int, int]

files_obj: JFilesBase

find(keys=None, vals=None, date=None, limit=0, skip=0, sort=0, with_value=None, stats=None, **kwargs)[source]

Find and return a dictionary of records matching complex query criteria.

Parameters:

keys (Optional[Any], optional) – Condition for key filtering.
vals (Optional[Dict[str, Any]], optional) – Condition for value filtering using operators.
date (Optional[Any], optional) – Date filters.
limit (int, optional) – Maximum item cap. Defaults to 0.
skip (int, optional) – skip number of matched records, Defaults to 0.
sort (int, optional) – Sorting direction (1 for ascending, -1 for descending, 0 for unsorted). Defaults to 0.
with_value (Optional[bool], optional) – Whether to read the key’s value. Defaults to False.
stats (Dict[str,float], optional) – statistic: loops, records, matched, key.filter, date.filter, value.filter, used_s

Returns:

The subset of matched data.

Return type:

Dict[str, Any]

find_iter(keys=None, vals=None, date=None, limit=0, skip=0, with_value=False, with_date=False, stats=None, **kwargs)[source]

Iterate over the database records yielding key-value pairs matching complex query criteria.

Parameters:

keys (Optional[Any], optional) –

Pattern, function, or string key matches.

>>> jdb.find(re.compile(r'Jo(e|hn)')) == jdb.find(r'Jo(e|hn)')
>>> jdb.find(lambda k: k[-1] == 'n')
>>> fdb.find({'$sw:': 'Jo'})

vals (Optional[Dict[str, Any]], optional) –

Dictionary of value constraint operators (e.g., {‘$gt’: 10}).

>>> jdb.find(GT=12) == dict(jdb.find_iter(vals={'$gt':12})) # value > 12
>>> jdb.find(GTE=12) == dict(jdb.find_iter(vals={'$gte':12})) # value >= 12
>>> jdb.find(GE=12) == dict(jdb.find_iter(vals={'$ge':12})) # value >= 12
>>> jdb.find(LT=12) == dict(jdb.find_iter(vals={'$lt':12})) # value < 12
>>> jdb.find(LTE=12) == dict(jdb.find_iter(vals={'$lte':12})) # value <= 12
>>> jdb.find(LE=12) == dict(jdb.find_iter(vals={'$le':12})) # value <= 12
>>> jdb.find(EQ=12) == dict(jdb.find_iter(vals={'$eq':12})) # value == 12
>>> jdb.find(NE=12) == dict(jdb.find_iter(vals={'$ne':12})) # value != 12
>>> jdb.find(NE=12) == dict(jdb.find_iter(vals={'!$eq':12})) # value != 12
>>> jdb.find(EQ='Joe') == dict(jdb.find_iter(vals={'$eq':'Joe'})) # value == "Joe"
>>> jdb.find(NE='Joe') == dict(jdb.find_iter(vals={'$ne':'Joe'})) # value != "Joe"
>>> jdb.find(RE=r'Jo(hn|e)') == dict(jdb.find_iter(vals={'$re':'Jo(hn|e)'})) # re.search(r'Jo(hn|e)', value)
>>> jdb.find(HAS=12) == dict(jdb.find_iter(vals={'$has':12})) # 12 in value
>>> jdb.find(IN=[1,2]) == dict(jdb.find_iter(vals={'$in':[1,2]})) # value in [1,2]
>>> jdb.find(NIN=[1,2]) == dict(jdb.find_iter(vals={'$nin':[1,2]})) # value not in [1,2]
>>> jdb.find(NIN=[1,2]) == dict(jdb.find_iter(vals={'$!in':[1,2]})) # value not in [1,2]
>>> jdb.find(FUNC=lambda k,v: v == 1) == dict(jdb.find_iter(vals={'$func':lambda k,v: v == 1}))
>>> jdb.find(AND=[{'name':'A'}, {'age':{'$gte':20}}]) # value['name'] == 'A' and value['age'] >= 20
>>> jdb.find(OR=[{'name':'A'}, {'age':{'$ge':20}}]) # value['name'] == 'A' or value['age'] >= 20
>>> jdb.find(NOR=[{'name':'A'}, {'age':{'$gte':20}}]) # value['name'] != 'A' and value['age'] < 20
>>> jdb.find(NOT={'name':'A'}}]) # not value['name] == 'A'
>>> jdb.find(ANY='A')  # any record's value equal to  'A'
>>> jdb.find(vals={'name.$has': 'ice'})
>>> jdb.find(vals={'!name.$ihas': 'ice'})
>>> jdb.find(vals={'tags.0': ['db', 'c++']})
>>> jdb.find(vals={'country.city': ['US', 'UK']})
>>> jdb.find(vals={'c*t*y.c*y': ['US', 'UK']})

date (Optional[Any], optional) –
Timeline constraint for record modifications.
```
>>> jdb.find(date={'$ne': date(2011,1)})
```
limit (int, optional) – Max results to return. 0 means unlimited. Defaults to 0.
skip (int, optional) – skip number of matched records, Defaults to 0.
with_value (bool, optional) – Whether to decode and return the actual value, or just None. Defaults to False.
with_date (bool, optional) – Whether to return the actual value + created date + modified date Defaults to False.
stats (Dict[str,float], optional) – statistic: loops, records, matched, key.filter, date.filter, value.filter, used_s
**kwargs – Extra filter configurations (e.g., regex flags).

Yields:

Tuple[str, Any] – Matching key and its associated value (or None if with_value is False).

Example

>>> jdb.find_iter(vals={'$eq': "value"})
>>> jdb.find_iter(EQ="value")
>>> jdb.find_iter(vals={'$in': ["value1", "value2"]})
>>> jdb.find_iter(IN=["value1", "value2"])
>>> jdb.find_iter(NIN=["value1", "value2"])
>>> jdb.find_iter(vals={'$func': lamdba value:value == "any"})
>>> jdb.find_iter(FUNC=lambda value:value == "any")
>>> jdb.find_iter(FUNC=lambda key,val:val == "any")
>>> jdb.find_iter(r'^[Rr].*[Nn]$', IN=[8,27])
>>> jdb.find_iter(r'^[Rr].*[Nn]$', NIN=[8,27])
>>> jdb.find_iter(keys=[r'^[Rr]', r'[Nn]$'], vals={'$in' : [8, 27]})
>>> jdb.find_iter(keys=[r'^[Rr]', r'[Nn]$'], vals={'$gt' : 8, '$lt' : 100})
>>> jdb.find_iter(keys=[r'^[Rr]', r'[Nn]$'], vals={'$or' : {'$eq' : 8, '$lt' : 50}})
>>> jdb.find_iter(vals={'name' : r'Jo(e|hn)'})
>>> jdb.find_iter(ANY='name')
>>> jdb.find_iter(vals={'$any' : r'name'})
>>> jdb.find_iter(vals={'$any' : {'$re' : r'name'}})
>>> jdb.find_iter(vals={'$or': [{'name1':{'$eq':'value1'}, {'name2':{'$eq':'value2'}}])
>>> jdb.find_iter(OR=[{'name1':{'$eq':'value1'}, {'name2':{'$eq':'value2'}}])
>>> jdb.find_iter(NOR=[{'name1':{'$eq':'value1'}, {'name2':{'$eq':'value2'}}])
>>> jdb.find_iter(vals={'$and': [{'age':{'$gt':0}, {'age':{'$lte':100}}])
>>> jdb.find_iter(AND=[{'age':{'$gt':0}, {'age':{'$lte':100}}]) # 100 >= age >= 0
>>> jdb.find_iter(vals={'$not: {'$eq':'value1'})
>>> jdb.find_iter(NOT={'$eq':'value1'}) # find_iter(NE='value1')
>>> jdb.find_iter(EXISTS='role')
>>> jdb.find_iter(vals={'name.$has': 'ice'})      # $has as query operator
>>> jdb.find_iter(vals={'name. $has': 'ice'})     # ' $has' as a literal dict key

flags: JFlag

fp_table: Dict[int, dict]

fsize

get(key, default_val=None, copy=True)[source]

Safely fetch a value for a specific key, returning a default if not found.

Parameters:

key (str) – The target key.
default_val (Any, optional) – Value to return upon missing key. Defaults to None.
copy (bool, optional) – Retrieve a deep copy to prevent mutation. Defaults to True.

Returns:

The stored value or the default value.

Return type:

Any

get_all(cache_only=False)[source]

Retrieve the entirety of the database content into a single dictionary.

Parameters:: cache_only (bool, optional) – If True, only load what fits in the predefined cache_limit. Defaults to False.
Returns:: A full snapshot of the database.
Return type:: Dict[str, Any]

get_bytes(key)[source]

Extract the raw, compressed binary payload of a stored value without deserializing it.

Parameters:: key (str) – The key mapping to the payload.
Returns:: Raw binary block. Returns empty bytes if the key is not found.
Return type:: bytes

get_cache(key, default_val=None, copy=False)[source]

Attempt to retrieve the value from memory cache first, minimizing disk I/O.

Parameters:

key (str) – The target key.
default_val (Any, optional) – Fallback value. Defaults to None.
copy (bool, optional) – Return a deep copy. Defaults to False.

Returns:

The resolved data.

Return type:

Any

get_child(name)[source]

Resolve specific detached child storage database elements indexed under active mappings names.

Parameters:: name (str) – Named partition token directory target selector.
Returns:: Initialized isolated reader interface or None if file records break.
Return type:: Optional[JDbReader]

get_group(key)[source]

Isolate nested dataset directories initializing separate partitions spaces bound to distinct data keys.

Parameters:: key (str) – Selector name defining sub-database namespace boundaries.
Returns:: Active partition workspace or None if allocation rules break.
Return type:: Optional[JDbReader]

get_n(*records)[source]

Retrieve multiple keys simultaneously and pack them into a dictionary.

Parameters:: *records (str) – Variable arguments representing the keys to fetch.
Returns:: A mapping of the requested keys to their values.
Return type:: Dict[str, Any]

has(key)[source]

Check if a specific key exists in the database.

Parameters:: key (str) – The key to locate.
Returns:: True if the key exists, False otherwise.
Return type:: bool

has_(key)[source]

Check key presence strictly within local fast lookup caches avoiding heavy execution locks.

Parameters:: key (str) – Target dictionary lookup query string.
Returns:: True if active memory cache recognizes item reference, False otherwise.
Return type:: bool

has_all(keys)[source]

Check if all keys from the provided set exist in the database.

Parameters:: keys (Set[str]) – The keys to search for.
Returns:: True if all keys match, False otherwise.
Return type:: bool

has_any(keys)[source]

Check if at least one key from the provided set exists in the database.

Parameters:: keys (Set[str]) – The keys to search for.
Returns:: True if any key matches, False otherwise.
Return type:: bool

property index_size: int

Get the allocated storage byte size of an individual index block row.

Returns:: Number of fixed allocation bytes per index.
Return type:: int

info(prefix='', key='')[source]

Print formatted database statistics and configuration details to the console.

Parameters:

prefix (str, optional) – Indentation prefix string for nested groups. Defaults to ‘’.
key (str, optional) – Title or designated key name representing this branch. Defaults to ‘’.

intersection(keys)[source]

Intersect internal active index dictionary indices against query sequences fields.

Parameters:: keys (Set[str]) – Cross-reference set to check items matching domain rules.
Returns:: Shared element set output.
Return type:: Set[str]

io: JIo

is_disjoint(keys)[source]

Confirm if there are zero intersecting items common between tracking layers.

Parameters:: keys (Set[str]) – External evaluation frame array.
Returns:: True if overlap evaluates empty, False if items are shared.
Return type:: bool

is_latest()[source]

Verify absolute parity matching current application memory arrays states with filesystem indicators on disk.

Returns:: True if records mirror filesystem metrics perfectly, False if changes are pending.
Return type:: bool

is_subset(keys)[source]

Determine if local elements exist fully nested within a broader external pool space.

Parameters:: keys (Set[str]) – Broader parent context set.
Returns:: True if completely nested, False if any unique outlier is found.
Return type:: bool

is_superset(keys)[source]

Determine if every key inside an external collection exists in the local collection.

Parameters:: keys (Set[str]) – Target slice layout candidates to cross-verify.
Returns:: True if local structures envelope all values inside inputs, False otherwise.
Return type:: bool

item_iter(key=None)[source]

Iterate entities across datasets utilizing customizable indexing, criteria lambdas or slices parameters.

Parameters:

key (Optional[Any], optional) –

Query target constraint layer rule. Defaults to None.

re.Pattern
function(k) | function(k,v)
str: record name
int: record index
float: records sync ID
bytes | bytearray | bool
slice | date | datetime
list | tuple | set | dict

Yields:

Generator[str, Any] – (key, Value)

items(read_only=True)[source]

Generate structured key-value maps pairs extracted from indices tables.

Parameters:: read_only (bool, optional) – Engage shared serialization pipes logic optimization. Defaults to True.
Yields:: Tuple[str, Any] – A structural tuple pair associating key name strings with content values.

joint(keys)[source]

Find overlapping keys existing symmetrically between database space and criteria sets.

Parameters:: keys (Set[str]) – Query tracking indicators set.
Returns:: Intersected structural keys slice.
Return type:: Set[str]

property key_limit: str

Get the operational threshold rule limiting active reference cache structures.

Returns:: Tracking limits context operational string code.
Return type:: str

property key_table: Dict[str, int]

Access the loaded dictionary mapping keys to their exact line row numbers.

Returns:: Key table map.
Return type:: Dict[str, int]

keys: JDbKey

len_()[source]

Extract the exact active record count by checking core filesystem headers directly.

Returns:: Number of live unique records verified on device layer.
Return type:: int

load_table(force=False)[source]

Synchronize primary tables records maps checking current physical descriptor files states signatures.

Parameters:: force (bool, optional) – Bypass transaction timeline validation checks forcing an absolute rebuild. Defaults to False.
Returns:: Synced key_table map paired with active file_table indices.
Return type:: Tuple[Dict[str, int], Dict[int, int]]

lock

map(map_func, keys=None, vals=None, date=None, sort=0, **kwargs)[source]

Apply a mapping function to the results of a query and return a list.

Parameters:

map_func (Callable[[str, Any], Any]) – The lambda or function to process (key, value) pairs.
keys (Optional[Any], optional) – Key criteria.
vals (Optional[Any], optional) – Value criteria.
date (Union[str, datetime, dt_date, int, None], optional) – Date criteria.
sort (int, optional) – Sort direction flag.
**kwargs – Extra find arguments.

Returns:

Transformed list of objects returned by map_func.

Return type:

list

max_wsize: int

property min_value_size: int

Get the minimum floor alignment constraint for data segment storage arrays.

Returns:: Minimal byte width allocation limit.
Return type:: int

property n_lines: int

Get the total row line count inside the structural index file.

Returns:: Total logical index rows, including dead and deleted entries.
Return type:: int

property n_records: int

Get the count of valid active records currently indexed.

Returns:: The total number of active keys.
Return type:: int

non_intersection(keys)[source]

Isolate nodes that evaluate unique to either target dataset boundaries.

Parameters:: keys (Set[str]) – Target comparison index space.
Returns:: Computed symmetric difference tracking array.
Return type:: Set[str]

non_joint(keys)[source]

Compute the relative difference containing items unique to this instance.

Parameters:: keys (Set[str]) – Comparison collection base criteria target.
Returns:: The resulting asymmetric difference subset array.
Return type:: Set[str]

open(read_only=True, no_raise=False)[source]

Context manager to acquire thread-safe read/write access to the database files.

Parameters:

read_only (bool, optional) – Request a shared read lock instead of an exclusive write lock. Defaults to True.
no_raise (bool, optional) – If True, suppresses exceptions and attempts to reset corrupted headers. Defaults to False.

Yields:

Dict[int, IO] – A dictionary of open file pointers mapped by their IDs.

property path: str

Get the full system path to the primary DB file.

Returns:: Absolute or relative file path.
Return type:: str

property remv_id: int

Get the total deletion count sequence identifier used for data tracking.

Returns:: Counter indicating total deleted element lines.
Return type:: int

property reserved_rate: int

Get the padding reserve multiplier allocated for runtime object drift expansion.

Returns:: Pre-allocation expansion reservation rate.
Return type:: float

safe_line

show(keys=None, vals=None, date=None, limit=50, skip=0, with_date=False, **kwargs)[source]

show matched key+value in table.

Parameters:

keys (Optional[Any], optional) – Condition for key filtering.
vals (Optional[Dict[str, Any]], optional) – Condition for value filtering using operators.
date (Optional[Any], optional) – Date filters.
limit (int, optional) – +ve matched item. 0=all matched items (default=50)
skip (int, optional) – skip number of matched records, Defaults to 0.

Return type:

Dict[str, Any]

Example

>>> jdb = JDb()
>>> jdb += {'apple': {'color':'red', 'qty':10}, 'banana':{'color':'yellow', 'qty':100, 'from':'Japan'}}
>>> matches = jdb.show(limit=0) # show all records
    +--------+--------+-----+-------+
    | _id    | color  | qty | from  |
    +--------+--------+-----+-------+
    | apple  | red    | 10  |       |
    | banana | yellow | 100 | Japan |
    +--------+--------+-----+-------+
>>> matches = jdb.show(limit=1)
    +--------+--------+-----+-------+
    | _id    | color  | qty | from  |
    +--------+--------+-----+-------+
    | apple  | red    | 10  |       |
    +--------+--------+-----+-------+
>>> matches = jdb.show(vals={'qty': {'$gt': 50}})
    +--------+--------+-----+-------+
    | _id    | color  | qty | from  |
    +--------+--------+-----+-------+
    | banana | yellow | 100 | Japan |
    +--------+--------+-----+-------+

property swap_id: int

Get the compact sequence reference ID utilized during index storage updates.

Returns:: Garbage collection lifecycle phase index tracker.
Return type:: int

symmetric_difference(keys)[source]

Standard alias routing directly onto the non_intersection layout method.

Parameters:: keys (Set[str]) – Target values mapping sets to isolate.
Returns:: Unique divergent components layout map.
Return type:: Set[str]

sync(force=False, with_child=False)[source]

Refresh configuration maps arrays state ensuring compatibility with concurrent system modifications.

Parameters:

force (bool, optional) – Obliterate internal state layouts prior to polling system state logs. Defaults to False.
with_child (bool, optional) – Cascades environment register purge rules downwards to inner instances. Defaults to False.

Returns:

The updated synchronization reference object instance.

Return type:

JDbReader

property sync_id: int

Get the master execution tracking generation version sequence signature.

Returns:: Current synchronization session sequence value number.
Return type:: int

th_table: Dict[int, int]

union(keys)[source]

Aggregate local tracking records together with external target collection frames.

Parameters:: keys (Set[str]) – Collection items to incorporate into query results.
Returns:: Complete combination matrix unique elements array.
Return type:: Set[str]

unsync(with_child=False)[source]

Flush and drop internal tracker registries resetting structures states to standard zero parameters.

Parameters:: with_child (bool, optional) – Cascades environment register purge rules downwards to inner instances. Defaults to False.
Returns:: Clean slate structural tracking instance.
Return type:: JDbReader

values()[source]

Generate object values decoded directly from sequential segments records data blocks.

Yields:: Any – The unpacked deserialized python object row mapping.

write_hook: Callable[[str, Any], bool]

property zip_type: str

Get the active algorithm code string indicating row-level compression profile rules.

Returns:: Compression blueprint nomenclature code string (e.g., ‘zs’, ‘no’).
Return type:: str

class omni_json_db.JDiskFiles(KEY_file)[source]

Bases: JFilesBase

Production file-system storage driver implementing physical disk storage.

Maps database operations and logical indexing directly to file nodes and segments on the local storage media.

KEY_date()[source]

Extract baseline system epoch unix registration modification timelines indices numbers from files metadata fields layers.

Returns:: Numerical sequence timestamp logging phase alteration points timelines historical shifts.
Return type:: int

KEY_file

KEY_open(mode='rb', buffering=-1, encoding=None, **kwargs)[source]

Acquire persistent transactional stream pointers connected to the core index file.

Parameters:

mode (str, optional) – Target operational mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – IO array sizing buffer limits. Defaults to -1.
encoding (str, optional) – Explicit character translation rules. Defaults to None.
**kwargs – Extra arguments passed down directly to native Python open().

Returns:

Active file stream connecting directly to the index dataset.

Return type:

IO

Raises:

FileNotFoundError – If a lookup fails encountering missing files across specified paths.

KEY_size()[source]

Extract baseline UNIX timestamp marking index file creation/modification.

Returns:: The integer timestamp log from the file system metadata.
Return type:: int

LCK_close()[source]: Disengage isolation streams and safely close the lock file descriptor.

LCK_file

LCK_fp: int | IO | None

LCK_remove()[source]: Purge system lock indicators physically from disk storage.

LCK_rlock(block=False)[source]

Secure a platform-safe shared reader lock blocking writers but enabling read parallelism.

Parameters:: block (bool, optional) – If True, block until the lock becomes available. If False, attempt non-blocking mode. Defaults to False.
Raises:: BlockingIOError – If an exclusive writer is currently active.

LCK_unlock()[source]: Relinquish secured filesystem concurrency locks.

LCK_wlock(block=False)[source]

Secure a platform-safe exclusive write barrier lock blocking parallel transactions.

Parameters:: block (bool, optional) – If True, block until the lock becomes available. If False, attempt non-blocking mode. Defaults to False.
Raises:: BlockingIOError – If existing active transactions (readers or writers) overlap.

VAL_exist(file_id=0)[source]

Validate if a specified value partition file exists on the physical disk.

Parameters:: file_id (int, optional) – Partition locator code integer. Defaults to 0.
Returns:: True if the file exists on the system.
Return type:: bool

VAL_file

VAL_open(file_id=0, mode='rb', buffering=0, encoding=None, **kwargs)[source]

Open a standard file stream for a specific value partition (VAL file).

Parameters:

file_id (int, optional) – The ID of the partition file to open. Defaults to 0.
mode (str, optional) – The file access mode (e.g., 'rb', 'ab'). Defaults to 'rb'.
buffering (int, optional) – Buffer size policy. Defaults to 0.
encoding (str, optional) – Character encoding (only applies to text modes). Defaults to None.
**kwargs – Extra parameters passed to the native Python open().

Returns:

An open file object pointing to the specific storage block file.

Return type:

IO

Raises:

FileNotFoundError – If a read mode targets a non-existent file segment.

VAL_remove(file_id=0)[source]

Delete a physical value partition file from the file system.

Parameters:: file_id (int, optional) – Targeted contents partition index. Defaults to 0.
Returns:: True if the node is successfully unlinked, False otherwise.
Return type:: bool

VAL_size(file_id=0)[source]

Calculate the size of the specific VAL file.

Parameters:: file_id (int, optional) – Partition locator code integer. Defaults to 0.
Returns:: The size in bytes, or -1 if the file does not exist.
Return type:: int

__eq__(obj)[source]

Evaluate if two disk drivers point to the same physical file.

Parameters:: obj (Any) – Candidate comparison storage manager instance.
Returns:: True if path coordinates precisely match.
Return type:: bool

__init__(KEY_file)[source]

Initialize a database management context pointing to real disk storage.

Parameters:

KEY_file (str) – The absolute or relative file path locating the primary database index.

Raises:

TypeError – If KEY_file is not a string.
ValueError – If KEY_file is empty or entirely whitespace.

__repr__()[source]

Generate string descriptions summarizing the active driver configuration.

Returns:: Identity properties presenting the target file layout.
Return type:: str

copy()[source]

Create a duplicate driver instance pointing to the exact same file target.

Returns:: Duplicate disk space storage driver context.
Return type:: JDiskFiles

create_group(name)[source]

Assemble an isolated disk subdirectory tree configured for a partition group.

Parameters:: name (str) – Cluster classification identity label.
Returns:: Dedicated subfolder disk management framework instance.
Return type:: JDiskFiles

dir_name

file_name

fsync(fd)[source]

Force the operating system to flush internal buffers to the physical disk.

Parameters:: fd (int) – Target open file descriptor.
Return type:: None

get_KEY()[source]

Extract the exact physical path to the core key index file.

Returns:: The system descriptor path string.
Return type:: str

get_folder()[source]

Extract the absolute workspace parent directory path.

Returns:: The target directory path.
Return type:: str

get_name()[source]

Extract the specific filename of the database.

Returns:: The base filename string.
Return type:: str

get_path(folder='')[source]

Assemble the absolute path locating the database file.

Parameters:: folder (str, optional) – An optional subdirectory to append. Defaults to ''.
Returns:: The resolved absolute system path.
Return type:: str

group_KEY_file

is_group(KEY_file, name)[source]

Cross-verify group naming structures ensuring correct namespace allocations.

Parameters:

KEY_file (str | JFilesBase) – The file node indicator path.
name (str) – Label matching targeted group workspace boundaries.

Returns:

True if criteria tests locate matching configurations.

Return type:

bool

exception omni_json_db.JError[source]: Bases: Exception

class omni_json_db.JFlag(value)[source]

Bases: IntFlag

Enumeration flag to control write/delete behavior in database operations.

REVERT = 1

SPLIT = 2

__str__()[source]

Return a string representation of the currently active flags.

Returns:: A string where each character represents an active flag’s initial (e.g., 'rs'), or '_' if inactive.
Return type:: str

exception omni_json_db.JKeyError[source]: Bases: JError, KeyError

class omni_json_db.JMemFiles(KEY_file=None, VAL_table=None, LCK_file=None, lock=None, cond=None, timestamp=None, name=None)[source]

Bases: JFilesBase

In-memory virtual filesystem backend for transient database operations.

Manages layout matrices and dataset segments entirely within RAM using mutable bytearrays, bypassing physical storage devices.

KEY_date()[source]

Get the UNIX timestamp of the memory instance creation.

Returns:: The integer timestamp.
Return type:: int

KEY_file

KEY_open(mode='rb', buffering=-1, **kwargs)[source]

Open a raw stream tracking the primary key index in memory.

Parameters:

mode (str, optional) – Operation modes (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Ignored. Defaults to -1.
**kwargs – Extra attributes.

Returns:

Virtual stream handler managing the master key bytearray.

Return type:

IO

Raises:

FileNotFoundError – If reading is attempted on an uninitialized context.

KEY_size()[source]

Calculate the total size of the key index buffer.

Returns:: The number of bytes tracking the main index.
Return type:: int

LCK_close()[source]: Placeholder system stream shutdown routine. Does nothing in memory mode.

LCK_file

LCK_remove()[source]: Reset concurrency tracker values, clearing the lock bytes structure.

LCK_rlock(block=False)[source]

Acquire a shared reader lock for the memory instance.

Allows multiple threads to read concurrently while blocking write threads.

Parameters:

block (bool, optional) – If True, wait until the lock is available. If False, raise immediately if a writer is active. Defaults to False.

Raises:

BlockingIOError – If an exclusive write lock is held by another thread.
RuntimeError – If the lock file has been marked as closed/removed.

LCK_unlock()[source]: Release session concurrency locks, returning access control to the pool.

LCK_wlock(block=False)[source]

Acquire an exclusive writer lock for the memory instance.

Prevents other threads from reading or writing while held.

Parameters:

block (bool, optional) – If True, wait until the lock is available. If False, raise immediately. Defaults to False.

Raises:

BlockingIOError – If active transaction records indicate overlapping activities.
RuntimeError – If the lock file has been marked as closed/removed.

VAL_exist(file_id=0)[source]

Check if a specific segment block exists in memory.

Parameters:: file_id (int, optional) – The partition ID. Defaults to 0.
Returns:: True if the byte block exists.
Return type:: bool

VAL_open(file_id=0, mode='rb', buffering=0, **kwargs)[source]

Initialize an in-memory file stream for a specific value block.

Parameters:

file_id (int, optional) – The ID of the partition to open. Defaults to 0.
mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Ignored for memory arrays. Defaults to 0.
**kwargs – Extra parameters (ignored).

Returns:

A JBytesIO wrapper for reading and writing memory arrays.

Return type:

IO

VAL_remove(file_id=0)[source]

Clear memory array elements unlinking selected partitions.

Parameters:: file_id (int, optional) – The ID of the partition to delete. Defaults to 0.
Returns:: True if successfully cleared, False if not found.
Return type:: bool

VAL_size(file_id=0)[source]

Calculate the size of a specific in-memory partition block.

Parameters:: file_id (int, optional) – The partition ID. Defaults to 0.
Returns:: The size in bytes, or -1 if the block does not exist.
Return type:: int

VAL_table

__eq__(obj)[source]

Check if two memory instances share the exact same underlying key buffer.

Parameters:: obj (Any) – Target entity evaluation candidate.
Returns:: True if both objects wrap the identical in-memory bytearray.
Return type:: bool

__init__(KEY_file=None, VAL_table=None, LCK_file=None, lock=None, cond=None, timestamp=None, name=None)[source]

Initialize a volatile in-memory storage manager.

Parameters:

KEY_file (bytearray, optional) – Buffer for index mapping. Defaults to a new bytearray.
VAL_table (dict, optional) – Dictionary tracking file_id to content bytearrays.
LCK_file (bytearray, optional) – Mutex tracker array. Defaults to a new bytearray.
lock (Lock, optional) – Primitive synchronization engine.
cond (Condition, optional) – Condition variable for blocking concurrency.
timestamp (float, optional) – Baseline creation timestamp.
name (str, optional) – The virtual file object name.

Raises:

TypeError – If input parameters do not match required native types.

__repr__()[source]

Generate a string representation of the memory file state.

Returns:: Diagnostic telemetry regarding memory allocations.
Return type:: str

cond

copy()[source]

Create a duplicate instance referencing the same memory buffers.

Returns:: A replicated virtual storage controller.
Return type:: JMemFiles

create_group(name)[source]

Create a child dataset partition in memory.

Parameters:: name (str) – The cluster group name.
Returns:: A new empty memory storage manager.
Return type:: JMemFiles

fsync(fd)[source]

Mock file synchronization. Does nothing in memory mode.

Parameters:: fd (int) – Target file descriptor.
Return type:: None

get_KEY()[source]

Get the primary identifier tag for this memory instance.

Returns:: A placeholder string starting with <MEM.
Return type:: str

get_folder()[source]

Get the parent directory path.

Returns:: Always an empty string '' in transient memory environments.
Return type:: str

get_name()[source]

Get the descriptive file signature.

Returns:: The memory signature string including the memory address.
Return type:: str

get_path(folder='')[source]

Resolve the path mapping for the file.

Parameters:: folder (str, optional) – Target layer customization. Defaults to ''.
Returns:: Always an empty string '' in transient memory environments.
Return type:: str

is_group(KEY_file, name)[source]

Validate if the layout keys resolve to a volatile partition context.

Parameters:

KEY_file (str | JFilesBase) – Allocation identifier.
name (str) – Label matching targeted group boundaries.

Returns:

True if the target is a memory group.

Return type:

bool

lock

name

timestamp

class omni_json_db.JNetFiles(address=('127.0.0.1', 59898))[source]

Bases: JFilesBase

Network proxy client implementing the JFilesBase filesystem driver.

Routes file system operations to a remote ThreadedTCPServer database instance.

KEY_date()[source]

Get the UNIX timestamp of the remote main index file modification.

Returns:

The epoch timestamp.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

KEY_open(mode='rb', buffering=-1, **kwargs)[source]

Open a network stream to read or write the remote main index (KEY) file.

Parameters:

mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Buffer allocation boundaries. Defaults to -1.
**kwargs – Extra parameters passed to the remote driver.

Returns:

A JNetIO stream controller object.

Return type:

IO

Raises:

IOError – If the network socket is disconnected.

KEY_size()[source]

Get the total byte size of the remote main index (KEY) file.

Returns:

The size in bytes.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

LCK_close()[source]: Safely close lock channels to prevent remote resource starvation.

LCK_remove()[source]

Delete the lock file physically from the remote server.

Raises:: RuntimeError – If the network socket is disconnected or fails.

LCK_rlock(block=False)[source]

Acquire a shared reader lock on the remote server.

Parameters:

block (bool, optional) – If True, block until acquired. Defaults to False.

Raises:

BlockingIOError – If an exclusive writer lock is currently active.
RuntimeError – If a general connection or internal state error occurs.

LCK_unlock()[source]

Release any held locks on the remote server.

Raises:

BlockingIOError – If the unlock command is rejected.
RuntimeError – If a general connection or internal state error occurs.

LCK_wlock(block=False)[source]

Acquire an exclusive writer lock on the remote server.

Parameters:

block (bool, optional) – If True, block until acquired. Defaults to False.

Raises:

BlockingIOError – If any lock (read or write) is currently active.
RuntimeError – If a general connection or internal state error occurs.

VAL_exist(file_id=0)[source]

Check if a specific value partition exists on the remote server.

Parameters:

file_id (int, optional) – The partition ID to check. Defaults to 0.

Returns:

True if the partition exists.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

VAL_open(file_id=0, mode='rb', buffering=0, **kwargs)[source]

Open a network stream to read or write a specific remote value partition.

Parameters:

file_id (int, optional) – The partition ID to open. Defaults to 0.
mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Buffer limits. Defaults to 0.
**kwargs – Extra parameters passed to the remote driver.

Returns:

A JNetIO stream controller object.

Return type:

IO

Raises:

IOError – If the network socket is disconnected.

VAL_remove(file_id=0)[source]

Delete a specific value partition file on the remote server.

Parameters:

file_id (int, optional) – The partition ID to remove. Defaults to 0.

Returns:

True if successfully deleted by the server.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

VAL_size(file_id=0)[source]

Get the byte size of a remote value partition.

Parameters:

file_id (int, optional) – The partition ID to measure. Defaults to 0.

Returns:

The size in bytes, or -1 if it does not exist.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

__del__()[source]: Disconnect the socket cleanly upon garbage collection.

__eq__(obj)[source]

Check if two network clients point to the same server address.

Parameters:: obj (Any) – The candidate client to compare.
Returns:: True if the server addresses match exactly.
Return type:: bool

__init__(address=('127.0.0.1', 59898))[source]

Initialize the network database client.

Parameters:: address (Tuple[str, int], optional) – A tuple containing the host IP and port. Defaults to ('127.0.0.1', 59898).
Raises:: RuntimeError – If the socket connection fails.

__repr__()[source]

Return a string representation of the network client configuration.

Return type:: str

copy()[source]

Create a duplicate client connected to the same server address.

Returns:: A new network connection context proxy.
Return type:: JNetFiles
Raises:: IOError – If the original socket is closed.

create_group(name)[source]

Attempt to spawn a child group over the network.

Parameters:

name (str) – The group namespace.

Raises:

RuntimeError – Always raised, as remote multi-group creation is disallowed.
IOError – If the network socket is disconnected.

Return type:

JFilesBase

fsync(fd)[source]

Force the remote server to write buffers to the physical disk.

Parameters:

fd (int) – Target file descriptor.

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote fsync command fails.

Return type:

None

get_KEY()[source]

Get the primary identifier path for the remote database index.

Returns:

The master key identifier from the remote server.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_folder()[source]

Get the parent directory path of the remote database.

Returns:

The absolute directory path on the remote machine.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_name()[source]

Get the specific filename of the remote database.

Returns:

The filename string from the remote server.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_path(folder='')[source]

Resolve the absolute physical path to the remote database.

Parameters:

folder (str, optional) – A subdirectory to append. Defaults to ''.

Returns:

The resolved absolute path on the remote machine.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

is_group(KEY_file, name)[source]

Validate if a path belongs to a named database group on the remote server.

Parameters:

KEY_file (str | JFilesBase) – The file node indicator path.
name (str) – Label matching targeted group workspace boundaries.

Returns:

True if the group validation succeeds on the server.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

server_addr

sock

exception omni_json_db.JTypeError[source]: Bases: JError, TypeError

exception omni_json_db.JValueError[source]: Bases: JError, ValueError

class omni_json_db.Query(_path='')[source]

Bases: object

A builder class for constructing MongoDB-style query dictionaries safely.

Provides a fluent, Pythonic interface to generate query filters using magic methods (==, >) and chained method calls.

Parameters:: _path (str, optional) – The initial path segment for the query. Defaults to ''.

Example

>>> q = Query()
>>> condition = (q.age > 18) & (q.name.startswith("Al"))
>>> print(condition)
Condition({'$and': [{'age': {'$gt': 18}}, {'name': {'$sw': 'Al'}}]})

__eq__(val)[source]

Build an equality condition (==).

Return type:: Condition

__ge__(val)[source]

Build a greater-than-or-equal condition (>=). Maps to $gte.

Return type:: Condition

__getattr__(name)[source]

Extend the query path using attribute access (e.g., q.user.name).

Return type:: Query

__getitem__(segment)[source]

Extend the query path using item access (e.g., q['user']['name']).

Return type:: Query

__gt__(val)[source]

Build a greater-than condition (>). Maps to $gt.

Return type:: Condition

__le__(val)[source]

Build a less-than-or-equal condition (<=). Maps to $lte.

Return type:: Condition

__lt__(val)[source]

Build a less-than condition (<). Maps to $lt.

Return type:: Condition

__ne__(val)[source]

Build a not-equal condition (!=). Maps to $ne.

Return type:: Condition

abs()[source]

Apply abs() in the path chain. Maps to $abs.

Return type:: Query

Example

>>> Query().delta.abs_() < 0.1
Condition({'delta.$abs': {'$lt': 0.1}})

any_in(col)[source]

Check if any element of the target iterable exists within the provided collection. Maps to $anyin.

Return type:: Condition

avg()[source]

Apply arithmetic mean in the path chain. Maps to $avg.

Returns None (no-match) for empty sequences.

Return type:: Query

Example

>>> Query().scores.avg().between(70, 90)
Condition({'scores.$avg': {'$between': (70, 90)}})

between(lo, hi)[source]

Check if the target value falls strictly between two bounds. Maps to $between.

Return type:: Condition

ceil()[source]

Return the ceiling of x as an Integral.

Return type:: Query

Example

>>> Query().price.ceil() == 10
Condition({'price.$ceil': {'$eq': 10}})

endswith(suffix)[source]

Check if the target string ends with the given suffix. Maps to $ew.

Return type:: Condition

exists(fields)[source]

Check if the specified keys/fields exist in the target dictionary. Maps to $exists.

Return type:: Condition

first()[source]

Extracts the first item or character** before comparing. Maps to $first.

Return type:: Query

flat()[source]

Flattens a nested iterable before comparing. Maps to $flat.

Return type:: Query

float()[source]

Convert a number or string to an floating point.

Return type:: Query

Example

>>> Query().price.float() == 99.9
Condition({'price.$float': {'$eq': 99.9}})

floor()[source]

Return the floor of x as an Integral.

Return type:: Query

Example

>>> Query().price.floor() == 10
Condition({'price.$floor': {'$eq': 10}})

fullmatch(pattern, flags=0)[source]

Check if the target string perfectly matches a regex pattern. Maps to $match.

Return type:: Condition

has(val)[source]

Check if the target string or collection contains the value. Maps to $has.

Return type:: Condition

ihas(val)[source]

Check if the target string contains the value (case-insensitive). Maps to $ihas.

Return type:: Condition

int()[source]

Convert a number or string to an integer.

Return type:: Query

Example

>>> Query().price.int() == 99
Condition({'price.$int': {'$eq': 99}})

last()[source]

Extracts the last item or character** before comparing. Maps to $last.

Return type:: Query

len()[source]

Apply len() in the path chain. Maps to $len.

Works on str, list, tuple, dict, set, bytes.

Return type:: Query

Example

>>> Query().tags.len_() >= 3
Condition({'tags.$len': {'$gte': 3}})

lower()[source]

Apply str.lower() in the path chain. Maps to $lower.

Return type:: Query

Example

>>> Query().name.lower().has('alice')
Condition({'name.$lower': {'$has': 'alice'}})

matches(pattern, flags=0)[source]

Check if the target string contains a regex pattern match. Maps to $re.

Return type:: Condition

max()[source]

Apply max() in the path chain. Maps to $max.

Return type:: Query

Example

>>> Query().scores.max_() == 100
Condition({'scores.$max': {'$eq': 100}})

mid()[source]

Return the middle element/character in the path chain. Maps to $mid.

Uses index len(val) // 2. Works on list, tuple, str, bytes.

Return type:: Query

Example

>>> Query().tags.mid() == 'python'
Condition({'tags.$mid': {'$eq': 'python'}})

min()[source]

Apply min() in the path chain. Maps to $min.

Applicable to non-string iterables (list, tuple, set).

Return type:: Query

Example

>>> Query().scores.min_() >= 60
Condition({'scores.$min': {'$gte': 60}})

mod(div, rem)[source]

Check if the target value divided by div leaves a remainder of rem. Maps to $mod.

Return type:: Condition

near(target, tol)[source]

Check if the target value is within a specified tolerance of a number. Maps to $near.

Return type:: Condition

neg()[source]

Convert a number or string to an negative integer.

Return type:: Query

Example

>>> Query().price.neg() == -99
Condition({'price.$neg': {'$eq': -99}})

not_has(val)[source]

Check if the target string or collection does not contain the value. Maps to $nhas.

Return type:: Condition

not_in(collection)[source]

Check if the target value does not exist within the provided collection. Maps to $nin.

Return type:: Condition

one_of(collection)[source]

Check if the target value exists within the provided collection. Maps to $in.

Return type:: Condition

round()[source]

Round a number to a given precision in decimal digits.

Return type:: Query

Example

>>> Query().price.round() == 10
Condition({'price.$round': {'$eq': 10}})

size_of(size)[source]

Check if the length of the target collection matches the given size. Maps to $size.

Return type:: Condition

sort()[source]

Sort the iterable values before comparing. Maps to $sort.

Return type:: Query

startswith(prefix)[source]

Check if the target string starts with the given prefix. Maps to $sw.

Return type:: Condition

std()[source]

Apply population standard deviation in the path chain. Maps to $std.

Uses population std-dev (divides by n). Returns 0.0 for single-element sequences and None for empty ones.

Return type:: Query

Example

>>> Query().readings.std() < 2.0
Condition({'readings.$std': {'$lt': 2.0}})

str()[source]

Convert scalar to string

Return type:: Query

Example

>>> Query().price.str() == "99.9"
Condition({'price.$str': {'$eq': 99.9}})

strip()[source]

Apply str.strip() in the path chain. Maps to $strip.

Return type:: Query

sum()[source]

Apply sum() in the path chain. Maps to $sum.

Works on str, list, tuple, dict, set, bytes.

Return type:: Query

Example

>>> Query().tags.sum() == 3
Condition({'tags.$sum': 3})

test(func)[source]

Evaluate the target using a custom callback function. Maps to $func.

Return type:: Condition

type_of(_type)[source]

Check if the target value matches a specific data type. Maps to $type.

Return type:: Condition

unique()[source]

Performs order-preserving deduplication on an iterable before comparing. Maps to $unique.

Return type:: Query

upper()[source]

Apply str.upper() in the path chain. Maps to $upper.

Return type:: Query

omni_json_db.dumps(data, ret_type=None)

convert any data into Json/Marshal/Pickle/Msgpack/YAML format

Parameters:

data (Any) –
target Python data
- support str/bytes/int/float/bool/None/dict/list/set/tuple/JDb
ret_type (str, optional) –
return format
- ”J” = JSON format (default)
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

converted data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> dumps([1,2], 'J')
>>> dumps([1,2], 'M')
>>> dumps([1,2], 'P')
>>> dumps([1,2], 'S')
>>> dumps([1,2], 'Y')

omni_json_db.loads(data, ret_type='J')

convert Json/Marshal/Pickle/Msgpack/YAML bytes into Python data

Parameters:

data (Any) – Json/Msgpack/Marshal/Pickle bytes
ret_type (str, optional) –
return format
- ”J” = JSON format
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

Python data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> loads(dumps([1,2], 'J'), 'J') # Output: [1,2]
>>> loads(dumps([1,2], 'M'), 'M') # Output: [1,2]
>>> loads(dumps([1,2], 'P'), 'P') # Output: [1,2]
>>> loads(dumps([1,2], 'S'), 'S') # Output: [1,2]
>>> loads(dumps([1,2], 'Y'), 'J') # Output: [1,2]

omni_json_db.run_files_server(host='127.0.0.1', port=59898, files=None, verbose=0)[source]

Initialize and start a multi-threaded TCP server to allow external access to the JDb object.

Parameters:

host (str, optional) – The host address for the server to listen on. Defaults to ‘127.0.0.1’.
port (int, optional) – The port number for the server to listen on. Defaults to 59898.
files (Union[str, bytearray, JFilesBase, JDbReader, None], optional) –
The specified source for the database file:
- str: Uses JMemFiles() if empty; otherwise, parses as JDiskFiles(path).
- bytearray: Uses JMemFiles(KEY_file).
- JFilesBase: Various file objects (JDiskFiles, JMemFiles, JNetFiles).
- JDbReader: An existing JDbReader object.
- None: Defaults to JMemFiles().
verbose (int, optional) – Logging verbosity level (-1: Off, 0: Limited, 1: Error, 2: Warning, 3: Info, 4: Debug). Defaults to 0.

Return type:

TCPServer

Returns: TCPServer: The started TCP server instance.

Raises:: TypeError – Raised when the provided type for the files parameter is invalid.

Examples

>>> server = run_files_server(host='127.0.0.1', port=8080)
>>> server.shutdown()

omni_json_db.jdb

class omni_json_db.jdb.JDb(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Bases: JDbReader

Main Database controller managing reading, writing, transaction rollbacks, and multi-part data compaction pipelines.

Ensures data consistency under high concurrent load using fine-grained file-level system locking primitives.

__delitem__(key)[source]

Physically drop or unlink selected record entries spaces from database index tracking registries.

Parameters:

key (Union[str, Any]) –

Unique entry character label token text descriptor, query filter conditional lambda function, regex sequence pattern, or subset iterable sequence.

str | int | float | bool | bytes
```
>>> del jdb['name']
```

Condition

>>> user = Query()
>>> del jdb[user.age >= 40]

slice | date | datetime

>>> del jdb[1:10:2]
>>> del jdb[-10.:]
>>> del jdb[:]
>>> del jdb[dt.date(2020,1,1)::r'key[0-9]']
>>> del jdb[:100:r'key[0-9]']
>>> del jdb[date(2020,1,1)]
>>> del jdb[datetime(2020,1,1)]

function(k,v)

>>> del jdb[lambda k,v: k.startswith('key')]
>>> del jdb[lambda k,v: v == 10] = val

function(k)
```
>>> del jdb[lambda k: k[0] == 'k']
```
re.Pattern
```
>>> del jdb[re.compile(r'key[0-9]')]
```

tuple | set | list | dict

>>> del jdb['a', 'b', 'c', 'd']
>>> del jdb[('a', 'b', 'c', 'd')]
>>> del jdb[{'a', 'b', 'c', 'd'}]
>>> del jdb[['a', 'b', 'c', 'd']]
>>> del jdb[{'a':0, 'b':1, 'c':2, 'd':3}]

Raises:

TypeError – If lookups evaluation candidates strike unrecognizable parameter types rules boundaries models.

Example

>>> del jdb[:] # delete all records
>>> del jdb['name']
>>> del jdb[lambda k,v: k.startswith('temp_')]

__iadd__(records)[source]

Batch load elements dictionaries mapping records directly in-place rewriting overlapping values lines.

Parameters:

records (Dict[str, Any]) –

Collection mapping identifiers to target value instances or iterable primitives arrays.

JDbReader
```
>>> jdb += other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb += {'a':1, 'b':2}
```

tuple | set | list == List[Any] == (val1, val2, ..)

>>> jdb += {'a', 'b'} # jdb.update_vals({'a', 'b'})
>>> jdb += ('a', 'b') # jdb.update_vals(('a', 'b'))
>>> jdb += ['a', 'b'] # jdb.update_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb += 'name' # jdb['name'] = None
```

Returns:

Self repository context manager interface handle reference.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb += {'new_key': 99}

__iand__(records)[source]

Batch update or override known elements row values data rows avoiding adding unknown outliers into index layers maps.

Parameters:

records (Dict[str, Any]) –

Translation adjustments dictionary mapping context models fields.

JDbReader
```
>>> jdb &= other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb &= {'a':1, 'b':2}
```

tuple | set | list == Tuple[Any] == (val1, val2, ..)

>>> jdb &= {'a', 'b'} # jdb.replace_vals({'a', 'b'})
>>> jdb &= ('a', 'b') # jdb.replace_vals(('a', 'b'))
>>> jdb &= ['a', 'b'] # jdb.replace_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb &= 'name' # jdb['name'] = None
```

Returns:

Self database environment framework instance configuration wrapper.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb &= {'key1': 99}
>>> jdb['key1']
99

__init__(KEY_file=None, data_type='J+S', zip_type='no', key_limit='no', cache_limit=0, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, api_ver=None, write_hook=None, max_wsize=None, flags=None, **kwargs)[source]

Initialize the transactional JDb controller object mapping configurations sheets models.

Parameters:

KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None], optional) –
File path, memory buffer, or network host.
- None | bytearray
  - JMemFiles() or JMemFiles(bytearray)
- str
  - ’’ = use JMemFiles() in memory
  - ’127.0.0.1:8001’ = use JNetFiles((‘127.0.0.1’, 8001))
  - ’database/test.jdb’ = use JDiskFiles(database/test.jdb)
- JDbReader = use JDb.files_obj
- JMemFiles | JNetFiles | JDiskFiles
data_type (Union[str, int, None], optional) –
Serialization format
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Compression algorithm to use.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
key_limit (Union[str, int, None], optional) –
Key table limitation constraint.
- ”no” = use DictKeyTable. (default).
- ”bt” = use BTreeKeyTable.
- ”l0”-“l5” = use LiteKeyTable.
- +ve: use PartialKeyTable.
cache_limit (int, optional) –
In-memory object cache limit.
- -1 = unlimited cache.
- 0 = no cache. (default)
- +ve = with cache.
max_file_size (Optional[int], optional) – Max size of a single data part.
min_value_size (Optional[int], optional) – Minimum byte size for value padding.
index_size (Optional[int], optional) – Fixed byte size for the key index records.
reserved_rate (Optional[float], optional) – Expansion buffer rate for data rows.
api_ver (Optional[int], optional) –
API structural version limit.
- 0 = oldest version.
- None = latest version. (default)
write_hook (Optional[Callable[[str, Any], bool]], optional) – Callback triggered before writing.
max_wsize (Optional[int], optional) – Search window for dead lines. Defaults to 4.
flags (Optional[JFlag], optional) – Enum flags for modifying revert/split behavior.
**kwargs – Extra arguments passed to internal components.

Raises:

TypeError – Raised if provided arguments are of the incorrect type.

Example

>>> jdb = JDb() # in-memory mode
>>> jdb = JDb('192.168.0.1:8181') # Network mode
>>> jdb = JDb('file.jdb') # file mode
>>> jdb = JDb('example.jdb', data_type='J+J', zip_type='gz')

__ior__(records)[source]

Batch insert unallocated entities matrices structures arrays in-place strictly bypassing existing nodes bounds.

Parameters:

records (Dict[str, Any]) –

Target context source map entries.

JDbReader
```
>>> jdb |= other_jdb
```
dict == Dict[str,Any] == {key1:val1, key2:val2, ..}
```
>>> jdb |= {'a':1, 'b':2}
```

tuple | set | list == List[Any] == (val1, val2, ..)

>>> jdb |= {'a', 'b'} # jdb.insert_vals({'a', 'b'})
>>> jdb |= ('a', 'b') # jdb.insert_vals(('a', 'b'))
>>> jdb |= ['a', 'b'] # jdb.insert_vals(['a', 'b'])

str | int | float | bool | bytes
```
>>> jdb |= 'name' # jdb['name'] = None
```

Returns:

Self proxy repository interface controller instance framework.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb |= {'new_key': 99}

__isub__(keys)[source]

Batch remove outstanding entries index references using LIFO strategy blocks optimization.

Parameters:

keys (Set[str]) –

Target dataset collection maps array or sibling JDbReader source instance candidate.

JDbReader
```
>>> jdb -= other_jdb
```
str | int | float | bool | bytes
```
>>> jdb -= "name" # jdb -= {"name"}
```

tuple | set | list | dict

>>> jdb -= {'a'', 'b'', 'c', 'd'}
>>> jdb -= ('a'', 'b'', 'c', 'd')
>>> jdb -= ['a'', 'b'', 'c', 'd']
>>> jdb -= {'a':0, 'd':1, 'c':2, 'd':3}

Returns:

Self instance with specified nodes decoupled completely.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1', 'key2', 'key3'] = 1
>>> jdb -= {'key1', 'key2', 'key3'}

__ixor__(keys)[source]

Revert or roll back transaction shifts processing selected node indicators parameters history blocks fields.

Parameters:

keys (Set[str]) –

Target indicator strings mapping historical recovery boundaries paths.

JDbReader
```
>>> jdb ^= other_jdb
```
str | int | float | bool | bytes
```
>>> jdb ^= 'name'
```

dict | tuple | set | list

>>> jdb ^= {'a', 'b'}
>>> jdb ^= ('a', 'b')
>>> jdb ^= ['a', 'b']
>>> jdb ^= {'a':1, 'b':2} # == {'a', 'b}

Returns:

Self chronologically synchronized operational workspace manager proxy.

Return type:

JDb

Example

>>> jdb = JDb()
>>> jdb['key1'] = 1
>>> jdb['key1'] = 99
>>> jdb ^= {'key1'}
>>> jdb['key1']
1

__setitem__(key, val)[source]

Commit or modify entry content mapping values utilizing scalar indicators, regex arrays or functions parameters.

Parameters:

key (Union[str, Any]) –

Target database lookups selection token lookup identifier or filter schema block query criteria fields.

str | int | float | bool | bytes
```
>>> jdb['name'] = val
```

Condition

>>> User = Query()
>>> jdb[User.name == 'Alice'] = val

slice | date | datetime

>>> jdb[1:10:2] = val
>>> jdb[-10.:] = val
>>> jdb[:] = val
>>> jdb[date(2020,1,1)::r'key[0-9]'] = val
>>> jdb[:100:r'key[0-9]'] = val
>>> jdb[date(2020,1,1)] = val
>>> jdb[datetime(2020,1,1)] = val

function(k,v)

>>> jdb[lambda k,v: k.startswith('key') and v > 0] = val
>>> jdb[lambda k,v: v == 10] = val

function(k)
```
>>> jdb[lambda k: k[0] == 'k'] = val
```
re.Pattern
```
>>> jdb[re.compile(r'key[0-9]')] = val
```

tuple | set | list | dict

>>> jdb['a', 'b', 'c', 'd'] = val | func
>>> jdb[('a', 'b'', 'c', 'd')] = val | func
>>> jdb[{'a', 'b'', 'c', 'd'}] = val | func
>>> jdb[['a', 'b'', 'c', 'd']] = val | func
>>> jdb[{'a':0, 'b':1, 'c':2, 'd':3}] = val | func

val (Any) –

Payload value context or updating mutation callback functional lambda routine.

any type but function
```
>>> jdb['name'] = val
```

function(k,v)

>>> jdb['name'] = lambda k,v : v+1
>>> jdb['name'] = lambda k,v : v+1 if v is not None else None # replace if exist
>>> jdb['name'] = lambda k,v : v if v is not None else 1 # insert if not exist

Raises:

TypeError – If input validation layers discover corrupted lambda parameter signatures rules or mismatched data types.

Example

>>> jdb['name'] = 'Charlie'
>>> jdb[lambda k,v: v == 10] = 11
>>> jdb[1:10:2] = "updated"

add(records, default_val=None, replace=True, insert=True, is_list=False, flags=None, max_wsize=None)[source]

Core serialization writing gatekeeper pipeline routing entries insertions or value replacements into database tracks layers maps.

Parameters:

records (Dict[str, Any]) – Repository container processing elements candidates maps records fields text tokens variables.
default_val (Optional[Any], optional) – Fallback value mapping variables context assigned if source candidate parses abstract. Defaults to None.
replace (bool, optional) – Overwrite pre-existing records keys if lookups discover shared matching indicators indices parameters logs. Defaults to True.
insert (bool, optional) – Generate brand new data records lines spaces if target descriptors evaluate absent from index pools. Defaults to True.
is_list (bool, optional) – Toggle switch adapting input types tracking sequences listing vs dictionaries tracking key-value parameters. Defaults to False.
flags (Optional[JFlag], optional) – strategic behavioral modifiers. Defaults to None.
max_wsize (Optional[int], optional) – Scan scope lookahead density limit constraining dead rows tracking checks loops fields. Defaults to None.

Returns:

Descriptive dictionary summary array tracking all successfully committed modified entries fields log data metrics records fields.

Return type:

Dict[str, Any]

Raises:

TypeError – If input validation candicates structures break system framework specifications classes.

add_group(key)[source]

Initialize an isolated nested cluster sub-database partition workspace domain.

Parameters:: key (str) – Subfolder tracking name selector token text string.
Returns:: The newly constructed partition node interface.
Return type:: JDb
Raises:: KeyError – If incoming cluster nomenclature violates basic string character constraints.

append(records, **kwargs)[source]

Batch append continuous sequence datasets mapping rows values content segments parts blocks anonymously utilizing sequence numbers as descriptors labels markers arrays sheets.

Parameters:

records (List[Any]) – Array container processing distinct values entries configurations records fields metrics.
**kwargs – Strategic flags variables modifiers parameters context settings blocks layers maps tracks systems.

Returns:

Generated mapping fields matching identity codes tokens integers sequences keys to individual saved objects data lines.

Return type:

Dict[str, Any]

backup(folder=None, data_type=None, zip_type=None, fast_mode=True, **kwargs)[source]

Clone structural matrix database state tracking sheets records fields exporting backups profiles to targeted destination folders clusters.

Parameters:

folder (Optional[str], optional) – Target system descriptor path code string identifier template context. Defaults to None.
data_type (Union[str, int, None], optional) –
Override layout specifications format setting selection index. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Override snapshot baseline row compression properties values limits rules. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
fast_mode (bool, optional) – Accelerate copy algorithms utilizing binary segment streams maps mirroring rules. Defaults to True.
**kwargs – Extra attributes routed down seamlessly to child construction factories.

Returns:

Initialized destination replica workspace proxy connection interface object.

Return type:

JDb

Example

>>> jdb = JDb('example.jdb', data_type='J+M', zip_type='gz')
>>> jdb += {f'key{v}':list(range(v)) for v in range(100)}
>>> bak_jdb = jdb.backup(folder='bak', data_type='S+S', zip_type='br')
>>> print(bak_jdb.date_type, bak_jdb.zip_type)
S+S br

change_KEY(KEY_type, api_ver=None)[source]

Transcode indexing layouts formats blueprint rules rewriting master entry trackers parameters configurations.

Parameters:

KEY_type (str) – Format encoding specification classification string token text (‘J’, ‘L’, ‘M’, ‘S’).
api_ver (Optional[int], optional) – Physical logical standard implementation layout version index number. Defaults to None.

Returns:

True if structure transposition completes altering the master file, False otherwise.

Return type:

bool

Raises:

ValueError – If target codes evaluate out of structural ranges definitions thresholds.

Example

>>> jdb = JDb(date_type='J+J')
>>> jdb.change_KEY('S')
>>> print(jdb.data_type)
S+J

check_error(parent='', level=0, fix_it=False, verbose=True)[source]

Validate logical structure integrity scan index layers maps checking anomalies corruptions cross-referencing files parameters indicators metrics models.

Parameters:

parent (str, optional) – Hierarchy node namespace trace tracking origin references variables tokens. Defaults to ‘’.
level (int, optional) – Deepness limitation parameter capping child database recursion lookahead cycles. Defaults to 0.
fix_it (bool, optional) – Trigger dynamic reconstruction algorithms rewriting mismatching structures headers rows templates objects. Defaults to False.
verbose (bool, optional) – Enable terminal diagnostics print traces mapping structural verification flows metrics grids windows panels fields fields logs. Defaults to True.

Returns:

Registry tracing all identified data alignment failures associated against internal sequence identifiers numbers lines.

Return type:

dict

chg_keys: Set

childs: Dict[str, JDbReader]

clear(agree='no', wait_sec=10, **kwargs)[source]

Obliterate data registries resetting storage files templates entirely to an empty layout framework.

Parameters:

agree (str, optional) – Validation security phrase. Must equal strictly string token ‘yes’ to proceed. Defaults to ‘no’.
wait_sec (int, optional) – Counting delay buffer allowing developers to abort using Ctrl-C indicators. Defaults to 10.
**kwargs – Extra settings overrides configuring properties mapped onto the fresh structural sheets.

Returns:

True if destruction and reallocation finalize properly, False otherwise.

Return type:

bool

clone_to(target, signal='.', fast_mode=True, max_file_size=None, min_value_size=None, index_size=None, reserved_rate=None, data_type=None, zip_type=None, cache_limit=0, api_ver=None, **kwargs)[source]

Clone data mapping layouts structures templates from self source environment into target destination storage configurations drivers arrays frames.

Parameters:

target (Union[JDb, JFilesBase, str]) – Target storage manager engine wrapper, location token path text format layout selector string, or absolute instance proxy context.
signal (str, optional) – Heartbeat monitoring output string token mapped onto runtime console loops indicators text. Defaults to ‘.’.
fast_mode (bool, optional) – Engage raw binary stream optimization mechanics bypassing transcoders pipelines loops if schemas align uniformly. Defaults to True.
max_file_size (Optional[int], optional) – Custom destination storage capacity parameter setting data file segment bounds. Defaults to None.
min_value_size (Optional[int], optional) – Minimum alignment floor width constraint bounding row expansion buffers tracks. Defaults to None.
index_size (Optional[int], optional) – Fixed byte width defining destination row padding boundaries constraints markers fields. Defaults to None.
reserved_rate (Optional[float], optional) – Cushion expansion multiplier allocated across target workspace segments fields. Defaults to None.
data_type (Union[str, int, None], optional) –
Format coding classification token specifying serialization configurations layout schemas. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Targeted compression algorithm code token selection settings options values. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
cache_limit (int, optional) – Memory limitation constraint variables values bounding destination cache lookup objects registry. Defaults to 0.
api_ver (Optional[int], optional) – Logical logical operational standard blueprint standard iteration version identifier. Defaults to None.
**kwargs – Extra settings overrides routed down seamlessly onto compilation factory pipelines matrices.

Returns:

The initialized populated target destination session environment workspace model context.

Return type:

JDb

Raises:

TypeError – If input target elements candidates fail driver framework integration matching expectations rules profiles metrics tracks.

create_jdb(KEY_file)[source]

Spawn a child read-write companion database instance mimicking host properties models parameters grids.

Parameters:: KEY_file (Union[str, bytearray, JFilesBase, JDbReader, None]) – File path or core buffer source stream.
Returns:: A relative fresh JDb session workspace environment instance.
Return type:: JDb

del_group(key)[source]

Exterminate a nested sub-database cluster namespace dropping structural tracking indicators permanently.

Parameters:: key (str) – Sub-space lookup target selector token text string.
Returns:: The destroyed group instance handle if successfully cleared, None fallback otherwise.
Return type:: Optional[JDb]

f_change_days(fp_dict, key, days=-1)[source]

Modify the timestamp of a specific Key at the low level without changing the data content.

Parameters:

fp_dict (Dict[int, IO]) – The file descriptor set for the current thread.
key (str) – The name of the target key.
days (Union[int, float, str, dt_date, datetime], optional) – The number of days, time object, or string representation of the date to be written. Defaults to -1.

Returns:

Returns True if the write is successful; returns False if it fails or the Key is not found.

Return type:

bool

f_delete(fp_dict, key, read_value=True, row=None, flags=None)[source]

Low-level pipeline method: physically unlink a specified entity, compact index arrays, and manage transaction rollbacks.

Parameters:

fp_dict (Dict[int, IO]) – Open file pointers maps repository.
key (str) – Unique entry identification lookup code label string.
read_value (bool, optional) – Unpack and return original data contents before discarding tracking pointers. Defaults to True.
row (Optional[int], optional) – Precise allocation row block offset index to bypass search indices. Defaults to None.
flags (Optional[JFlag], optional) – strategic behavioral modifiers flags. Defaults to None.

Returns:

The unlinked python value payload object, or group workspace if targeted entity maps a nested sub-database.

Return type:

Any

f_get_child(fp_dict, name)[source]

Low level routing factory resolving child detached storage pipelines inside current streams boundaries maps trackers.

Parameters:

fp_dict (Dict[int, IO]) – Active file pointers registration collection maps table.
name (str) – Named item node partition token text descriptor selector.

Returns:

Open operational child dataset workspace reference, or None if validation fails.

Return type:

Optional[JDb]

f_get_write_fp(fp_dict)[source]

Acquire and configure exclusive writing streams access permissions channels context maps matrices metrics.

Parameters:: fp_dict (Dict[int, IO]) – Active file handler dictionary tracking metrics variables configuration parameters.
Returns:: Consolidated processing context payload group returning core matrix, file map registers, main descriptor pointer, and timeline shift synchronization flag state.
Return type:: Tuple[JIo, Dict[int, IO], IO, bool]
Raises:: RuntimeError – If multi-threaded file locks context cannot initialize isolation guards blocks parameters thresholds numbers.

f_rename(fp_dict, key, new_key)[source]

Low-level pipeline method: alter unique index reference tokens text strings mapping keys metadata blocks layout configurations.

Parameters:

fp_dict (Dict[int, IO]) – Active file handler matrix registration array mapping pools handles.
key (str) – Existing unique query selector name token label string format context fields fields.
new_key (str) – Newly requested target character string identification indicator code text.

Returns:

True if identity name properties switch successfully inside tracking registers, False otherwise.

Return type:

bool

Raises:

KeyError – If destination identifier string token collides against pre-allocated records fields data layers.

f_undelete(fp_dict, key, row=None, flags=None)[source]

Low-level pipeline method: resurrect dropped or unlinked indices descriptors variables from dead logs sectors.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active handles arrays tables registers.
key (str) – Missing identifier text selector string to target and recover.
row (Optional[int], optional) – Precise hardware target slot alignment position index to bypass lookup cycles loops. Defaults to None.
flags (Optional[JFlag], optional) – strategic modifiers flags. Defaults to None.

Returns:

Core allocation parameters metadata tuple summarizing recovered slot parameters if successful, None otherwise.

Return type:

Optional[Tuple[int,int,int,int,int]]

f_unwrite(fp_dict, key, row=None, flags=None)[source]

Low-level pipeline method: roll back dynamic record modifications shifting indices properties maps back to legacy content points maps.

Parameters:

fp_dict (Dict[int, IO]) – Persistent active system registers stream descriptor collections.
key (str) – Unique dictionary descriptive name string token format selector query fields.
row (Optional[int], optional) – Target layout position index bounding search rows loops. Defaults to None.
flags (Optional[JFlag], optional) – strategic modifiers behavioral flags. Defaults to None.

Returns:

Execution parameters logging adjusted item metrics parameters integers if successful, None otherwise.

Return type:

Optional[Tuple[int,int,int,int,int]]

f_write(fp_dict, key, val, days=-1, flags=None, max_wsize=None, compare=True)[source]

Low-level pipeline method: serialize, compress, and record dynamic Python value entries mapping into target filesystem tracks safely.

Parameters:

fp_dict (Dict[int, IO]) – Open file handles tracking collections metrics maps.
key (str) – Destination dictionary descriptor reference character token text string layout context.
val (Any) – Payload instance content python object structure to serialize.
days (int, optional) – Calendar modification timing tracking parameter representation number. Defaults to -1.
flags (Optional[JFlag], optional) – strategic behavioral modifiers flags. Defaults to None.
max_wsize (Optional[int], optional) – Maximum search lookahead steps window constraint index number. Defaults to None.
compare (bool, optional) – compare old value and new value before writing it. Defaults to True

Returns:

True if serialization persistence completes smoothly, False if transaction logic drops inputs.

Return type:

bool

Raises:

TypeError – If interceptor write hooks reject incoming inputs configuration candidate attributes.

f_write_bytes(fp_dict, key, val, days=-1, flags=None, max_wsize=None)[source]

Low-level pipeline method: directly commit raw un-serialized binary byte blocks into physical content sectors tracks.

Parameters:

fp_dict (Dict[int, IO]) – Current thread transactional context opens registries handles maps.
key (str) – Unique data record pointer lookup name token layout string.
val (bytes) – Raw uncompressed payload byte configuration data chunk array.
days (int, optional) – Compact timeline relative days counter index selection number. Defaults to -1.
flags (Optional[JFlag], optional) – Custom modifier bitflags overrides. Defaults to None.
max_wsize (Optional[int], optional) – Maximum search lookahead steps window constraint index number. Defaults to None.

Returns:

True if binary persistence pipelines execute smoothly, False fallback otherwise.

Return type:

bool

file_lock: FileLock

files_obj: JFilesBase

flags: JFlag

fp_table: Dict[int, dict]

from_csv(csv_file, key=None, flags=None, max_wsize=None, **kwargs)[source]

Import structured CSV text streams context sheets fields records translating tabular elements rows matrices back onto native database maps datasets collections.

Parameters:

csv_file (Union[str, IO]) – Source filesystem node address string path notation text or open stream descriptor channel container proxy.
key (Optional[str], optional) – Identity reference label indicating target unique row key column header text layout. Defaults to None.
flags (Optional[JFlag], optional) – strategic operational behavioral modifiers flags. Defaults to None.
max_wsize (Optional[int], optional) – Search window capacity constraint bounding dead structural entry lookahead scans width parameters. Defaults to None.
**kwargs – Extra parameters routed down seamlessly onto secondary underlying DictReader extraction components.

Returns:

Current context modified active database environment workspace proxy handle.

Return type:

JDb

from_ini(src)[source]

Parse configuration template sheets fields context records extracting variables settings structures from classic text INI files layout templates blocks rules.

Parameters:: src (Union[str, IO]) – Full target system text string path context layout parameters maps or active open file object stream interface pointer locator.
Returns:: Updated relational configuration workspace context handle.
Return type:: JDb

from_sqlite(src, batch_size=-1)[source]

Migrate SQLite transaction tables models matrices records mapping columns profiles straight into isolated nested database groups spaces partitions layers.

Parameters:

src (Union[str, Connection]) – Full database file system address string text path context layout parameters maps or active connection instance handle proxy.
batch_size (int, optional) – Iteration size constraint capping total rows fetched during single chunk cycles processes frames metrics. Defaults to -1.

Returns:

Updated relational engine state interface snapshot workspace.

Return type:

JDb

Raises:

TypeError – If input sources violate target standard database connection configurations criteria parameters properties fields.

from_toml(src)[source]

Parse TOML specification sheets structures arrays data profiles converting unified hierarchical trees structures documents models directly into record metrics paths context.

Parameters:: src (Union[str, IO]) – Target localization filename string path context blueprint text or open streaming object channel handle wrapper proxy.
Returns:: Updated dataset configurations management engine state.
Return type:: JDb
Raises:: ModuleNotFoundError – If the host runtime environment misses required third party parsing extensions framework dependencies libraries wrapper hooks.

fsize

insert(records, default_val=None, **kwargs)[source]

Batch write new elements parameters metrics ignoring existing records overlaps boundaries positions lines fields metrics logs maps.

Parameters:

records (Dict[str, Any]) – Core context source dictionary mapping indices properties fields.
default_val (Optional[Any], optional) – Fallback placeholder variable options parameters settings models. Defaults to None.
**kwargs – Extra transaction isolation modifiers parameters variables.

Returns:

Subset tracking entries successfully registered inside indices fields.

Return type:

Dict[str, Any]

insert_vals(records, **kwargs)[source]

Batch insert row value metrics collections anonymously into new entries indices slots.

Parameters:

records (List[Any]) – Sequence collection containing target entries values arrays fields indicators models tracks metrics.
**kwargs – Extra transactional parameter switches.

Returns:

Mapping catalog aligning sequence identities variables to generated records outputs.

Return type:

Dict[str, Any]

io: JIo

keys: JDbKey

lock

max_wsize: int

pop(key, default_val=None)[source]

Isolate, pop, and erase an individual item record from indices returning previous python object contents.

Parameters:

key (str) – Target dictionary lookup query choice token text string descriptor criteria.
default_val (Optional[Any], optional) – Fallback data assigned if lookup registers miss elements indicators. Defaults to None.

Returns:

Unpacked Python object value, or default_val if missing from storage tables.

Return type:

Any

Example

>>> previous_value = jdb.pop('key_to_remove', default_val=0)

recycle(parent='', level=0, merge=False, fill_zero=False, verbose=True)[source]

Purge unlinked dead storage slots rewriting physical indexes sheets to reclaim unallocated disk space footprints metrics.

Parameters:

parent (str, optional) – Hierarchy prefix namespace path denoting partition trees boundaries. Defaults to ‘’.
level (int, optional) – Recursion limitation deepness constraining nested children evaluation scopes paths rules. Defaults to 0.
merge (bool, optional) – Combine contiguous sparse gaps inside data segments layout storage files. Defaults to False.
fill_zero (bool, optional) – Overwrite unallocated physical tracks with structural zeroes vectors preventing leakage traces. Defaults to False.
verbose (bool, optional) – Enable terminal logging text parameters metrics visualization alerts. Defaults to True.

Example

>>> jdb.recycle(merge=False)

reinit(records, default_val=None, is_list=False, agree='no', wait_sec=10, **kwargs)[source]

Purge tracking maps drop active registers systematically rebuilding complete datasets layout configurations from scratch matching incoming records fields.

Parameters:

records (Dict[str, Any]) – Incoming context source matrix data candidates.
default_val (Optional[Any], optional) – Fallback variable context setting parameter assigned if structures evaluate blank. Defaults to None.
is_list (bool, optional) – Adjust entry evaluation tracks converting lists structures sequences anonymously vs mapping dictionaries keys fields text format. Defaults to False.
agree (str, optional) – Safeguard validation checkpoint rule phrase. Must equal strictly ‘yes’ to proceed. Defaults to ‘no’.
wait_sec (int, optional) – Interactive buffer countdown seconds threshold capping destruction loops parameters. Defaults to 10.
**kwargs – Extra attributes override keys passed down seamlessly to re-initialization routines.

Returns:

True if allocation routines commit the fresh structures records maps smoothly, False if checkpoint guards intercept execution paths tracks.

Return type:

bool

remove(*records)[source]

Batch decouple unlinking targeted index entry row selections extracting values payloads concurrently back onto general system pools.

Parameters:: *records (str) – Variadic references containing key strings tokens to systematically purge from active pools sheets.
Returns:: Dictionary mapping successfully deleted record elements strings identifiers back onto their contents maps arrays blocks.
Return type:: Dict[str, Any]

remove_fast(*records)[source]

Batch decouple index parameters keys ignoring payload decryption parsing stages optimizing deletion streams throughput processing speed metrics profiles.

Parameters:: *records (str) – Unique text identifier token references variadic selection arguments context layout parameters maps tracks systems layers.
Returns:: Registry containing successfully discarded items keys list mappings logs.
Return type:: Set[str]

rename(keys)[source]

Batch re-label items mapping old text identifier codes tokens parameters straight into new destination unique name strings indices.

Parameters:: keys (Dict[str, str]) – Translation target dictionary pairing former tags descriptors keys with freshly requested identifiers text.
Returns:: Catalog mapping all altered item names coordinates changes records fields logs properties context.
Return type:: Dict[str, str]
Raises:: TypeError – If input mapping elements fail standard structural collection constraints.

replace(records, default_val=None, **kwargs)[source]

Batch rewrite pre-existing record lines parameters properties fields metrics values profiles avoiding adding unknown outliers into index pools blocks.

Parameters:

records (Dict[str, Any]) – Target translation dictionary allocating adjustments details configurations rules models sheets text fields context layers frameworks grids.
default_val (Optional[Any], optional) – Fallback value. Defaults to None.
**kwargs – Extra execution runtime attributes.

Returns:

Replaced records data array tracking modified items coordinates parameters positions numbers blocks.

Return type:

Dict[str, Any]

replace_vals(records, **kwargs)[source]

Batch rewrite anonymous value elements sequences arrays avoiding appending unknown new index records lines.

Parameters:

records (List[Any]) – Input sequences collection mapping variables targets logs properties.
**kwargs – Extra hardware processing configuration overrides.

Returns:

Updated objects matrix maps summary results array tracking modified items.

Return type:

Dict[str, Any]

resize_index_size(index_size=0, extra_size=8, min_ver=True)[source]

Modify fixed tracking structural allocation padding bounding database row dimensions headers fields permanently.

Parameters:

index_size (int, optional) – Targeted byte allocation width constraint indicator. 0 forces dynamic scan configuration. Defaults to 0.
extra_size (int, optional) – Buffer allocation extension safety boundary width metrics. Defaults to 8.
min_ver (bool, optional) – Reset baseline synchronizations version markers indices. Defaults to True.

Returns:

Calculated final index padding dimension assigned across files structures.

Return type:

int

restore(folder='bak', fast_mode=True, **kwargs)[source]

Overwrite current repository layers tracking matrices components structures using elements matching chosen backup files templates.

Parameters:

folder (Union[str, JDb]) – File directory absolute lookup address string parameter or active source driver reader object workspace. Defaults to ‘bak’.
fast_mode (bool, optional) – Skip complex transposition steps if files properties mirror baseline configurations structures. Defaults to True.
**kwargs – Extra parameters routed forward seamlessly onto replication controllers.

Returns:

Current context active database session interface manager handle.

Return type:

JDb

Raises:

ValueError – If lookup coordinates target unallocated positions boundaries paths context lines.
TypeError – If input structural data candidate fails standard module validation checks.

Example

>>> jdb = JDb('example.jdb')
>>> jdb.restore(folder='bak')

revert(*records)[source]

Symmetrically execute recovery pipelines rolling back either variable values updates or item omissions based on history bounds logs.

Parameters:: *records (str) – Target text identifiers tracking variables contexts fields.
Returns:: Collection mapping keys fields onto recovery structural outcomes status codes.
Return type:: Dict[str, Any]

Example

>>> status = jdb.revert('target_key_1', 'target_key_2')

safe_line

set(key, val, flags=None, max_wsize=None)[source]

Write single entry content maps configuring transaction modifiers rules indices tracks.

Parameters:

key (str) –
Target unique key lookup choice token identifier text string.
- str
```
>>> jdb[ke)] = val
```
- int | float | bool
```
>>> jdb[str(key)] = val
```

val (Any) –

Scalar object layout payload or conditional update callback lambda routine context.

any type but function
```
>>> jdb['name'] = val
```

function(k,v)

>>> jdb['name'] = lambda k,v : v+1
>>> jdb['name'] = lambda k,v : v+1 if v is not None else None # replace if exist
>>> jdb['name'] = lambda k,v : v if v is not None else 1 # insert if not exist

flags (Optional[JFlag], optional) –
strategic behavioral modifiers. Defaults to None.
- REVERT = allow to revert
- SPLIT = allow to split largest row size to two
max_wsize (Optional[int], optional) –
Maximum search scope bounding lookahead sweeps across dead lines elements. Defaults to None.
- None = use default max_wsize (4)
- -ve = disable searching

Returns:

The committed data payload if changes successfully execute, old value context otherwise.

Return type:

Optional[Any]

Raises:

TypeError – If input candidate argument structures fail validation tests specifications models.

set_days(key, days)[source]

Modify tracking calendar timestamps elapsed days values logs stored within entry index parameters coordinates.

Parameters:

key (str) – Target descriptor lookups selection token lookup string classification label context.
days (Union[int, float, str, dt_date, datetime]) –
Timeline offset integer, calendar object instance, or formatted date text code.
- int : days since 1-1-1
```
>>> jdb.set_days('key', 1)
```
- str : ‘YYYY-MM-DD’ or ‘YYYY-MM-DD YYYY-MM-DD’
```
>>> jdb.set_days('key', "2000-01-01")
>>> jdb.set_days('key', "2000-01-01 2001-12-31")
```
- date | datetime
```
>>> jdb.set_days('key', date(2000, 1, 1))
>>> jdb.set_days('key', datetime(2000, 1, 1))
```
- float : timestamp

Returns:

True if modification markers indices write successfully, False fallback if errors strike connections.

Return type:

bool

set_n(records, default_val=None, replace=True, insert=True, **kwargs)[source]

Batch commit key-value collections mapping records into active database frames indexes lanes.

Parameters:

records (Dict[str, Any]) – Inputs target mapping records collections datasets.
default_val (Optional[Any], optional) – Fallback value mapping variables context if entries lookups evaluate abstract. Defaults to None.
replace (bool, optional) – Rewrite existing data points if indexes discover overlapping indicators matches parameters. Defaults to True.
insert (bool, optional) – Initialize unknown outliers creating fresh structural slots sheets fields records lines. Defaults to True.
**kwargs – Extra parameters routed down directly into underlying translation execution engines factories.

Returns:

Changed objects log maps summary array tracing modified elements paths.

Return type:

Dict[str, Any]

Raises:

TypeError – If input candidate collection elements break schema constraints maps parameters.

setdefault(key, val)[source]

Initialize chosen lookup strings with default values if currently missing from the index registries.

Parameters:

key (str) – Target text reference indicator lookup query string token context.
val (Any) – Fallback object template payload context rules data fields variables.

th_table: Dict[int, int]

to_csv(csv_file, key=None, **kwargs)[source]

Export internal data frames records fields matrices structures logs straight into tabular structured CSV data formats sheets files documents models.

Parameters:

csv_file (Union[str, IO]) – Target filename string locator path or open streaming file-like interface stream descriptor handle context.
key (Optional[str], optional) – Custom field token labeling the principal identifier index row data columns fields layout. Defaults to None.
**kwargs – Extra formatting parameters routed directly onto inner DictWriter configuration profiles blueprints rules options fields.

Returns:

True if extraction workflows finish completely without errors metrics profiles, False fallback otherwise.

Return type:

bool

unmodify(*records)[source]

Undo dynamic value row mutations rolling records states back onto prior chronological signatures logs on file layer.

Parameters:: *records (str) – Variadic sequence choosing target keys or groups tracking indicators strings to restore.
Returns:: Mapping dictionary summarizing all successfully restored entities linked along previous positions data.
Return type:: Dict[str, Any]

Example

>>> recovered_info = jdb.unremove('accidental_delete_key')

unremove(*records)[source]

Resurrect dropped index tracking references pulling deleted outlier components back into live databases index pools blocks.

Parameters:: *records (str) – Unique identifier token strings matching targeted deleted records candidates tracking keys data.
Returns:: Execution summary index tracing resurrected targets aligned with recovered layouts coordinates parameters logs.
Return type:: Dict[str, Any]

update(records, default_val=None, **kwargs)[source]

Batch load elements dictionaries mapping records directly in-place rewriting overlapping lines fields metrics fields.

Parameters:

records (Dict[str, Any]) – Datasets records dictionary mapping collections lines tracks.
default_val (Optional[Any], optional) – Fallback parameter value context fields variables. Defaults to None.
**kwargs – Strategic execution modifier attributes passed smoothly onto translation processors factories frameworks wrappers.

Returns:

Catalog tracing successfully updated dataset items.

Return type:

Dict[str, Any]

update_if(condition, patch)[source]

Merge patch into every record (dict value) matching condition.

Parameters:

conditon (Condition | dict) – Condition for key/date/value filtering.
patch (dict | Callable[[str,Any],Dict[str,Any]]) – if condition is matched, update the corresponding value.

Returns:

the number of records updated.

Return type:

int

Example

>>> jdb.update_if(Query().age <= 32, {'age':18, 'active':True})
>>> jdb.update_if(Query().age <= 99, lambda k,v : {'age':v['age']+1, status:v['age']<40})

update_vals(records, **kwargs)[source]

Batch update or append anonymous values collections entries into database lanes maps.

Parameters:

records (List[Any]) – Input items sequences list container.
**kwargs – Strategic transaction properties context configuration rules parameters trackers handles.

Returns:

Generated identity key dictionary tracks tracking saved row models.

Return type:

Dict[str, Any]

upgrade(folder='bak', data_type=None, zip_type=None, fast_mode=True, **kwargs)[source]

Migrate database models records maps layouts transforming internal formats properties fields seamlessly via proxy nodes staging tracks.

Parameters:

folder (str, optional) – Target temporary folder location token. Defaults to ‘bak’.
data_type (Union[str, int, None], optional) –
Override serialization schema standard encoding format settings. Defaults to None.
- ”J+J” | KEY=JSON | VAL=JSON
- ”J+M” | KEY=JSON | VAL=Marshal
- ”J+P” | KEY=JSON | VAL=Pickle
- ”J+S” | KEY=JSON | VAL=msgpack (default)
- ”J+Y” | KEY=JSON | VAL=YAML
- ”S+J” | KEY=Msgpack | VAL=JSON
- ”S+M” | KEY=Msgpack | VAL=Marshal
- ”S+P” | KEY=Msgpack | VAL=Pickle
- ”S+S” | KEY=Msgpack | VAL=msgpack
- ”S+Y” | KEY=Msgpack | VAL=YAML
- ”L+J” | KEY=split | VAL=Json
- ”M+M” | KEY=Marshal | VAL=Marshal
zip_type (Union[str, int, None], optional) –
Override compression layout parameters criteria markers fields. Defaults to None.
- ”no” = no compression for VAL. (default)
- ”gz” = gzip compression(9) for VAL.
- ”bz” = bz2 compression(9) for VAL.
- ”xz” = lzma compression for VAL.
- ”zs” = zstandard compression(22) for VAL.
- ”br” = brotli compression(6) for VAL.
- ”z1” = zstandard compression(6) for VAL.
- ”z2” = zstandard compression(11) for VAL.
- ”lz” = lz4 compression(0) for VAL.
fast_mode (bool, optional) – Skip extraction loop algorithms stages if transcoders align uniformly. Defaults to True.
**kwargs – Extra parameters passed straight to construction modules.

Returns:

Updated system interface reference workspace engine.

Return type:

JDb

write_hook: Callable[[str, Any], bool]

static z_dumps(data, ret_type=None)[source]

convert any data into Json/Marshal/Pickle/Msgpack/YAML format

Parameters:

data (Any) –
target Python data
- support str/bytes/int/float/bool/None/dict/list/set/tuple/JDb
ret_type (str, optional) –
return format
- ”J” = JSON format (default)
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

converted data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> dumps([1,2], 'J')
>>> dumps([1,2], 'M')
>>> dumps([1,2], 'P')
>>> dumps([1,2], 'S')
>>> dumps([1,2], 'Y')

static z_loads(data, ret_type='J')[source]

convert Json/Marshal/Pickle/Msgpack/YAML bytes into Python data

Parameters:

data (Any) – Json/Msgpack/Marshal/Pickle bytes
ret_type (str, optional) –
return format
- ”J” = JSON format
- ”M” = Marshal format
- ”P” = Pickle format
- ”S” = Msgpack format
- ”Y” = YAML format

Returns:

Python data

Return type:

bytes

Raises:

ValueError – invalid ret_type

Example

>>> loads(dumps([1,2], 'J'), 'J') # Output: [1,2]
>>> loads(dumps([1,2], 'M'), 'M') # Output: [1,2]
>>> loads(dumps([1,2], 'P'), 'P') # Output: [1,2]
>>> loads(dumps([1,2], 'S'), 'S') # Output: [1,2]
>>> loads(dumps([1,2], 'Y'), 'J') # Output: [1,2]

static z_upgrade_API(KEY_path)[source]

Upgrade an older version of the database to the latest API structural format.

This method reads the existing database schema, resizes the index structure if necessary, migrates all tracking properties and physical indices to match the specifications of API_LATEST, and overwrites the legacy header. It ensures backward compatibility for older .jdb files by re-encoding the storage pipelines.

Parameters:: KEY_path (Union[str, JDb]) – The file path string to the legacy database, or an already initialized JDb instance that requires upgrading.
Returns:: The fully upgraded database controller instance running on the newest API format.
Return type:: JDb
Raises:: TypeError – If the provided KEY_path cannot be resolved into a valid JDb instance, or if the current API version is missing/invalid.

Example

>>> from omni_json_db import JDb
>>> # Upgrade a legacy database file to the latest API
>>> upgraded_db = JDb.z_upgrade_API('db/legacy_data.jdb')
>>> print(upgraded_db.io.api_ver)

static z_upgrade_KEY_day(KEY_path)[source]

Upgrade and rectify the legacy timeline tracking format (days) inside the database index.

This migration method patches older date formats (specifically targeting pre-2000 epoch offsets) within the index registries. It sequentially scans all allocated rows, updates the timestamp metadata values directly via bitwise masks, and rewrites the file header safely.

Parameters:: KEY_path (Union[str, JDbReader]) – The absolute file path to the database, or an active JDb/JDbReader instance wrapper.
Returns:: The database controller instance with fully rectified timeline index matrices.
Return type:: JDb
Raises:: TypeError – If the input target cannot be instantiated or validated as a proper JDb environment.

Example

>>> from omni_json_db import JDb
>>> # Fix timeline metadata constraints for an older database
>>> fixed_db = JDb.z_upgrade_KEY_day('db/old_timestamps.jdb')

class omni_json_db.jdb.JDbKey2(jdb)[source]

Bases: JDbKey

Extended read-write key navigation proxy subsystem handling conditional timeline transformations.

__setitem__(key, val)[source]

Modify the calendar tracking metrics associated with specific database keys dynamically.

Processes complex queries including string identifiers, regex targets, or filtering lambdas.

Parameters:

key (Union[str, Any]) – Unique selection text string, compiled regex pattern, callable condition filter, or historical slice.
val (Union[str, int, datetime, dt_date]) – Normalized time token descriptor, datetime instance, or calculated days integer.

Raises:

TypeError – If the incoming value or functional keys violate standard layout validation parameters rules.

Return type:

None

jdb: JDbReader

omni_json_db.jdb_file

class omni_json_db.jdb_file.JBytesIO(buffer, *args, **kwargs)[source]

Bases: RawIOBase

An optimized, in-memory binary stream interface managing a mutable bytearray buffer.

Inherits from io.RawIOBase to provide standard I/O streaming integration.

__del__()[source]: Safely destruct the current context ensuring active resource components disengage.

__init__(buffer, *args, **kwargs)[source]

Initialize the stream interface with a mutable byte storage target.

Parameters:

buffer (Optional[bytearray]) – The mutable byte array serving as the underlying storage.
*args – Variable length arguments passed directly to RawIOBase.
**kwargs – Keyword arguments passed directly to RawIOBase.

Raises:

TypeError – If the provided buffer is not a bytearray.

buf

fileno()[source]

Returns underlying file descriptor if one exists.

OSError is raised if the IO object does not use a file descriptor.

Return type:: int

idx

read(size=-1)[source]

Read up to size bytes from the stream.

Parameters:: size (int, optional) – The maximum number of bytes to read. Defaults to -1 (read all).
Returns:: The extracted binary data.
Return type:: bytes
Raises:: ValueError – If the stream is closed.

readable()[source]

Determine if the stream supports reading.

Returns:: True if the stream is open and readable.
Return type:: bool
Raises:: ValueError – If the stream is closed.

readall()[source]

Read and return all remaining bytes in the stream.

Returns:: The remaining binary data.
Return type:: bytes
Raises:: ValueError – If the stream is closed.

readinto(b)[source]

Read bytes directly into a pre-allocated, mutable byte-like object.

Parameters:: b (bytearray) – The mutable object to populate.
Returns:: The number of bytes successfully read.
Return type:: int
Raises:: ValueError – If the stream is closed.

readline(size=-1)[source]

Read and return one line from the stream.

Reads until a newline (\n) is found or the stream ends.

Parameters:: size (int, optional) – The maximum number of bytes to read. Defaults to -1 (no limit).
Returns:: The read line, including the trailing newline character if present.
Return type:: bytes
Raises:: ValueError – If the stream is closed.

readlines(hint=None)[source]

Read and return a list of lines from the stream.

Parameters:: hint (int, optional) – The maximum number of bytes to read across all lines. Defaults to None (read all lines).
Returns:: A list of byte strings, each representing a line.
Return type:: list
Raises:: ValueError – If the stream is closed.

seek(offset, whence=0)[source]

Change the stream position to the given byte offset.

Parameters:

offset (int) – The byte offset relative to the position indicated by whence.
whence (int, optional) – The reference point. SEEK_SET (0) for start of stream, SEEK_CUR (1) for current position, SEEK_END (2) for end of stream. Defaults to SEEK_SET.

Returns:

The new absolute stream position.

Return type:

int

Raises:

ValueError – If the stream is closed or an invalid whence value is provided.

seekable()[source]

Determine if stream navigation is supported.

Returns:: Always returns True if the stream is open.
Return type:: bool
Raises:: ValueError – If the stream is closed.

tell()[source]

Return the current stream position.

Returns:: The current absolute byte offset from the start of the stream.
Return type:: int
Raises:: ValueError – If the stream is closed.

truncate(size=None)[source]

Resize the stream to the given size in bytes.

If the size is smaller than the current size, the stream is truncated.

Parameters:: size (int, optional) – The target size in bytes. If None, truncates to the current stream position. Defaults to None.
Returns:: The new size of the stream.
Return type:: int
Raises:: ValueError – If the stream is closed.

writable()[source]

Determine if the stream supports writing.

Returns:: Always returns True if the stream is open.
Return type:: bool
Raises:: ValueError – If the stream is closed.

write(b)[source]

Write the given bytes-like object to the stream.

Parameters:: b (bytes | bytearray) – The raw binary data to write.
Returns:: The number of bytes successfully written.
Return type:: int
Raises:: ValueError – If the stream is closed.

writelines(lines)[source]

Write a list of lines to the stream.

Parameters:: lines (Any) – An iterable of byte-like objects to write.
Raises:: ValueError – If the stream is closed.

class omni_json_db.jdb_file.JDiskFiles(KEY_file)[source]

Bases: JFilesBase

Production file-system storage driver implementing physical disk storage.

Maps database operations and logical indexing directly to file nodes and segments on the local storage media.

KEY_date()[source]

Extract baseline system epoch unix registration modification timelines indices numbers from files metadata fields layers.

Returns:: Numerical sequence timestamp logging phase alteration points timelines historical shifts.
Return type:: int

KEY_file

KEY_open(mode='rb', buffering=-1, encoding=None, **kwargs)[source]

Acquire persistent transactional stream pointers connected to the core index file.

Parameters:

mode (str, optional) – Target operational mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – IO array sizing buffer limits. Defaults to -1.
encoding (str, optional) – Explicit character translation rules. Defaults to None.
**kwargs – Extra arguments passed down directly to native Python open().

Returns:

Active file stream connecting directly to the index dataset.

Return type:

IO

Raises:

FileNotFoundError – If a lookup fails encountering missing files across specified paths.

KEY_size()[source]

Extract baseline UNIX timestamp marking index file creation/modification.

Returns:: The integer timestamp log from the file system metadata.
Return type:: int

LCK_close()[source]: Disengage isolation streams and safely close the lock file descriptor.

LCK_file

LCK_fp: int | IO | None

LCK_remove()[source]: Purge system lock indicators physically from disk storage.

LCK_rlock(block=False)[source]

Secure a platform-safe shared reader lock blocking writers but enabling read parallelism.

Parameters:: block (bool, optional) – If True, block until the lock becomes available. If False, attempt non-blocking mode. Defaults to False.
Raises:: BlockingIOError – If an exclusive writer is currently active.

LCK_unlock()[source]: Relinquish secured filesystem concurrency locks.

LCK_wlock(block=False)[source]

Secure a platform-safe exclusive write barrier lock blocking parallel transactions.

Parameters:: block (bool, optional) – If True, block until the lock becomes available. If False, attempt non-blocking mode. Defaults to False.
Raises:: BlockingIOError – If existing active transactions (readers or writers) overlap.

VAL_exist(file_id=0)[source]

Validate if a specified value partition file exists on the physical disk.

Parameters:: file_id (int, optional) – Partition locator code integer. Defaults to 0.
Returns:: True if the file exists on the system.
Return type:: bool

VAL_file

VAL_open(file_id=0, mode='rb', buffering=0, encoding=None, **kwargs)[source]

Open a standard file stream for a specific value partition (VAL file).

Parameters:

file_id (int, optional) – The ID of the partition file to open. Defaults to 0.
mode (str, optional) – The file access mode (e.g., 'rb', 'ab'). Defaults to 'rb'.
buffering (int, optional) – Buffer size policy. Defaults to 0.
encoding (str, optional) – Character encoding (only applies to text modes). Defaults to None.
**kwargs – Extra parameters passed to the native Python open().

Returns:

An open file object pointing to the specific storage block file.

Return type:

IO

Raises:

FileNotFoundError – If a read mode targets a non-existent file segment.

VAL_remove(file_id=0)[source]

Delete a physical value partition file from the file system.

Parameters:: file_id (int, optional) – Targeted contents partition index. Defaults to 0.
Returns:: True if the node is successfully unlinked, False otherwise.
Return type:: bool

VAL_size(file_id=0)[source]

Calculate the size of the specific VAL file.

Parameters:: file_id (int, optional) – Partition locator code integer. Defaults to 0.
Returns:: The size in bytes, or -1 if the file does not exist.
Return type:: int

__eq__(obj)[source]

Evaluate if two disk drivers point to the same physical file.

Parameters:: obj (Any) – Candidate comparison storage manager instance.
Returns:: True if path coordinates precisely match.
Return type:: bool

__init__(KEY_file)[source]

Initialize a database management context pointing to real disk storage.

Parameters:

KEY_file (str) – The absolute or relative file path locating the primary database index.

Raises:

TypeError – If KEY_file is not a string.
ValueError – If KEY_file is empty or entirely whitespace.

__repr__()[source]

Generate string descriptions summarizing the active driver configuration.

Returns:: Identity properties presenting the target file layout.
Return type:: str

copy()[source]

Create a duplicate driver instance pointing to the exact same file target.

Returns:: Duplicate disk space storage driver context.
Return type:: JDiskFiles

create_group(name)[source]

Assemble an isolated disk subdirectory tree configured for a partition group.

Parameters:: name (str) – Cluster classification identity label.
Returns:: Dedicated subfolder disk management framework instance.
Return type:: JDiskFiles

dir_name

file_name

fsync(fd)[source]

Force the operating system to flush internal buffers to the physical disk.

Parameters:: fd (int) – Target open file descriptor.
Return type:: None

get_KEY()[source]

Extract the exact physical path to the core key index file.

Returns:: The system descriptor path string.
Return type:: str

get_folder()[source]

Extract the absolute workspace parent directory path.

Returns:: The target directory path.
Return type:: str

get_name()[source]

Extract the specific filename of the database.

Returns:: The base filename string.
Return type:: str

get_path(folder='')[source]

Assemble the absolute path locating the database file.

Parameters:: folder (str, optional) – An optional subdirectory to append. Defaults to ''.
Returns:: The resolved absolute system path.
Return type:: str

group_KEY_file

is_group(KEY_file, name)[source]

Cross-verify group naming structures ensuring correct namespace allocations.

Parameters:

KEY_file (str | JFilesBase) – The file node indicator path.
name (str) – Label matching targeted group workspace boundaries.

Returns:

True if criteria tests locate matching configurations.

Return type:

bool

class omni_json_db.jdb_file.JFilesBase[source]

Bases: object

Abstract Base Class defining the standard interface for database filesystem drivers.

abstractmethod KEY_date()[source]

Return type:: int

abstractmethod KEY_open(mode='rb', buffering=-1, **kwargs)[source]

Return type:: IO

abstractmethod KEY_size()[source]

Return type:: int

abstractmethod LCK_close()[source]

abstractmethod LCK_remove()[source]

abstractmethod LCK_rlock(block=False)[source]

abstractmethod LCK_unlock()[source]

abstractmethod LCK_wlock(block=False)[source]

abstractmethod VAL_exist(file_id=0)[source]

Return type:: bool

abstractmethod VAL_open(file_id=0, mode='rb', buffering=0, **kwargs)[source]

Return type:: IO

abstractmethod VAL_remove(file_id=0)[source]

Return type:: bool

abstractmethod VAL_size(file_id=0)[source]

Return type:: int

abstractmethod copy()[source]

Return type:: JFilesBase

abstractmethod create_group(name)[source]

Return type:: JFilesBase

abstractmethod fsync(fd)[source]

Return type:: None

abstractmethod get_KEY()[source]

Return type:: str

abstractmethod get_folder()[source]

Return type:: str

abstractmethod get_name()[source]

Return type:: str

abstractmethod get_path(folder='')[source]

Return type:: str

abstractmethod is_group(KEY_file, name)[source]

Return type:: bool

class omni_json_db.jdb_file.JMemFiles(KEY_file=None, VAL_table=None, LCK_file=None, lock=None, cond=None, timestamp=None, name=None)[source]

Bases: JFilesBase

In-memory virtual filesystem backend for transient database operations.

Manages layout matrices and dataset segments entirely within RAM using mutable bytearrays, bypassing physical storage devices.

KEY_date()[source]

Get the UNIX timestamp of the memory instance creation.

Returns:: The integer timestamp.
Return type:: int

KEY_file

KEY_open(mode='rb', buffering=-1, **kwargs)[source]

Open a raw stream tracking the primary key index in memory.

Parameters:

mode (str, optional) – Operation modes (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Ignored. Defaults to -1.
**kwargs – Extra attributes.

Returns:

Virtual stream handler managing the master key bytearray.

Return type:

IO

Raises:

FileNotFoundError – If reading is attempted on an uninitialized context.

KEY_size()[source]

Calculate the total size of the key index buffer.

Returns:: The number of bytes tracking the main index.
Return type:: int

LCK_close()[source]: Placeholder system stream shutdown routine. Does nothing in memory mode.

LCK_file

LCK_remove()[source]: Reset concurrency tracker values, clearing the lock bytes structure.

LCK_rlock(block=False)[source]

Acquire a shared reader lock for the memory instance.

Allows multiple threads to read concurrently while blocking write threads.

Parameters:

block (bool, optional) – If True, wait until the lock is available. If False, raise immediately if a writer is active. Defaults to False.

Raises:

BlockingIOError – If an exclusive write lock is held by another thread.
RuntimeError – If the lock file has been marked as closed/removed.

LCK_unlock()[source]: Release session concurrency locks, returning access control to the pool.

LCK_wlock(block=False)[source]

Acquire an exclusive writer lock for the memory instance.

Prevents other threads from reading or writing while held.

Parameters:

block (bool, optional) – If True, wait until the lock is available. If False, raise immediately. Defaults to False.

Raises:

BlockingIOError – If active transaction records indicate overlapping activities.
RuntimeError – If the lock file has been marked as closed/removed.

VAL_exist(file_id=0)[source]

Check if a specific segment block exists in memory.

Parameters:: file_id (int, optional) – The partition ID. Defaults to 0.
Returns:: True if the byte block exists.
Return type:: bool

VAL_open(file_id=0, mode='rb', buffering=0, **kwargs)[source]

Initialize an in-memory file stream for a specific value block.

Parameters:

file_id (int, optional) – The ID of the partition to open. Defaults to 0.
mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Ignored for memory arrays. Defaults to 0.
**kwargs – Extra parameters (ignored).

Returns:

A JBytesIO wrapper for reading and writing memory arrays.

Return type:

IO

VAL_remove(file_id=0)[source]

Clear memory array elements unlinking selected partitions.

Parameters:: file_id (int, optional) – The ID of the partition to delete. Defaults to 0.
Returns:: True if successfully cleared, False if not found.
Return type:: bool

VAL_size(file_id=0)[source]

Calculate the size of a specific in-memory partition block.

Parameters:: file_id (int, optional) – The partition ID. Defaults to 0.
Returns:: The size in bytes, or -1 if the block does not exist.
Return type:: int

VAL_table

__eq__(obj)[source]

Check if two memory instances share the exact same underlying key buffer.

Parameters:: obj (Any) – Target entity evaluation candidate.
Returns:: True if both objects wrap the identical in-memory bytearray.
Return type:: bool

__init__(KEY_file=None, VAL_table=None, LCK_file=None, lock=None, cond=None, timestamp=None, name=None)[source]

Initialize a volatile in-memory storage manager.

Parameters:

KEY_file (bytearray, optional) – Buffer for index mapping. Defaults to a new bytearray.
VAL_table (dict, optional) – Dictionary tracking file_id to content bytearrays.
LCK_file (bytearray, optional) – Mutex tracker array. Defaults to a new bytearray.
lock (Lock, optional) – Primitive synchronization engine.
cond (Condition, optional) – Condition variable for blocking concurrency.
timestamp (float, optional) – Baseline creation timestamp.
name (str, optional) – The virtual file object name.

Raises:

TypeError – If input parameters do not match required native types.

__repr__()[source]

Generate a string representation of the memory file state.

Returns:: Diagnostic telemetry regarding memory allocations.
Return type:: str

cond

copy()[source]

Create a duplicate instance referencing the same memory buffers.

Returns:: A replicated virtual storage controller.
Return type:: JMemFiles

create_group(name)[source]

Create a child dataset partition in memory.

Parameters:: name (str) – The cluster group name.
Returns:: A new empty memory storage manager.
Return type:: JMemFiles

fsync(fd)[source]

Mock file synchronization. Does nothing in memory mode.

Parameters:: fd (int) – Target file descriptor.
Return type:: None

get_KEY()[source]

Get the primary identifier tag for this memory instance.

Returns:: A placeholder string starting with <MEM.
Return type:: str

get_folder()[source]

Get the parent directory path.

Returns:: Always an empty string '' in transient memory environments.
Return type:: str

get_name()[source]

Get the descriptive file signature.

Returns:: The memory signature string including the memory address.
Return type:: str

get_path(folder='')[source]

Resolve the path mapping for the file.

Parameters:: folder (str, optional) – Target layer customization. Defaults to ''.
Returns:: Always an empty string '' in transient memory environments.
Return type:: str

is_group(KEY_file, name)[source]

Validate if the layout keys resolve to a volatile partition context.

Parameters:

KEY_file (str | JFilesBase) – Allocation identifier.
name (str) – Label matching targeted group boundaries.

Returns:

True if the target is a memory group.

Return type:

bool

lock

name

timestamp

omni_json_db.jdb_file.file_rlock(fd, LCK_file, block=False)[source]

Acquire a shared (read) OS-level file lock.

Parameters:

fd (int | IO) – An existing file descriptor or file object. If None or 0, a new descriptor/object will be opened.
LCK_file (str) – The system path pointing to the targeted lock file.
block (bool, optional) – If True, block until the lock can be acquired. If False, attempt non-blocking mode. Defaults to False.

Returns:

The active file descriptor or file object holding the shared lock.

Return type:

int | IO

Raises:

BlockingIOError – If block=False and the lock cannot be acquired immediately because another process holds an exclusive lock.

omni_json_db.jdb_file.file_unlock(fd)[source]

Release the file lock and safely close the file descriptor/object.

Parameters:: fd (int | IO) – The open file descriptor or file object to unlock and close.

omni_json_db.jdb_file.file_wlock(fd, LCK_file, block=False)[source]

Acquire an exclusive (write) OS-level file lock.

Parameters:

fd (int | IO) – An existing file descriptor or file object. If None or 0, a new descriptor/object will be opened.
LCK_file (str) – The system path pointing to the targeted lock file.
block (bool, optional) – If True, block until the lock can be acquired. If False, attempt non-blocking mode. Defaults to False.

Returns:

The active file descriptor or file object holding the exclusive lock.

Return type:

int | IO

Raises:

BlockingIOError – If block=False and the lock cannot be acquired immediately due to existing readers or writers.

omni_json_db.jdb_io

class omni_json_db.jdb_io.DictKeyTable[source]

Bases: dict

Dictionary-backed implementation of KeyTable protocol optimizing fast in-memory lookups.

__missing__(key)[source]

Handle missing keys safely by returning default error indicator value -1.

Parameters:: key (str) – Target lookup indicator.
Returns:: Error code indicating unallocated item references.
Return type:: int

get_mode()[source]

Get the current dictionary matrix classification mode.

Returns:: Code indicator mapping baseline processing profiles rules.
Return type:: int

class omni_json_db.jdb_io.JDbGroupDict[source]

Bases: dict

Custom dictionary implementation returning None instead of throwing KeyError on missing elements.

__missing__(key)[source]

Handle missing keys safely by returning None.

Parameters:: key (Str) – Missing key token descriptor.
Returns:: Fallback placeholder indicator value.
Return type:: None

class omni_json_db.jdb_io.JIo(files_obj, data_type=None, zip_type=None, key_limit=None, api_ver=None, min_value_size=None, index_size=None, max_file_size=None, reserved_rate=None, sync_id=0, swap_id=0, remv_id=0)[source]

Bases: JIoBase

Core processing engine linking pipeline translation modules and file handles.

HEAD_dumps

HEAD_loads

KEY_dumps

KEY_loads

VAL_dumps

VAL_loads

VAL_unzip

VAL_unzip0

VAL_zip

__init__(files_obj, data_type=None, zip_type=None, key_limit=None, api_ver=None, min_value_size=None, index_size=None, max_file_size=None, reserved_rate=None, sync_id=0, swap_id=0, remv_id=0)[source]

Initialize core engine parameters and layout configurations.

Parameters:

files_obj (JFilesBase) – File management abstraction driver context.
data_type (str | int, optional) –
Codec serialization scheme categorization flag.
- ’L+J’ | 1 = KEY=split | VAL=Json
- ’M+M’ | 2 = KEY=Marshal | VAL=Marshal
- ’J+J’ | 3 = KEY=Json | VAL=Json
- ’J+M’ | 4 = KEY=Json | VAL=Marshal
- ’J+P’ | 5 = KEY=Json | VAL=Pickle
- ’S+S’ | 6 = KEY=msgpack | VAL=msgpack
- ’J+S’ | 7 = KEY=Json | VAL=msgpack
- ’S+M’ | 8 = KEY=msgpack | VAL=Marshal
- ’S+J’ | 9 = KEY=msgpack | VAL=Json
- ’S+P’ | 10 = KEY=msgpack | VAL=Pickle
- ’J+Y’ | 11 = KEY=msgpack | VAL=YAML
- ’S+Y’ | 12 = KEY=msgpack | VAL=YAML
zip_type (str | int, optional) –
Target row data level compression profile.
- ’no’ | 0 = no compression for VAL
- ’gz’ | 1 = gzip compression(9) for VAL
- ’bz’ | 2 = bz2 compression(9) for VAL
- ’xz’ | 3 = lzma compression for VAL
- ’zs’ | 4 = zstandard compression(22) for VAL
- ’br’ | 5 = brotli compression(6) for VAL
- ’z1’ | 6 = zstandard compression(6) for VAL
- ’z2’ | 7 = zstandard compression(11) for VAL
- ’lz’ | 8 = lz4 compression(0) for VAL
key_limit (str | int, optional) –
Sizing constraint boundary for index memory.
- ”no” | 0 = use DictKeyTable (dict). (default).
- ”bt” | 0x100 = use BTreeKeyTable.
- ”l0”-“l5” | -ve = use LiteKeyTable (fast load_keys()).
- ”<{n}” | +ve = use PartialKeyTable (fast load_keys()).
api_ver (int, optional) –
Logical structural schema edition index. Defaults to latest.
- 0 = oldest version.
- None = latest version. (default)
min_value_size (int, optional) – Minimal alignment constraint width.
index_size (int, optional) – Fixed byte width defining row segmentation sizes.
max_file_size (int, optional) – Constraint limiting data partitions allocation sizes.
reserved_rate (float, optional) – Expansion reserve factor allocated for updates.
sync_id (int, optional) – Synchronization sequence generation tracker. Defaults to 0.
swap_id (int, optional) – Rearrangement transaction milestone tracking index. Defaults to 0.
remv_id (int, optional) – Accumulative deletions sequence tracker. Defaults to 0.

Raises:

TypeError – If input structural variables violate driver specifications.

__repr__()[source]

Generate structured string summary reports outlining operational engine states parameters configurations specs.

Returns:: Identity presentation string block details tracks logs metrics layout context text.
Return type:: str

api_ver

change_APIs(version=None, data_type=0, zip_type=-1, reset=False)[source]

Re-bind serialization codec abstraction routing pointers across chosen logical engine configuration profiles models.

Parameters:

version (Optional[int], optional) – Target API schema iteration index token code value number. Defaults to None.
data_type (int, optional) – Coding matrix categorization specification number index value. Defaults to DEF_TYPE.
zip_type (int, optional) – Data row compression profiling rule classification identifier. Defaults to DEF_ZIP.
reset (bool, optional) – Obliterate internal state layouts prior to polling system state logs. Defaults to False.

Raises:

TypeError – If input structural identifiers break validation configurations parameters.
ValueError – If an unexpected out-of-bounds format version token encounters tracking pipelines.

copy_key(fp, src_row, dst_row, decode=False)[source]

Duplicate an exact slice of row metadata bytes from one slot address to another slot index line.

Parameters:

fp (IO) – Persistent active streaming framework connection file object.
src_row (int) – Original row source index position number.
dst_row (int) – Destination target row index line location mapping parameters.
decode (bool, optional) – De-serialize and unpack raw duplicated lines properties back into tuple parameters objects instead. Defaults to False.

Returns:

Copied binary stream metadata chunk array, or unpacked items elements tuple.

Return type:

Union[bytes, tuple, list]

property data_type: int

Get operational database layout coding formats parameters targets.

Returns:: Operational mapping category tracking specification number integer.
Return type:: int

property data_type_str: str

Get format encoding specification layout code tokens indicator naming blueprints.

Returns:: Structural layout identifier code string token (e.g., ‘J+S’).
Return type:: str

days

dumps_with_zip(data, zip_type=None)[source]

Compress and serialize values blocks payloads utilizing combined encoder algorithms frameworks pipelines.

Parameters:

data (Any) – Python data primitive object layout candidate.
zip_type (Optional[int], optional) – Custom compression algorithm code tracker identifier index. Defaults to None.

Returns:

Packed compressed structural binary elements track block sequence array.

Return type:

bytes

file_size

file_table

files_obj

get_dead_row(min_row_id, req_size)[source]

Get the matched dead row from DEAD_rows cache.

Parameters:

min_row_id (int) – start row ID
req_size (int) – requested row size

Returns:

row_id, file_id, offset, row_size

Return type:

Tuple[int, int, int, int]

groups

index_size

init_APIs(api_ver, reset=False)[source]

Scan physical descriptor headers logs dynamically setting baseline codecs pipelines matching verified database states blueprints.

Parameters:

api_ver (Optional[int]) – Logical iteration category indicator target index selection token code text format.
reset (bool, optional) – Obliterate operational structures resetting metrics back onto standard initialization defaults. Defaults to False.

is_updated()[source]

Validate transactional chronology alignment verifying if memory arrays match disk headers footprints.

Returns:: True if alignment indicators match active storage timeline parameters perfectly, False otherwise.
Return type:: bool

property key_limit: int

Get memory cache restriction constraint rules selection variables indices numbers.

Returns:: Operational limitations tracking threshold index value integer number.
Return type:: int

property key_limit_str: str

Get structural cache limitation description code tokens.

Returns:: Parsed context representation parameters string layout text format.
Return type:: str

key_table

load_keys(fp, force=False)[source]

Synchronize the master index tracking dataset by parsing the database index file.

Parameters:

fp (IO) – Open index file pointer stream handle.
force (bool, optional) – If True, overrules timeline checks and rebuilds index layouts from zero. Defaults to False.

loads_with_unzip(val_bytes, zip_type=None)[source]

Unpack and decompress values blocks sequences backward reconstructing original Python structures layout instances profiles models parameters data fields fields.

Parameters:

val_bytes (bytes) – Source compressed binary data chunk payload array block sequence input.
zip_type (Optional[int], optional) – Overriding algorithmic category reference number identifier selection indicator value. Defaults to None.

Returns:

Deserialized Python data payload mapping output.

Return type:

Any

max_file_size

min_days

min_value_size

n_lines

n_records

pad(data, max_size=0, no_zip=False)[source]

Prune out padding byte array trailing margins restoring raw compressed string context array.

Parameters:: data (bytes) – Aligned padded binary stream data blocks array.
Returns:: Clean trimmed binary data payload block.
Return type:: bytes

pad0_byte

pad_byte

read_bytes(fp, pos, row_size, val_size)[source]

Extract unparsed continuous byte chunks arrays sequences straight from active storage device sectors indices coordinates paths.

Parameters:

fp (IO) – Persistent active streaming channel handler context.
pos (int) – Absolute destination location offset parameter integer measurement.
row_size (int) – Segment envelope block tracking width parameter.
val_size (int) – True data size.

Returns:

Raw binary block sequence fetched from physical tracks.

Return type:

bytes

read_header(fp)[source]

Parse master configuration descriptor headers grids loading metadata parameters indicators cross-referencing timeline indices numbers.

Parameters:: fp (IO) – Source active streaming channel file pointer wrapper proxy.
Returns:: The synchronized processing engine master instance context reference.
Return type:: JIo

read_key(fp, row_id)[source]

Extract individual item schema parameters matrices fields reading indices configurations records rows.

Parameters:

fp (IO) – Open file pointer registration stream controller instance proxy handle.
row_id (int) – Targeted hardware data space line allocation position slot integer number.

Returns:

Complete row structural metadata metrics (key, file_id, offset, row_size, val_size, ver, days).

Return type:

Tuple[str,int,int,int,int,int,int]

read_value(fp, pos, row_size, val_size)[source]

Extract and deserialize a stored data record from the physical storage.

Parameters:

fp (IO) – Active open file descriptor stream handler.
pos (int) – Core target byte position coordinate indicator.
row_size (int) – Sizing constraint boundary defining row block structural margins.
val_size (int) – Expected unpadded data byte payload length.

Returns:

Unpacked deserialized Python data structure.

Return type:

Any

remv_id

reserved_rate

reset(**kwargs)[source]

Obliterate runtime trackers dropping state variables clearing memory pools tables configurations allocations fields.

Parameters:: **kwargs – Configuration overrides for baseline engine constants (e.g., index_size, reserved_rate).

resize_keys(fp, index_size, min_ver=False)[source]

Re-structure physical index layout files modifying rows padding block sizing constraints permanently.

Parameters:

fp (IO) – Persistent open streaming interface proxy connection file object.
index_size (int) – Target row byte allocation width constraint parameter integer number.
min_ver (bool, optional) – Overrule version trackers initializing sequential timeline markers coordinates limits fields back onto compressed baselines. Defaults to False.

row_bytes

seek(fp, row_id)[source]

Reposition system storage stream pointer coordinates directly targeting selected index row boundaries blocks fields.

Parameters:

fp (IO) – Target active open file object interface streaming channel handle.
row_id (int) – Absolute or negative index tracking row target selector integer position number.

Returns:

The newly repositioned file navigation pointer absolute byte index address location.

Return type:

int

shift_keys(fp, start, offset=1, size=1, block_size=None)[source]

Displace continuous series of index row metadata entries horizontally to allocate open layout rows block zones.

Parameters:

fp (IO) – Destination open streaming stream file handler context.
start (int) – Absolute baseline rows row index coordinate position where shifting procedures activate.
offset (int, optional) – Relocation displacement coefficient multiplier integer adjusting target rows coordinates. Defaults to 1.
size (int, optional) – Combined length measure tracking total logical rows objects to shift. Defaults to 1.
block_size (Optional[int], optional) – Internal parsing lookahead width constraining buffered file operations rows loops. Defaults to None.

sorted_key_table_items(start_row=0, stop_row=-1, copy=False, reverse=False)[source]

Generate chronologically ordered or reverse ordered key index entries pairs collections sequences.

Parameters:

start_row (int, optional) – start KEY row index, Defaults to 0
stop_row (int, optional) – stop KEY row index, Default to -1 == end of record
copy (bool, optional) – Force safe execution isolation boundaries by duplicating indices structures tracks first. Defaults to False.
reverse (bool, optional) – Flip direction output forcing descending trajectory parsing flows instead. Defaults to False.

Yields:

Tuple[str, int] – Entry identity string descriptor paired along active logical index row line identifier number.

swap_id

sync_id

unpad(data)[source]

Prune out padding byte array trailing margins restoring raw compressed string context array.

Parameters:: data (bytes) – Aligned padded binary stream data blocks array.
Returns:: Clean trimmed binary data payload block.
Return type:: bytes

unzip(data, zip_type=None)[source]

Decompress data blocks sequences backward returning baseline raw serialization strings contents arrays.

Parameters:

data (bytes) – Input compressed binary payload segment array block.
zip_type (Optional[int], optional) – Overriding codec rule selector index option parameter integer. Defaults to None.

Returns:

Decompressed raw byte block string.

Return type:

bytes

Raises:

ValueError – If decompression routines hit unrecoverable stream corruptions parameters markers fields.

update_days()[source]

Query host clock registers re-aligning tracking timestamp offset integer representations variables.

Returns:: Updated sequence number indicator mapping active relative day metrics thresholds.
Return type:: int

update_file_table()[source]

Scan all VAL files and update the max size for each VAL file.

Return type:: None

window_size

write_header(fp, truncate=False)[source]

Commit production database status configuration descriptors templates header schemas directly into metadata boundaries fields.

Parameters:

fp (IO) – Destination active streaming interface pipeline driver handle context.
truncate (bool, optional) – Force physical truncation pruning obsolete residual data rows block remnants away. Defaults to False.

Returns:

Calculated total byte storage width capacity logged after header updates execution completes.

Return type:

int

write_key(fp, row_id, key, file_id, offset, row_size, val_size=0, ver=None, days=-1)[source]

Commit structured individual key mapping elements definitions metadata straight into active tracking index slots.

Parameters:

fp (IO) – Destination open file descriptor stream handler context.
row_id (int) – Hardware space line allocation alignment position coordinate number integer value.
key (str) – Unique data reference lookup descriptor name string token formatting layout context.
file_id (int) – Segment data section classification index identifier value number code.
offset (int) – Absolute hardware capacity cursor position displacement indicator.
row_size (int) – Allocated byte length ceiling constraining row segment storage space tracks.
val_size (int, optional) – True byte length occupied by payload content items strings. Defaults to 0.
ver (Optional[int], optional) – Synchronization transaction generation code index tracker. Defaults to None.
days (int, optional) – Relative calendar sequence tracking day mapping metrics value number integer. Defaults to -1.

Returns:

Total absolute verification measurement count bytes committed into physical files.

Return type:

int

static z_conv_date(days)[source]

Convert relative day integers back into structured standard timezone-agnostic calendar object dates.

Parameters:: days (int) – Compact relative timeline offset value tracking variable inside index row.
Returns:: Pair processing baseline baseline dates and updated adaptation tracking timeline pointers.
Return type:: Tuple[dt_date, dt_date]

static z_conv_days(timestamp)[source]

Compute the relative day integer offset from the baseline date.

Parameters:: timestamp (int | float | datetime | dt_date) – The target timestamp.
Returns:: The absolute day index number.
Return type:: int

static z_conv_str_to_days(val)[source]

Parse raw textual timestamp representation parameters expressions converting fields directly to unified day numbers integers.

Parameters:: val (str) – Human readable raw calendar date text sequence string (e.g., ‘YYYY-MM-DD’).
Returns:: Compact integer measurement mapping day metrics boundaries positions indices numbers parameters logs.
Return type:: int
Raises:: ValueError – If alphanumeric parsing patterns break constraint definitions templates format specifications.

static z_data_type_str(data_type)[source]

Convert serialization schema format integer targets into layout identification token code strings.

Parameters:: data_type (int) – Type index value number.
Returns:: Operational configuration layout nomenclature label text (e.g., ‘J+S’).
Return type:: str
Raises:: ValueError – If an unrecognized layout configuration category code is matched.

static z_key_limit_str(key_limit)[source]

Translate structural cache constraint parameters integers into readable indicator codes text specifications.

Parameters:: key_limit (int) – Underlying memory limitation capacity bounds code index number integer.
Returns:: Readable constraint description format string token.
Return type:: str

static z_zip_type_str(zip_type)[source]

Convert a numerical compression classification token into its short string name.

Parameters:: zip_type (int) – Compression indicator number.
Returns:: Target nomenclature identity label (e.g., 'zs', 'gz', 'no').
Return type:: str
Raises:: ValueError – If an unknown compression type integer is provided.

zip(data, zip_type=None)[source]

Compress raw binary block sequence elements utilizing active chosen format algorithms drivers factories.

Parameters:

data (bytes) – Target binary payload block array string input context.
zip_type (Optional[int], optional) – Overriding specification targeting alternative compress parameters rules. Defaults to None.

Returns:

Compressed block sequence output data.

Return type:

bytes

Raises:

ValueError – If compressor engine throws system level error conditions.

property zip_type: int

Get or set compression rules profiles specifications integers indices tokens.

Returns:: Structural algorithmic classification identifier number.
Return type:: int

property zip_type_str: str

Get the compression configuration format profile nomenclature string.

Returns:: Identity code string token mapping algorithmic targets (e.g., ‘zs’, ‘no’).
Return type:: str

class omni_json_db.jdb_io.LiteKeyTable(jio, mode=0)[source]

Bases: KeyTable

Ultra compact text index manager replacing standard dictionary spaces models entirely with serialized byte arrays.

Saves device runtime environments storage footprints overhead inside system execution memory layers grids.

__init__(jio, mode=0)[source]

Initialize compact storage partitions maps arrays based on specialized mask profiling parameters rules.

Parameters:

jio (JIo) – Active pipeline transaction driver routing local configuration properties.
mode (int, optional) – Sizing constraints profile configuration indicator value. Defaults to 0.

Raises:

ValueError – If an unexpected out-of-bounds mode tier is passed.

copy()[source]

Construct replica instances duplication frameworks copying binary data tracking targets indicators context.

Returns:: Cloned alternative index workspace data object manager framework handle.
Return type:: LiteKeyTable

get_mode()[source]

Extract the exact active masking operational mode code index number integer.

Returns:: Tracking classification setting variable.
Return type:: int

mode

class omni_json_db.jdb_io.PartialKeyTable(jio)[source]

Bases: KeyTable

Memory-efficient key indexing proxy utilizing bitarrays and sparse object cache pipelines.

Postpones loading full keys sets from physical devices disks by maintaining localized bloom filter configurations trackers.

__init__(jio)[source]

Initialize partial tracking layers parsing data indices boundaries criteria metrics models.

Parameters:: jio (JIo) – Active pipeline transaction driver routing local configuration properties.

cache: Dict[str, int]

copy()[source]

Construct replica instances duplication frameworks copying active filter arrays signatures matrices layers.

Returns:: Carbon copy replication workspace object context wrapper tracker handle.
Return type:: PartialKeyTable

files_obj

flags

flags_mask

found_flags

groups: List[bytearray]

io

mask

size

with_cache

omni_json_db.jdb_io.frozenset_representer(dumper, data)[source]

omni_json_db.jdb_lite

class omni_json_db.jdb_lite.JDbKey(jdb)[source]

Bases: object

A lightweight, read-only interface for interacting strictly with the keys of a JDbReader instance.

__add__(keys)[source]

Return the union of current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to add.
Returns:: The resulting union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb.keys + {'new_user'}
{'user_1', 'user_2', 'new_user'}

__and__(keys)[source]

Return the intersection of current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to intersect with.
Returns:: The intersection set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb.keys & {'user_1', 'missing_user'}
{'user_1'}

__call__(keys=None, vals=None, date=None, limit=0, **kwargs)[source]

Execute a search query returning matching keys as a generator.

Parameters:

keys (Any, optional) – Condition for filtering keys. Defaults to None.
vals (Any, optional) – Condition for filtering values. Defaults to None.
date (Any, optional) – Date range filter. Defaults to None.
limit (int, optional) – Maximum number of results to yield. Defaults to 0 (no limit).
**kwargs – Additional filtering arguments.

Yields:

str – Matched key.

Example

>>> jdb = JDb()
>>> jdb += {'key1':[0,1], 'key2':[1,2], 'key3':[3,4,5]}
>>> print(set(jdb.keys(r'[12]$', ANY=2)))
{'key2'}
>>> print(set(jdb.keys(HAS=3))) # any record contains 3
{'key3'}

__contains__(keys)[source]

Check if the current key table is a superset of the provided keys.

Parameters:: keys (Set[str]) – A set of keys to check.
Returns:: True if all provided keys exist in the database, False otherwise.
Return type:: bool

Example

>>> jdb = JDb()
>>> jdb['user_1', 'user_2', 'user_3'] = 0
>>> {'user_1', 'user_2'} in jdb.keys
True

__delitem__(key)[source]

Prevent item deletion from a read-only key interface.

Parameters:: key (Any) – The storage key to remove.
Raises:: AttributeError – Always raised to enforce read-only integrity.

__eq__(keys)[source]

Compare the current keys with another collection or database.

Parameters:: keys (set | dict | JDbReader | JDbKey) – The target to compare against.
Returns:: True if the keys are identical, False otherwise.
Return type:: bool

Example

>>> jdb = JDb()
>>> jdb['user_1', 'user_2'] = 0
>>> jdb.keys == {'user_1', 'user_2'}
True

__getitem__(key)[source]

Retrieve key metadata or filter keys based on a variety of condition types.

Parameters:

key (Any) –

The filter criteria.

str | bool | bytes
- val = jdb.keys[‘name’]
Condition
- val = jdb.keys[Query().name.startswith(‘A’’)]

slice | date | datetime | float | int

>>> matches = jdb.keys[date(2020,1,1)::r'key[0-9]'] # get date from 2020-1-1 to now key and match r'key[0-9]'
>>> matches = jdb.keys[:100:r'key[0-9]'] # get 1-100th row keys and match r'key[0-9]'
>>> matches = jdb.keys[date.today()]     # get today modified/new keys
>>> matches = jdb.keys[datetime.now()]   # get today new keys
>>> matches = jdb.keys[1:10:2]   # get 2nd - 9th and step=2 key info
>>> matches = jdb.keys[-10.:]    # get key info and match sync_id
>>> matches = jdb.keys[:]        # get all key info
>>> matches = jdb.keys[0]        # get 1st key info
>>> matches = jdb.keys[-1]       # get last key info
>>> matches = jdb.keys[0]        # get 1st key info
>>> matches = jdb.keys[-1]       # get last key info
>>> matches = jdb.keys[-1.]      # get all key info which sync_id is matched

re.Pattern

>>> matches = jdb.keys[re.compile(r'key[0-9]')]

function(k,v)

>>> matches = jdb.keys[lambda k,v: k.startswith('key')]
>>> matches = jdb.keys[lambda k,v: v == 10]

function(k)

>>> matches = jdb.keys[lambda k: k[0] == 'k']

tuple | set | list | dict

>>> matches = jdb.keys[1, 2, 3, 'a']
>>> matches = jdb.keys[(1, 2, 3, 'a')]
>>> matches = jdb.keys[{1, 2, 3, 'a'}]
>>> matches = jdb.keys[[1, 2, 3, 'a']]
>>> matches = jdb.keys[{1:0, 2:1, 3:2, 'a':3}]

Returns:

Metadata tuple if a single string is passed, a dictionary of matched keys to their metadata, or None if not found.

Return type:

dict | tuple | None

__init__(jdb)[source]

Initialize the JDbKey instance.

Parameters:: jdb (JDbReader) – The parent database reader instance to bind to.

__iter__()[source]

Iterate over all keys present in the database.

Yields:: str – The next key in the database.

__len__()[source]

Get the total number of records in the associated database.

Returns:: The record count.
Return type:: int

__or__(keys)[source]

Return the union of current keys and the provided set using the bitwise OR operator.

Parameters:: keys (Set[str]) – The keys to unify.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb.keys | {'new_user'}
{'user_1', 'user_2', 'new_user'}

__radd__(keys)[source]

Right-side addition (union) operation.

Parameters:: keys (Set[str]) – The set to add.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'new_user'} + jdb.keys
{'user_1', 'user_2', 'new_user'}

__rand__(keys)[source]

Right-side bitwise AND (intersection) operation.

Parameters:: keys (Set[str]) – The set to intersect.
Returns:: The intersection set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'missing_user'} & jdb.keys
{'user_1'}

__repr__()[source]

Return the string representation of the JDbKey instance.

Returns:: The object’s memory address and class name.
Return type:: str

__ror__(keys)[source]

Right-side bitwise OR (union) operation.

Parameters:: keys (Set[str]) – The set to unify.
Returns:: The union set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'new_user'} | jdb.keys
{'user_1', 'user_2', 'new_user'}

__rsub__(keys)[source]

Right-side subtraction (difference) operation.

Parameters:: keys (Set[str]) – The baseline set.
Returns:: Elements in the given set but not in the database.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'new_user'} - jdb.keys
{'new_user'}

__rxor__(keys)[source]

Right-side bitwise XOR (symmetric difference) operation.

Parameters:: keys (Set[str]) – The set to compare.
Returns:: The symmetric difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> {'user_1', 'new_user'} ^ jdb.keys
{'user_2', 'new_user'}

__setitem__(key, val)[source]

Prevent item modification on a read-only key interface.

Parameters:

key (Any) – The storage key or identifier.
val (Any) – The value payload to assign.

Raises:

AttributeError – Always raised to enforce read-only integrity.

Return type:

None

__sub__(keys)[source]

Return the difference between current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to subtract.
Returns:: The resulting difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {f'user_{v+1}':v for v in range(3)}
>>> jdb.keys - {'user_1'}
{'user_2', 'user_3'}

__xor__(keys)[source]

Return the symmetric difference between current keys and the provided set.

Parameters:: keys (Set[str]) – The keys to compare.
Returns:: The symmetric difference set.
Return type:: Set[str]

Example

>>> jdb = JDb()
>>> jdb += {'user_1':1, 'user_2':2}
>>> jdb.keys ^ {'user_1', 'new_user'}
{'user_2', 'new_user'}

difference(keys)[source]

Calculate the difference between database keys and the provided set.

Parameters:: keys (Set[str]) – The set to subtract.
Returns:: The difference set.
Return type:: Set[str]

has(key)[source]

Check if a specific key exists in the database.

Parameters:: key (str) – The key to locate.
Returns:: True if the key exists, False otherwise.
Return type:: bool

has_all(keys)[source]

Check if all keys from the provided set exist in the database.

Parameters:: keys (Set[str]) – The keys to search for.
Returns:: True if all keys match, False otherwise.
Return type:: bool

has_any(keys)[source]

Check if at least one key from the provided set exists in the database.

Parameters:: keys (Set[str]) – The keys to search for.
Returns:: True if any key matches, False otherwise.
Return type:: bool

intersection(keys)[source]

Calculate the intersection between database keys and the provided set.

Parameters:: keys (Set[str]) – The set to intersect.
Returns:: The intersected set.
Return type:: Set[str]

is_disjoint(keys)[source]

Check if the database key table and the provided set have no keys in common.

Parameters:: keys (Set[str]) – The set to check.
Returns:: True if disjoint, False otherwise.
Return type:: bool

is_subset(keys)[source]

Check if all database keys exist within the provided set.

Parameters:: keys (Set[str]) – The set to check against.
Returns:: True if it is a subset, False otherwise.
Return type:: bool

is_superset(keys)[source]

Check if the database key table contains all keys in the provided set.

Parameters:: keys (Set[str]) – The set to check.
Returns:: True if it is a superset, False otherwise.
Return type:: bool

item_iter(key=None)[source]

Iterate over keys and their corresponding metadata tuples based on filter criteria.

Parameters:

key (Optional[Any], optional) –

Filtering criteria (slice, date, regex, etc.). Defaults to None.

str | bool | bytes

>>> matches = jdb.keys['name']
>>> matches = jdb.key['child:::name']
>>> matches = jdb.key[':::name']

int

>>> matches = jdb.keys[1]             # get 2nd line row key info
>>> matches = jdb.keys[-1]            # get last line row key info

float

>>> matches = jdb.keys[-1.]      # get all key info which sync_id is matched

slice | date | datetime | Conditon

>>> matches = jdb.keys[date(2020,1,1)::r'key[0-9]'] # get date from 2020-1-1 to now key and match r'key[0-9]'
>>> matches = jdb.keys[:100:r'key[0-9]'] # get 1-100th row keys and match r'key[0-9]'
>>> matches = jdb.keys[date.today()]     # get today modified/new keys
>>> matches = jdb.keys[datetime.now()]   # get today new keys
>>> matches = jdb.keys[1:10:2]   # get 2nd - 9th and step=2 key info
>>> matches = jdb.keys[-10.:]    # get key info and match sync_id
>>> matches = jdb.keys[:]        # get all key info
>>> matches = jdb.keys[Query().name.endswith('e')]

re.Pattern

>>> matches = jdb.keys[re.compile(r'key[0-9]')]

function(k,v)

>>> matches = jdb.keys[lambda k,v: k.startswith('key')]
>>> matches = jdb.keys[lambda k,v: v == 10]

function(k)

>>> matches = jdb.keys[lambda k: k[0] == 'k']

tuple | set | list | dict

>>> matches = jdb.keys[1, 2, 3, 'a']
>>> matches = jdb.keys[(1, 2, 3, 'a')]
>>> matches = jdb.keys[{1, 2, 3, 'a'}]
>>> matches = jdb.keys[[1, 2, 3, 'a']]
>>> matches = jdb.keys[{1:0, 2:1, 3:2, 'a':3}]

None: get all items

>>> all_keys = dict(jdb.keys.item_iter(None))

Yields:

Tuple[str, tuple]

[0] key

[1] tuple

[0] row_id:int

[1] file_id:int

[2] offset:int

[3] row_size:int

[4] val_size:int

[5] version:int

[6] days:int - combine modified date + created date

[7] modified date: str (eg. ‘2000-01-01’)

[8] created date: str (eg. ‘2000-01-01’)

items()[source]

Iterate over all keys and their metadata tuples.

Yields:

Tuple[str, tuple]

[0] key

[1] tuple

[0] row_id:int

[1] file_id:int

[2] offset:int

[3] row_size:int

[4] val_size:int

[5] version:int

[6] days:int - combine modified date + created date

[7] modified date: str (eg. ‘2000-01-01’)

[8] created date: str (eg. ‘2000-01-01’)

jdb: JDbReader

joint(keys)[source]

Find the intersection (joint) between this database keys and the provided set.

Parameters:: keys (Set[str]) – The set of keys to check.
Returns:: The intersected set of keys.
Return type:: Set[str]

non_intersection(keys)[source]

Calculate the non-intersecting elements (symmetric difference).

Parameters:: keys (Set[str]) – The set to compare.
Returns:: Elements in either sets but not both.
Return type:: Set[str]

non_joint(keys)[source]

Find keys that are strictly in this database but not in the provided set.

Parameters:: keys (Set[str]) – The set of keys to exclude.
Returns:: The set of non-joint keys.
Return type:: Set[str]

symmetric_difference(keys)[source]

Alias for non_intersection. Calculate the symmetric difference.

Parameters:: keys (Set[str]) – The set to compare.
Returns:: The symmetric difference set.
Return type:: Set[str]

union(keys)[source]

Combine current database keys with the provided set.

Parameters:: keys (Set[str]) – The keys to unite.
Returns:: The combined set.
Return type:: Set[str]

values()[source]

Iterate over all metadata tuples without their keys.

Yields:

tuple –

The metadata tuple for each key.

[0] row_id:int

[1] file_id:int

[2] offset:int

[3] row_size:int

[4] val_size:int

[5] version:int

[6] days:int - combine modified date + created date

[7] modified date: str (eg. ‘2000-01-01’)

[8] created date: str (eg. ‘2000-01-01’)

omni_json_db.jdb_net

class omni_json_db.jdb_net.JErrCode(value)[source]

Bases: IntFlag

Enumeration flags representing database and network error codes.

BLOCK_IO = 8192

FAIL_CALL = 512

FAIL_OPEN = 16

INVALID_ARGS = 8

INVALID_CMD = 4

INVALID_FMT = 1

INVALID_ID = 2

INVALID_VAL = 256

NOT_FOUND = 4096

OKAY = 0

class omni_json_db.jdb_net.JNetFiles(address=('127.0.0.1', 59898))[source]

Bases: JFilesBase

Network proxy client implementing the JFilesBase filesystem driver.

Routes file system operations to a remote ThreadedTCPServer database instance.

KEY_date()[source]

Get the UNIX timestamp of the remote main index file modification.

Returns:

The epoch timestamp.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

KEY_open(mode='rb', buffering=-1, **kwargs)[source]

Open a network stream to read or write the remote main index (KEY) file.

Parameters:

mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Buffer allocation boundaries. Defaults to -1.
**kwargs – Extra parameters passed to the remote driver.

Returns:

A JNetIO stream controller object.

Return type:

IO

Raises:

IOError – If the network socket is disconnected.

KEY_size()[source]

Get the total byte size of the remote main index (KEY) file.

Returns:

The size in bytes.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

LCK_close()[source]: Safely close lock channels to prevent remote resource starvation.

LCK_remove()[source]

Delete the lock file physically from the remote server.

Raises:: RuntimeError – If the network socket is disconnected or fails.

LCK_rlock(block=False)[source]

Acquire a shared reader lock on the remote server.

Parameters:

block (bool, optional) – If True, block until acquired. Defaults to False.

Raises:

BlockingIOError – If an exclusive writer lock is currently active.
RuntimeError – If a general connection or internal state error occurs.

LCK_unlock()[source]

Release any held locks on the remote server.

Raises:

BlockingIOError – If the unlock command is rejected.
RuntimeError – If a general connection or internal state error occurs.

LCK_wlock(block=False)[source]

Acquire an exclusive writer lock on the remote server.

Parameters:

block (bool, optional) – If True, block until acquired. Defaults to False.

Raises:

BlockingIOError – If any lock (read or write) is currently active.
RuntimeError – If a general connection or internal state error occurs.

VAL_exist(file_id=0)[source]

Check if a specific value partition exists on the remote server.

Parameters:

file_id (int, optional) – The partition ID to check. Defaults to 0.

Returns:

True if the partition exists.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

VAL_open(file_id=0, mode='rb', buffering=0, **kwargs)[source]

Open a network stream to read or write a specific remote value partition.

Parameters:

file_id (int, optional) – The partition ID to open. Defaults to 0.
mode (str, optional) – Access mode (e.g., 'rb'). Defaults to 'rb'.
buffering (int, optional) – Buffer limits. Defaults to 0.
**kwargs – Extra parameters passed to the remote driver.

Returns:

A JNetIO stream controller object.

Return type:

IO

Raises:

IOError – If the network socket is disconnected.

VAL_remove(file_id=0)[source]

Delete a specific value partition file on the remote server.

Parameters:

file_id (int, optional) – The partition ID to remove. Defaults to 0.

Returns:

True if successfully deleted by the server.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

VAL_size(file_id=0)[source]

Get the byte size of a remote value partition.

Parameters:

file_id (int, optional) – The partition ID to measure. Defaults to 0.

Returns:

The size in bytes, or -1 if it does not exist.

Return type:

int

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

__del__()[source]: Disconnect the socket cleanly upon garbage collection.

__eq__(obj)[source]

Check if two network clients point to the same server address.

Parameters:: obj (Any) – The candidate client to compare.
Returns:: True if the server addresses match exactly.
Return type:: bool

__init__(address=('127.0.0.1', 59898))[source]

Initialize the network database client.

Parameters:: address (Tuple[str, int], optional) – A tuple containing the host IP and port. Defaults to ('127.0.0.1', 59898).
Raises:: RuntimeError – If the socket connection fails.

__repr__()[source]

Return a string representation of the network client configuration.

Return type:: str

copy()[source]

Create a duplicate client connected to the same server address.

Returns:: A new network connection context proxy.
Return type:: JNetFiles
Raises:: IOError – If the original socket is closed.

create_group(name)[source]

Attempt to spawn a child group over the network.

Parameters:

name (str) – The group namespace.

Raises:

RuntimeError – Always raised, as remote multi-group creation is disallowed.
IOError – If the network socket is disconnected.

Return type:

JFilesBase

fsync(fd)[source]

Force the remote server to write buffers to the physical disk.

Parameters:

fd (int) – Target file descriptor.

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote fsync command fails.

Return type:

None

get_KEY()[source]

Get the primary identifier path for the remote database index.

Returns:

The master key identifier from the remote server.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_folder()[source]

Get the parent directory path of the remote database.

Returns:

The absolute directory path on the remote machine.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_name()[source]

Get the specific filename of the remote database.

Returns:

The filename string from the remote server.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

get_path(folder='')[source]

Resolve the absolute physical path to the remote database.

Parameters:

folder (str, optional) – A subdirectory to append. Defaults to ''.

Returns:

The resolved absolute path on the remote machine.

Return type:

str

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

is_group(KEY_file, name)[source]

Validate if a path belongs to a named database group on the remote server.

Parameters:

KEY_file (str | JFilesBase) – The file node indicator path.
name (str) – Label matching targeted group workspace boundaries.

Returns:

True if the group validation succeeds on the server.

Return type:

bool

Raises:

IOError – If the network socket is disconnected.
ValueError – If the remote command fails.

server_addr

sock

class omni_json_db.jdb_net.JNetIO(sock, file, mode='rb+', lock=None, **kwargs)[source]

Bases: RawIOBase

Simulates a file-like stream object over a TCP network connection.

Translates native I/O stream methods into network commands routed to a remote database server.

__del__()[source]: Safely close the stream context upon garbage collection.

__init__(sock, file, mode='rb+', lock=None, **kwargs)[source]

Initialize the network-backed file I/O stream.

Parameters:

sock (socket.socket) – Active network socket connected to the remote host.
file (str) – File identity profile path (e.g., 'KEY', 'VAL.0').
mode (str, optional) – Target access mode. Defaults to 'rb+'.
lock (RLock, optional) – Lock for socket operation
**kwargs – Extra parameters passed to the remote open command.

Raises:

TypeError – If the socket or filename variables are invalid.

__repr__()[source]

Return a string representation of the network stream context.

Return type:: str

close()[source]: Disconnect and release the remote file handle on the server.

file

fileno()[source]

Return the underlying file descriptor.

Returns:: Returns -1 since this is a network proxy interface, or as returned by the remote server.
Return type:: int

flush()[source]

Flush the write buffers on the remote server.

Does nothing for read-only or non-blocking streams.

Raises:: FileNotFoundError – If the server cannot find the target file to flush.
Return type:: None

lock

mode

not_found

open(*args, **kwargs)[source]

Transmit an open command to configure the remote file handle.

Parameters:

*args – Variable arguments for the remote file driver.
**kwargs – Keyword arguments for the remote file driver.

Raises:

FileNotFoundError – If the remote file does not exist.
ValueError – If the remote server returns an error code.

read(size=-1)[source]

Read bytes from the remote stream.

Parameters:: size (int, optional) – The maximum number of bytes to read. Defaults to -1.
Returns:: The binary data extracted from the remote storage.
Return type:: bytes
Raises:: ValueError – If the stream is closed, or if the server returns an error.

readable()[source]

Determine if the stream supports reading.

Returns:: Always returns True if the stream is open.
Return type:: bool

readall()[source]

Read all remaining bytes from the remote stream.

Returns:: The remaining binary data.
Return type:: bytes
Raises:: ValueError – If the stream is closed, or if the server returns an error.

readinto(b)[source]

Read bytes directly into a pre-allocated buffer from the network.

Parameters:: b (Any) – The mutable destination buffer to populate.
Returns:: The number of bytes successfully mapped.
Return type:: int
Raises:: ValueError – If the stream is closed, or if the server returns an error.

readline(size=-1)[source]

Read a single line from the remote stream.

Parameters:: size (int, optional) – The maximum number of bytes to read. Defaults to -1.
Returns:: The extracted line from the remote server.
Return type:: bytes
Raises:: ValueError – If the stream is closed, or if the server returns an error.

readlines(size=None)[source]

Read and return a list of lines from the remote stream.

Parameters:: size (int, optional) – The maximum number of bytes to read. Defaults to None.
Returns:: A list of byte strings, each representing a line.
Return type:: list
Raises:: ValueError – If the stream is closed, or if the server returns an error.

seek(offset, whence=0)[source]

Change the stream position on the remote server.

Parameters:

offset (int) – The byte offset to move.
whence (int, optional) – The reference point (0: start, 1: current, 2: end). Defaults to 0.

Returns:

The new absolute position returned by the server.

Return type:

int

Raises:

ValueError – If the stream is closed, or if the server returns an error.

seekable()[source]

Determine if stream navigation is supported.

Returns:: Always returns True if the stream is open.
Return type:: bool

sock

tell()[source]

Return the current stream position from the remote server.

Returns:: The current byte address index.
Return type:: int
Raises:: ValueError – If the stream is closed, or if the server returns an error.

truncate(size=None)[source]

Resize the remote file to the given size.

Parameters:: size (int, optional) – The target size in bytes. Defaults to None.
Returns:: The new terminal boundary length.
Return type:: int
Raises:: ValueError – If the stream is closed, or if the server returns an error.

writable()[source]

Determine if the stream supports writing.

Returns:: returns True if the stream is writable.
Return type:: bool

write(b)[source]

Write raw binary data to the remote server.

Parameters:: b (bytes | bytearray) – The raw binary payload to dispatch.
Returns:: The number of bytes successfully written to the remote storage.
Return type:: int
Raises:: ValueError – If the stream is closed, or if the server returns an error.

writelines(lines)[source]

Write an iterable list of lines to the remote server.

Parameters:: lines (Any) – An iterable of byte strings to write.
Raises:: ValueError – If the stream is closed, or if the server returns an error.

omni_json_db.jdb_net.dump_and_send(sock, obj)[source]

Serialize an object into MsgPack format and transmit it over a TCP socket.

Prepends an 8-byte aligned synchronization header before sending the data.

Parameters:

sock (socket.socket) – The destination network socket.
obj (Any) – The payload dictionary or object to transmit.

omni_json_db.jdb_net.recv_and_load(sock)[source]

Receive a network packet and decode its MsgPack payload.

Parameters:: sock (socket.socket) – The active network socket connection.
Returns:: The unpacked Python object from the network transmission.
Return type:: Any
Raises:: ValueError – If the payload header signature is corrupted or invalid.

omni_json_db.jdb_net.recv_exactly(sock, size)[source]

Receive an exact amount of bytes from a TCP socket, aligned to 8-byte boundaries.

Parameters:

sock (socket.socket) – The active network socket connection.
size (int) – The target payload length in bytes before alignment.

Returns:

The raw data received from the socket.

Return type:

bytes

Raises:

EOFError – If the socket connection closes before the expected bytes are received.

omni_json_db.jdb_query

class omni_json_db.jdb_query.Condition[source]

Bases: dict

Represents a logical query condition, inheriting from dict.

Provides overloaded bitwise operators to easily combine multiple query conditions using MongoDB-style logical operators ($and, $or, $not).

__and__(other)[source]

Combine two conditions using the logical AND (&) operator.

Parameters:: other (Condition) – The condition to combine with the current one.
Returns:: A new Condition wrapped in an $and operator array.
Return type:: Condition

__invert__()[source]

Negate the current condition using the logical NOT (~) operator.

Returns:: A new Condition wrapped in a $not operator dictionary.
Return type:: Condition

__missing__(key)[source]

Handle missing keys by providing default empty structures for logical operators.

Parameters:: key (str) – The requested dictionary key.
Returns:: [] for $and/$or, or {} for $not.
Return type:: Any
Raises:: KeyError – If the key is not a recognized logical operator.

__or__(other)[source]

Combine two conditions using the logical OR (|) operator.

Parameters:: other (Condition) – The condition to combine with the current one.
Returns:: A new Condition wrapped in an $or operator array.
Return type:: Condition

copy()[source]

Create a shallow copy of the Condition.

Returns:: A new Condition instance with identical key-value pairs.
Return type:: Condition

class omni_json_db.jdb_query.Query(_path='')[source]

Bases: object

A builder class for constructing MongoDB-style query dictionaries safely.

Provides a fluent, Pythonic interface to generate query filters using magic methods (==, >) and chained method calls.

Parameters:: _path (str, optional) – The initial path segment for the query. Defaults to ''.

Example

>>> q = Query()
>>> condition = (q.age > 18) & (q.name.startswith("Al"))
>>> print(condition)
Condition({'$and': [{'age': {'$gt': 18}}, {'name': {'$sw': 'Al'}}]})

__eq__(val)[source]

Build an equality condition (==).

Return type:: Condition

__ge__(val)[source]

Build a greater-than-or-equal condition (>=). Maps to $gte.

Return type:: Condition

__getattr__(name)[source]

Extend the query path using attribute access (e.g., q.user.name).

Return type:: Query

__getitem__(segment)[source]

Extend the query path using item access (e.g., q['user']['name']).

Return type:: Query

__gt__(val)[source]

Build a greater-than condition (>). Maps to $gt.

Return type:: Condition

__le__(val)[source]

Build a less-than-or-equal condition (<=). Maps to $lte.

Return type:: Condition

__lt__(val)[source]

Build a less-than condition (<). Maps to $lt.

Return type:: Condition

__ne__(val)[source]

Build a not-equal condition (!=). Maps to $ne.

Return type:: Condition

abs()[source]

Apply abs() in the path chain. Maps to $abs.

Return type:: Query

Example

>>> Query().delta.abs_() < 0.1
Condition({'delta.$abs': {'$lt': 0.1}})

any_in(col)[source]

Check if any element of the target iterable exists within the provided collection. Maps to $anyin.

Return type:: Condition

avg()[source]

Apply arithmetic mean in the path chain. Maps to $avg.

Returns None (no-match) for empty sequences.

Return type:: Query

Example

>>> Query().scores.avg().between(70, 90)
Condition({'scores.$avg': {'$between': (70, 90)}})

between(lo, hi)[source]

Check if the target value falls strictly between two bounds. Maps to $between.

Return type:: Condition

ceil()[source]

Return the ceiling of x as an Integral.

Return type:: Query

Example

>>> Query().price.ceil() == 10
Condition({'price.$ceil': {'$eq': 10}})

endswith(suffix)[source]

Check if the target string ends with the given suffix. Maps to $ew.

Return type:: Condition

exists(fields)[source]

Check if the specified keys/fields exist in the target dictionary. Maps to $exists.

Return type:: Condition

first()[source]

Extracts the first item or character** before comparing. Maps to $first.

Return type:: Query

flat()[source]

Flattens a nested iterable before comparing. Maps to $flat.

Return type:: Query

float()[source]

Convert a number or string to an floating point.

Return type:: Query

Example

>>> Query().price.float() == 99.9
Condition({'price.$float': {'$eq': 99.9}})

floor()[source]

Return the floor of x as an Integral.

Return type:: Query

Example

>>> Query().price.floor() == 10
Condition({'price.$floor': {'$eq': 10}})

fullmatch(pattern, flags=0)[source]

Check if the target string perfectly matches a regex pattern. Maps to $match.

Return type:: Condition

has(val)[source]

Check if the target string or collection contains the value. Maps to $has.

Return type:: Condition

ihas(val)[source]

Check if the target string contains the value (case-insensitive). Maps to $ihas.

Return type:: Condition

int()[source]

Convert a number or string to an integer.

Return type:: Query

Example

>>> Query().price.int() == 99
Condition({'price.$int': {'$eq': 99}})

last()[source]

Extracts the last item or character** before comparing. Maps to $last.

Return type:: Query

len()[source]

Apply len() in the path chain. Maps to $len.

Works on str, list, tuple, dict, set, bytes.

Return type:: Query

Example

>>> Query().tags.len_() >= 3
Condition({'tags.$len': {'$gte': 3}})

lower()[source]

Apply str.lower() in the path chain. Maps to $lower.

Return type:: Query

Example

>>> Query().name.lower().has('alice')
Condition({'name.$lower': {'$has': 'alice'}})

matches(pattern, flags=0)[source]

Check if the target string contains a regex pattern match. Maps to $re.

Return type:: Condition

max()[source]

Apply max() in the path chain. Maps to $max.

Return type:: Query

Example

>>> Query().scores.max_() == 100
Condition({'scores.$max': {'$eq': 100}})

mid()[source]

Return the middle element/character in the path chain. Maps to $mid.

Uses index len(val) // 2. Works on list, tuple, str, bytes.

Return type:: Query

Example

>>> Query().tags.mid() == 'python'
Condition({'tags.$mid': {'$eq': 'python'}})

min()[source]

Apply min() in the path chain. Maps to $min.

Applicable to non-string iterables (list, tuple, set).

Return type:: Query

Example

>>> Query().scores.min_() >= 60
Condition({'scores.$min': {'$gte': 60}})

mod(div, rem)[source]

Check if the target value divided by div leaves a remainder of rem. Maps to $mod.

Return type:: Condition

near(target, tol)[source]

Check if the target value is within a specified tolerance of a number. Maps to $near.

Return type:: Condition

neg()[source]

Convert a number or string to an negative integer.

Return type:: Query

Example

>>> Query().price.neg() == -99
Condition({'price.$neg': {'$eq': -99}})

not_has(val)[source]

Check if the target string or collection does not contain the value. Maps to $nhas.

Return type:: Condition

not_in(collection)[source]

Check if the target value does not exist within the provided collection. Maps to $nin.

Return type:: Condition

one_of(collection)[source]

Check if the target value exists within the provided collection. Maps to $in.

Return type:: Condition

round()[source]

Round a number to a given precision in decimal digits.

Return type:: Query

Example

>>> Query().price.round() == 10
Condition({'price.$round': {'$eq': 10}})

size_of(size)[source]

Check if the length of the target collection matches the given size. Maps to $size.

Return type:: Condition

sort()[source]

Sort the iterable values before comparing. Maps to $sort.

Return type:: Query

startswith(prefix)[source]

Check if the target string starts with the given prefix. Maps to $sw.

Return type:: Condition

std()[source]

Apply population standard deviation in the path chain. Maps to $std.

Uses population std-dev (divides by n). Returns 0.0 for single-element sequences and None for empty ones.

Return type:: Query

Example

>>> Query().readings.std() < 2.0
Condition({'readings.$std': {'$lt': 2.0}})

str()[source]

Convert scalar to string

Return type:: Query

Example

>>> Query().price.str() == "99.9"
Condition({'price.$str': {'$eq': 99.9}})

strip()[source]

Apply str.strip() in the path chain. Maps to $strip.

Return type:: Query

sum()[source]

Apply sum() in the path chain. Maps to $sum.

Works on str, list, tuple, dict, set, bytes.

Return type:: Query

Example

>>> Query().tags.sum() == 3
Condition({'tags.$sum': 3})

test(func)[source]

Evaluate the target using a custom callback function. Maps to $func.

Return type:: Condition

type_of(_type)[source]

Check if the target value matches a specific data type. Maps to $type.

Return type:: Condition

unique()[source]

Performs order-preserving deduplication on an iterable before comparing. Maps to $unique.

Return type:: Query

upper()[source]

Apply str.upper() in the path chain. Maps to $upper.

Return type:: Query

omni_json_db.jdb_query.match_DATE_rules(cdate, mdate, rules, level=0)[source]

Evaluate whether a document’s creation or modification date matches a set of rules.

Supports operations such as $gt, $ge, $lt, $le, $eq, $ne, $in, $has, $re, $func, logical grouping, and time-deltas. If rules is provided as an integer, it evaluates a date range relative to today (e.g., 0 for today, positive for future windows, negative for past windows).

Parameters:

cdate (datetime.date) – The created date of the key/document.
mdate (datetime.date) – The modified date of the key/document.
rules (Any) – A dictionary of operators and their targets, a date object, an integer (representing a day offset from today), or a direct match condition.
level (int, optional) – The current recursion depth. Defaults to 0.

Returns:

True if the dates satisfy all specified rules, False otherwise.

Return type:

bool

Example

>>> today = dt.date.today()
>>> match_DATE_rules(today, today, rules={'$eq': today})
True

omni_json_db.jdb_query.match_KEY_rules(key, rules, level=0)[source]

Evaluate whether a document key matches a specified set of rules or MongoDB-like operators.

Supports various operations including comparative ($gt, $ge, $lt, $le), equality ($eq, $ne), inclusion ($in, $has), regular expressions ($re, $re2), custom functions ($func), string matching ($sw, $ew), size constraints ($size), and logical operators ($not, $or, $nor, $and).

Parameters:

key (str) – The string key to be evaluated.
rules (Any) – A dictionary of operators mapping to their conditions, or a direct match condition (e.g., string, regex pattern, callable).
level (int, optional) – The current recursion depth. Defaults to 0.

Returns:

True if the key satisfies all specified rules, False otherwise.

Return type:

bool

Example

>>> rules = {'$has': 'ob'}
>>> match_KEY_rules("Bob", rules)
True
>>> match_KEY_rules("Alice", {"$re": r"Al.*"})
True

omni_json_db.jdb_query.match_VAL_rules(key, val, rules, cdate, mdate, level=0, ANY=False, ALL=False)[source]

Evaluate whether a data value matches a set of rules or MongoDB-like operators.

This function performs deep evaluation of values, supporting nested dictionaries, iterables, and path wildcards. It supports an extensive list of operators including comparisons ($gt, $gte), array operators ($any, $all, $none, $size, $anyin), string queries ($has, $sw, $re), type checking ($type), existence ($exists), and complex logic ($and, $or).

When applied to iterables (except strings/bytes) alongside ANY or ALL, the evaluation recurses through the elements.

Parameters:

key (str) – The key associated with the value being evaluated.
val (Any) – The actual data value to be checked.
rules (Any) – A dictionary of evaluation rules/operators or a direct match condition.
cdate (datetime.date) – The created date associated with the data.
mdate (datetime.date) – The modified date associated with the data.
level (int, optional) – The current recursion depth. Defaults to 0.
ANY (bool, optional) – If True, evaluates to True if any element in an iterable value matches the rules. Defaults to False.
ALL (bool, optional) – If True, evaluates to True if all elements in an iterable value match the rules. Defaults to False.

Returns:

True if the value satisfies all specified rules, False otherwise.

Return type:

bool

Example

>>> rules = {'$gt': 10, '$lt': 20}
>>> match_VAL_rules("age", 15, rules, cdate, mdate)
True
>>> match_VAL_rules("name", "Alice", {"$re": r"Al.*"}, cdate, mdate)
True

omni_json_db.jdb_server

class omni_json_db.jdb_server.ServerHandler(request, client_address, server)[source]

Bases: BaseRequestHandler

Asynchronous transaction stream interpreter routing incoming socket instructions into structural operations.

handle()[source]: Process incoming client execution requests continuously within an isolated, thread-safe network layer session.

class omni_json_db.jdb_server.ThreadedTCPServer(server_address='127.0.0.1', RequestHandlerClass=None, bind_and_activate=True, files_obj=None, verbose=0, **kwargs)[source]

Bases: ThreadingMixIn, TCPServer

Multi-threaded high-performance TCP server architecture acting as distributed backend engine for JFiles.

__init__(server_address='127.0.0.1', RequestHandlerClass=None, bind_and_activate=True, files_obj=None, verbose=0, **kwargs)[source]

Initialize the asynchronous socket routing engine mapping data threads limits variables configurations rules.

Parameters:

server_address (Tuple[str, int]) – Endpoint combination configuration assignment supplying network IP with port. Defaults to (‘127.0.0.1’, 59898).
RequestHandlerClass (Optional[BaseRequestHandler], optional) – Strategy driver parsing individual connection streams logic profiles. Defaults to None.
bind_and_activate (bool, optional) – Auto-engage socket layer binding parameters directly. Defaults to True.
files_obj (Optional[JFilesBase], optional) – Baseline abstract dataset backend pipeline mapping real tables records files drivers. Defaults to None.
verbose (int, optional) – Monitoring debug resolution output granularity metric code selection value. Defaults to 0.
**kwargs – Extra attributes routed down seamlessly into underlying initialization classes.

Raises:

TypeError – If incoming dataset managers violate target class interface expectations profiles.

allow_reuse_address = True

daemon_threads = True

omni_json_db.utils

class omni_json_db.utils.FileLock(rlock, wlock, unlock, close, remove)[source]

Bases: object

Combined thread-level and process-level read/write lock backed by OS file locks.

Wraps a set of OS-level file-lock callables to provide:

Shared read locks (mode='r') – multiple threads and processes may hold a read lock simultaneously.
Exclusive write locks (mode='w') – only one thread in one process may hold a write lock; all readers are excluded.
Re-entrant acquisition – the same thread may call acquire() multiple times; each call must be matched by a release() call.
Lock upgrade – a thread holding a read lock may promote it to a write lock without fully releasing via switch=True in acquire().
SIGINT protection – write locks automatically engage INT_Handler so that Ctrl+C is deferred until the write section completes.

Internal mode values stored in _mode:

'' – no lock held.
'r' – shared read lock active.
'w' – exclusive write lock active.
'p' – pending: a thread is waiting for the OS-level lock.
'x' – closed/destroyed; no new acquisitions are permitted.

__del__()[source]: Clean up on garbage collection: release all pending locks and close the lock file.

__init__(rlock, wlock, unlock, close, remove)[source]

Initialise the lock with OS-level locking callables.

Parameters:

rlock (Callable[[bool], None]) – Acquire a shared (read) OS-level file lock. The single bool argument indicates whether the call should block.
wlock (Callable[[bool], None]) – Acquire an exclusive (write) OS-level file lock. The single bool argument indicates whether the call should block.
unlock (Callable[[], None]) – Release the current OS-level file lock.
close (Callable[[], None]) – Close the underlying lock file handle.
remove (Callable[[], None]) – Delete the lock file from disk.

Raises:

TypeError – If any of the five arguments is not callable.

__repr__()[source]

Return a diagnostic string showing the lock’s current state.

Returns:: A string of the form <FileLock lock:<bool> mode:<mode> at <hex_address>>. lock is 1 when a read or write lock is active, 0 otherwise; mode is one of '', 'r', 'w', 'p', or 'x'.
Return type:: str

acquire(block=True, read_only=False, switch=False)[source]

Acquire a read or write lock for the calling thread.

Thread-level re-entrance is supported: calling acquire again from a thread that already holds a compatible lock simply increments the re-entrance counter and returns immediately.

Lock promotion ( switch=True ) – a thread that currently holds a read lock may atomically promote it to a write lock. The read lock is released and the write lock is acquired without allowing other threads to sneak in between.

Parameters:

block (bool, optional) – If True (default), block until the lock becomes available. If False, raise FileLockException immediately when the lock cannot be acquired.
read_only (bool, optional) – If True, acquire a shared read lock (multiple threads/processes may hold it simultaneously). If False (default), acquire an exclusive write lock.
switch (bool, optional) – If True, upgrade the current thread’s read lock to a write lock without fully releasing. Only valid when the calling thread already holds a read lock. Defaults to False.

Returns:

The calling thread’s identifier (as returned by threading.get_ident()).

Return type:

int

Raises:

RuntimeError – If the internal threading mutex cannot be acquired.
FileLockException – If block=False and the lock is held by another thread or process, or if the lock has been closed (mode 'x').

can_lock()[source]

Test whether an exclusive write lock can be acquired immediately without blocking.

Attempts a non-blocking acquire(block=False, read_only=False) and releases it straight away.

Returns:: True if the write lock was obtained (and released), False if another holder would have caused a block.
Return type:: bool

get_count(thread_id)[source]

Return the re-entrance count for a given thread.

Each call to acquire() increments the count for the calling thread; each release() decrements it. The OS-level lock is released only when the count returns to zero.

Parameters:: thread_id (int) – Thread identifier as returned by threading.get_ident().
Returns:: Number of times the thread has acquired this lock without a matching release. Returns 0 if the thread holds no lock.
Return type:: int

has_SIGINT()[source]

Return whether a Ctrl+C was received while a write lock was held.

This delegates to INT_Handler.is_called() on the shared INT_manager instance.

Returns:: True if a deferred SIGINT is pending, False otherwise.
Return type:: bool

property is_locked: bool

Whether any thread currently holds a read or write lock.

Returns:: True if mode is 'r' or 'w', False otherwise.
Return type:: bool

property mode: str

Current lock mode as a single character string.

Returns:

One of:

'' – no lock held.
'r' – shared read lock active.
'w' – exclusive write lock active.
'p' – a thread is blocked waiting for the OS-level lock.
'x' – lock is closed; no new acquisitions permitted.

Return type:

str

release()[source]

Release one acquisition of the lock for the calling thread.

Decrements the re-entrance counter for the calling thread. When the counter reaches zero and no other threads hold the lock, the OS-level file lock is released and SIGINT handling is re-enabled (if a write lock was held).

Calling release from a thread that does not hold the lock has no effect.

Returns:: The calling thread’s identifier (as returned by threading.get_ident()).
Return type:: int
Raises:: RuntimeError – If the internal threading mutex cannot be acquired.

release_all()[source]

Wait for all threads to release their locks, then mark the lock as destroyed.

Blocks until _idents is empty (every thread has called release() enough times to drop its count to zero). Once drained, the mode is set to 'x' to prevent any new acquire() calls from succeeding. If a write lock was active, the SIGINT handler is re-enabled before closing.

This method is called by __del__() and should not normally be called directly.

Returns:: True if the internal mutex was acquired and the shutdown sequence completed. False if the mutex itself could not be acquired (should not happen in practice).
Return type:: bool

reset_lock()[source]

Delete the lock file from disk, ignoring the error if it does not exist.

Use this to clean up a stale lock file left behind by a crashed process. Only call this when no other process holds or awaits the lock.

Return type:: None

rlock()[source]

Context manager that acquires a shared read lock and releases it on exit.

Yields:: None – Control is yielded to the with block with the read lock held.

Example

with file_lock.rlock():
    data = read_from_file()

wlock()[source]

Context manager that acquires an exclusive write lock and releases it on exit.

SIGINT (Ctrl+C) is deferred while the write lock is held and re-enabled automatically on release.

Yields:: None – Control is yielded to the with block with the write lock held.

Example

with file_lock.wlock():
    write_to_file(data)

exception omni_json_db.utils.FileLockException[source]

Bases: BlockingIOError

Raised when a FileLock operation cannot be completed.

Thrown in two situations:

A non-blocking lock acquisition (block=False) fails because another process already holds an incompatible lock.
A lock acquisition is attempted after the FileLock has been closed or is being destroyed (mode 'x').

omni_json_db.utils.deepcopy(src)[source]

Create a selective deep copy optimised for the types used in JDb.

Common immutable types and JDbBase instances are returned as-is without copying. Containers are handled as follows:

tuple – new tuple whose elements are recursively deep-copied.
dict – new dict whose values are recursively deep-copied (keys are not copied because dict keys must be hashable).
set – shallow copy via set.copy() (set elements are hashable scalars and need no further copying).
Any other object whose __hash__ attribute is truthy (e.g. a compiled re.Pattern or a frozenset) is treated as effectively immutable and returned without copying.
Everything else (typically a list) – new list whose elements are recursively deep-copied.

Parameters:: src (Any) – The object to copy.
Returns:: A deep copy of src, or src itself for immutable types.
Return type:: Any

Example

>>> original = {'key': [1, 2, 3]}
>>> copied = deepcopy(original)
>>> copied['key'] is original['key']
False