hio.base.webduring
Browser-safe durable storage for HIO wrappers.
Module Contents
- class hio.base.webduring.WebSubDb(*, key, dupsort, items)
LMDB-like sub-database handle for existing wrapper classes.
- class hio.base.webduring.WebDuror(*, name='main', base='', temp=False, reopen=False, clear=False, stores=None, storageOpener=None, **kwa)
Bases:
hio.base.filing.FilerBrowser durable storage with Duror-compatible method semantics.
Uses an async PyScript style storage opener instead of LMDB and exposes the same low-level db methods used by Duror wrappers.
- async reopen(*, clear=False, stores=None, storageOpener=None, temp=None, **kwa)
Open declared browser storage namespaces and load persisted records.
- close(clear=False)
Close local handles after persisting or clearing pending state.
When called inside a running loop, persistence is scheduled on that loop. Use await aclose() when the caller must wait for completion.
- async aclose(clear=False)
Flush pending writes, optionally clear persisted browser records, and close.
- async flush()
Persist dirty stores through their browser storage handles.
- property version
Return the version of database stored in __version__ key.
This value is read through cached in memory
- getVer()
Returns the value of the the semver formatted version in the __version__ key in this database
- Returns:
semver formatted version of the database
- Return type:
- setVer(version)
Set the version of the database in the __version__ key
- Parameters:
version (str) – The new semver formatted version str of the database
- putVal(sdb, key, val)
Write serialized bytes val to location key in db (subdb) Does not overwrite. :returns: True if val successfully written; False if val at key already exists :rtype: result (bool)
- pinVal(sdb, key, val)
Write serialized bytes val to location key in db Overwrites existing val if any :returns: True if val successfully written; False otherwise :rtype: result (bool)
- getVal(sdb, key)
Get val at key in db
- remVal(sdb, key)
Removes value at key in db.
- cntVals(sdb)
Counts entries in subdb db
- getTopItemIter(sdb, top=b'')
Iterates over branch of subdb db rooted at top key
- Returns:
- of (full key, val) tuples over a branch of the db
given by top key where: full key is full database key for val not truncated top key
- Return type:
items (Iterator)
Raises StopIteration Error when empty.
- Parameters:
sdb (WebSubDb) – instance of named sub db with dupsort==False
top (bytes) – truncated top key, a key space prefix to get all the items from multiple branches of the key space. If top key is empty then gets all items in database. In Python str.startswith(‘’) always returns True so if branch key is empty string it matches all keys in db with startswith.
- remTopVals(sdb, top=b'')
Removes all values in branch of db given top key.
- Returns:
- True if values were deleted at key.
False otherwise if no values at key
- Return type:
result (bool)
- Parameters:
Raises StopIteration Error when empty.
- static suffix(key: bytes | str | memoryview, ion: int, *, sep: bytes | str = b'.')
Return iokey after concatenating the hex ordinal suffix to key using sep.
- Parameters:
key (bytes|str|memoryview) – apparent effective database key (unsuffixed)
ion (int)) – insertion ordered ordinal numberfor set of vals
sep (bytes) – separator character(s) for concatenating suffix
- static unsuffix(iokey: bytes | str | memoryview, *, sep: bytes | str = b'.')
Return (key, ion) from splitting iokey at the rightmost sep.
- Parameters:
iokey (bytes|str|memoryview) – actual database key suffixed
sep (bytes) – separator character(s) for splitting suffix
- getIoValFirst(sdb, key, *, ion=0, sep=b'.')
Gets first of the insertion ordered set of values at key, None if no entry. Returns the first value at the apparent effective key whose iokey is greater than or equal to the iokey from ion, or None if no entry.
- getIoValLast(sdb, key, *, sep=b'.')
Gets last value (last in) of insertion ordered set values at key Returns the last value at the apparent effective key, or None if no entry.
Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- getIoVals(sdb, key, *, ion=0, sep=b'.')
Gets list of all the insertion ordered set of values at key
- Returns:
- insertion-ordered values at same apparent effective key;
hidden ordinal key suffix is used for insertion ordering and stripped transparently.
- Return type:
- Parameters:
- getIoValsIter(sdb, key, *, ion=0, sep=b'.')
Gets Iterator of all the insertion ordered set of values at key
- Returns:
- iterator over insertion ordered set of values
at same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- Return type:
ioset (Iterator)
Raises StopIteration Error when empty.
- popIoVal(sdb, key, *, ion=0, sep=b'.')
Pops first of the insertion ordered set of values at key. None if no entry. Pop deletes the returned entry.
- Returns:
- first val at same apparent effective key
whose iokey >= iokey from ion Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently. None if no entry.
- Return type:
val (bytes|None)
- Parameters:
- remIoVals(sdb, key, *, sep=b'.')
Deletes all values at apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- cntIoVals(sdb, key, *, sep=b'.')
Count all values with the same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- getTopIoItemIter(sdb, top=b'', *, sep=b'.')
Gets Iterator of all values in branch rooted at top key The suffix is appended and stripped transparently.
- Returns:
- iterator of tuples (key, val) where
key is apparent key with hidden insertion ordering suffixe removed from effective key. Iterates over top branch of insertion ordered set values where each effective key has trailing hidden suffix of serialization of insertion ordering ordinal.
Uses hidden ordinal key suffix for insertion ordering.
- Return type:
items (Iterator[(key,val)])
Raises StopIteration Error when empty.
- addIoVal(sdb, key, val, *, sep=b'.')
Add val at end (append) of insertion ordered set of values all with the same apparent effective key. Does not dedup val. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- putIoVals(sdb, key, vals, *, sep=b'.')
Adds at end (append) each val in vals to insertion ordered list of values all with the same apparent effective key for each val. Does not dedup added vals. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- pinIoVals(sdb, key, vals, *, sep=b'.')
Erase all vals at key and then add vals as insertion ordered set of values all with the same apparent effective key. Does not dedup vals. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- addIoSetVal(sdb, key, val, *, sep=b'.')
Add val idempotently to insertion ordered set of values all with the same apparent effective key if val not already in set of vals at key. Dedups the added val. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- putIoSetVals(sdb, key, vals, *, sep=b'.')
Adds idempotently each val in vals to insertion ordered set of values all with the same apparent effective key for each val that is not already in set of vals at key. Dedups the put vals. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- pinIoSetVals(sdb, key, vals, *, sep=b'.')
Erase all vals at key and then add unique vals as insertion ordered set of values all with the same apparent effective key. Dedups the set vals. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
- remIoSetVal(sdb, key, val, *, sep=b'.')
Removes (delete) matching val at apparent effective key if exists. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.
Because the insertion order of val is not provided must perform a linear search over set of values.
Another problem is that vals may get added and deleted in any order so the max suffix ion may creep up over time. The suffix ordinal max > 2**16 is an impossibly large number, however, so the suffix will not max out practically.But its not the most elegant solution.
In some cases a better approach would be to use getIoSetItemsIter which returns the actual iokey not the apparent effetive key so can delete using the iokey without searching for the value. This is most applicable when processing escrows where all the escrowed items are processed linearly and one needs to delete some of them in stride with their processing.
- async hio.base.webduring.openWebDuror(*, cls=None, name='test', temp=True, clear=False, **kwa)
Async context manager wrapper for WebDuror instances.