Database¶
- class dsviper.Database¶
Bases:
objectA Database is a CRUD like transactional database. Use the static factory method create_in_memory(), create(…), open(…), connect(…) or connect_local(…).
Transactional is a precondition, not a feature: reads need no transaction, and every WRITE requires one already open - set, delete and the blob operations raise without writing anything when there is none. extend_definitions is the exception in both directions, opening an exclusive transaction of its own. A CommitDatabase does NOT work this way: its writes need no transaction at all.
One file may be open in several processes; SQLite locks it. While a transaction writes, another writer waits, and in ‘Exclusive’ mode a reader waits too - for up to 10 seconds, after which the call raises ViperError: the database is busy. Otherwise a reader sees the last committed state.
Note: Not directly instantiable.
- attachment_getting() AttachmentGetting¶
Return the AttachmentGetting interface.
- begin_transaction(mode: str | None = None) None¶
Begin a transaction in mode ‘Deferred’ (the default), ‘Immediate’ or ‘Exclusive’.
Another spelling raises.
Transactions do not nest: calling this while in_transaction() is True raises, and the transaction already open is untouched.
- blob(blob_id: ValueBlobId) ValueBlob | None¶
Return the bytes of the blob blob_id names, or None if it is not held here.
Raises past 2 GB, where the bytes cannot be handed over in one piece. Ask blob_info(blob_id).chunked() first, and read such a blob with read_blob.
A blob databasing().create_zero_blob reserved raises until databasing().freeze_blob seals it; blob_info answers None for it meanwhile.
- blob_getting() BlobGetting¶
Return the BlobGetting interface.
- blob_ids() ValueSet[ValueBlobId]¶
Return the set of blob_id of every sealed blob.
A blob databasing().create_zero_blob reserved joins it once databasing().freeze_blob seals it.
- blob_info(blob_id: ValueBlobId) BlobInfo | None¶
Return the BlobInfo for blob_id, or None if the database does not hold it.
It gives the layout, the size and whether the blob is chunked. A blob databasing().create_zero_blob reserved answers None until databasing().freeze_blob seals it.
- blob_infos(blob_ids: set[ValueBlobId] | ValueSet[ValueBlobId]) list[BlobInfo]¶
Return one BlobInfo per blob_id of blob_ids the database holds.
An unknown blob_id is left out, so the list may be shorter than blob_ids.
- blob_reader_close(blob_reader: BlobReader) None¶
Close blob_reader, releasing its read lock.
A second close does nothing.
- blob_reader_open(blob_id: ValueBlobId) BlobReader¶
Return a BlobReader on the blob blob_id names.
Read it in pieces with blob_reader_read, each piece through the same handle, at a cost that grows with the bytes read alone. Raises when blob_id names no frozen blob.
The reader holds a read lock on the database file from its first read: another connection cannot commit until blob_reader_close, or until the last reference to the reader goes.
- blob_reader_read(blob_reader: BlobReader, size: int) ValueBlob¶
Return the next size bytes of blob_reader, and move it past them.
Fewer bytes at the end of the blob, none once it is read whole. Raises once the reader is closed.
- blob_statistics() BlobStatistics¶
Return the statistics for blobs.
- blob_stream_append(blob_stream: BlobStream, blob: ValueBlob) None¶
Append blob to blob_stream, after the bytes already written.
Requires an open transaction, and raises without writing when there is none. Raises when the bytes would run past the size the stream was created with.
A failure here closes the stream and discards what it collected, so nothing partial is left behind and there is nothing to clean up.
- blob_stream_close(blob_stream: BlobStream) ValueBlobId¶
Close blob_stream and return its blob_id.
The blob_id is computed from everything written into it. Requires an open transaction, and raises without writing when there is none. Raises when fewer bytes than the size the stream was created with were appended.
A failure here closes the stream and discards what it collected, so nothing partial is left behind and there is nothing to clean up.
- blob_stream_create(blob_layout: BlobLayout, size: int) BlobStream¶
Return a BlobStream to fill a blob of size bytes laid out by blob_layout.
Requires an open transaction, and raises without writing when there is none. The whole size is reserved in the store now: a stream that is never closed keeps that space, and this class has no call to give it back.
- close() None¶
Close the database.
- codec_name() str¶
Return the name of the codec.
- commit() None¶
Commit the transaction, so what it wrote stays.
Raises when no transaction is open.
- static connect(database: str, host: str, service: str = '54322') Database¶
Return the database named database, served by host on service.
- static connect_local(database: str, socket_path: str) Database¶
Return the database named database, served on the unix socket socket_path.
- static create(file_path: str, *, documentation: str | None = None) Database¶
Create a database at file_path and return it.
documentation is stored in the file and read back by documentation().
Requires that nothing exist at file_path, and raises without creating anything when something does.
- create_blob(blob_layout: BlobLayout, blob: ValueBlob) ValueBlobId¶
Store blob under blob_layout.
Returns the blob_id computed from its content and that layout. Requires an open transaction, and raises without writing when there is none.
- create_blob_from_buffer(buffer) ValueBlobId¶
Store the bytes of a buffer or a ValueBlob; return their blob_id.
Requires an open transaction, and raises without writing when there is none.
- static databases(host: str, service: str = '54322') list[str]¶
Return the names of the databases host serves on service.
- static databases_local(socket_path: str) list[str]¶
Return the names of the databases served on the unix socket socket_path.
- databasing() Databasing¶
Return the Databasing interface.
- definitions() DefinitionsConst¶
Return the Definitions every value in the database is typed by.
It is a SNAPSHOT: extending the database afterwards does not show through the handle you hold, so ask again. A view obtained from Definitions.const() is live instead - same class, opposite liveness.
- definitions_hexdigest() str¶
Return the SHA1 of the definitions, as a hex string.
- del_blob(blob_id: ValueBlobId) bool¶
Delete the blob blob_id names, and return True if it was there.
Requires an open transaction, and raises without writing when there is none.
- delete(attachment: Attachment, key: ValueKey) bool¶
Delete the document attachment holds at key.
Returns True if it was there. Requires an open transaction, and raises without writing when there is none.
- documentation() str¶
Return the free text stored with the database at create(). One made without any answers ‘not documented.’, one made in memory answers ‘In Memory’ - both are placeholders written in at create(), not substituted on read.
- extend_definitions(definitions: DefinitionsConst) DefinitionsExtendInfo¶
Add every type and attachment of definitions the database lacks.
It opens an exclusive transaction of its own, so it raises when one is already open - the reverse of every other write here.
It raises ViperError when the database already holds a type of the same name under another runtime id - the same type changed, as when a field is added.
- get(attachment: Attachment, key: ValueKey) ValueOptional¶
Return a ValueOptional over the document attachment holds at key.
Always a ValueOptional, never None: ask is_nil() whether it holds anything, and unwrap() for the document itself.
An absent document answers a nil ValueOptional; a key the attachment’s key type does not admit raises, so is_nil() reports absence and never a mismatched key. So does the default key, whose instance id is invalid, and an attachment extend_definitions has not registered.
The document comes back as a copy; mutating it does not reach what is stored.
- has(attachment: Attachment, key: ValueKey) bool¶
Return True if attachment holds a document at key.
Raises for an attachment extend_definitions has not registered.
- in_memory() bool¶
Return True if the database is in memory.
- in_transaction() bool¶
Return True if a transaction is running.
- is_closed() bool¶
Return True if the database is closed.
- static is_compatible(file_path: str) bool¶
Return True if the file at file_path carries the expected SQL schema.
- keys(attachment: Attachment) ValueSet[ValueKey]¶
Return every key attachment holds a document for.
The set is taken now: a later write does not reach it. Raises for an attachment extend_definitions has not registered.
- static open(file_path: str, readonly: bool = False) Database¶
Open the database at file_path and return it.
readonly opens it without allowing a write. The refusal comes at the first write, not at begin_transaction(): that call succeeds, the write raises, and the transaction stays open until rollback().
Requires a file at file_path, and raises when there is none.
- path() str¶
Return the file path the database was opened from.
A database made in memory answers ‘InMemory’ rather than a path, and that exact string is how the runtime recognises one, so no file may take it: creating or opening a file of that path raises. Over a socket the answer is whatever the server answers for its own database.
- read_blob(blob_id: ValueBlobId, size: int, offset: int) ValueBlob¶
Return size bytes of the blob blob_id names, starting at offset.
The read side of blob_stream_create, blob_stream_append and blob_stream_close, and the only way to read a blob past 2 GB, which blob() refuses.
Raises when offset, or offset + size, runs past the end of the blob, and when blob_id names no blob - where blob() answers None.
- rollback() None¶
Roll back the transaction, so what it wrote is dropped.
Raises when no transaction is open.
- set(attachment: Attachment, key: ValueKey, value: _InputValues) bool¶
Write value into attachment at key, replacing what was there.
The value is copied in: mutating it afterwards does not reach what was written, and writing the same object under two keys stores two independent documents.
Returns True when the document was written; a check that refuses raises instead of answering. It needs an attachment extend_definitions has registered - an unregistered one raises whatever the transaction - and an open transaction, without which it raises and writes nothing.