exception DBWriteError

Bases: Exception

Exception class for when db writes fail.

class RecordField

Bases: tuple

A RecordField represents a field as part of a record in the datastore.

The field is given a type via field_type. Additionally, a RecordField has three optional parameters: encode, decode, and query_filter.

The field_type is the Python type that the field should be when being accessed from the datastore.

The optional encode is any callable that takes the field value (as a field_type) as an argument and returns it as bytes. This should always be implemented if the field_type is not a natively msgpack’able type. Care should be taken to ensure that the encoded data can be decoded and usable in _another_ language other than Python to ensure future interoperability.

The optional decode is any callable that takes the unpack’d encoded field value and returns the field_type. If you implement encode, you will probably always want to provide a decode.

property field_type

Alias for field number 0

property encode

Alias for field number 1

property decode

Alias for field number 2

class DatastoreRecord(db_transaction: lmdb.Transaction, record_id: Union[int, str], writeable: bool = False)

Bases: object


Deletes the entire record.

This works by iterating over class variables, identifying the record fields, and then deleting them.

exception RecordNotFound

Bases: Exception

Exception class for Datastore calls for objects that don’t exist.

exception DatastoreTransactionError

Bases: Exception

Exception class for errors during transactions in the datastore.

class DatastoreKey

Bases: tuple

Used for managing keys when querying the datastore.

property record_type

Alias for field number 0

property record_field

Alias for field number 1

property record_id

Alias for field number 2

classmethod from_bytestring(key_bytestring: bytes)nucypher.datastore.datastore.DatastoreKey
compare_key(key_bytestring: bytes)bool

This method compares a key to another key given a key’s bytestring. Usually, the key_bytestring will be a query key, and the self key will be a key in the Datastore.

The logic below offers precedence when performing matches on a query. We _prefer_ the other_key over self. As such, if other_key doesn’t specify a key attr (it will be None), we will take the key attr conferred by self.

Specifically, this allows us to match partial keys to specific keys, where the Datastore will _always_ return specific keys, but queries will almost always be partial keys.

class Datastore(db_path: pathlib.Path)

Bases: object

A persistent storage layer for arbitrary data for use by NuCypher characters.

LMDB_MAP_SIZE = 1000000000000
describe(record_type: Type[DatastoreRecord], record_id: Union[int, str], writeable: bool = False) → Type[nucypher.datastore.base.DatastoreRecord]

This method is used to perform CRUD operations on the datastore within the safety of a context manager by returning an instance of the record_type identified by the record_id provided.

When writeable is False, the record returned by this method cannot be used for any operations that write to the datastore. If an attempt is made to retrieve a non-existent record whilst writeable is False, this method raises a RecordNotFound error.

When writeable is True, the record can be used to perform writes on the datastore. In the event an error occurs during the write, the transaction will be aborted and no data will be written, and a DatastoreTransactionError will be raised.

If the record is used outside the scope of the context manager, any writes or reads will error.

query_by(record_type: Type[DatastoreRecord], filter_func: Optional[Callable[[Union[Any, Type[DatastoreRecord]]], bool]] = None, filter_field: str = '', writeable: bool = False) → Generator[List[Type[nucypher.datastore.base.DatastoreRecord]], None, None]

Performs a query on the datastore for the record by record_type.

An optional filter_func callable will take the decoded field specified by the optional arg filter_field (see below) for the given record_type iff the filter_field has been provided. If no filter_field has been provided, then the filter_func will receive a _readonly_ DatastoreRecord.

An optional filter_field can be provided as a str to perform a query on a specific field for a record_type. This will cause the filter_func to receive the decoded filter_field per the record_type. Additionally, providing a filter_field will limit the query to iterating over only the subset of records specific to that field.

If records can’t be found, this method will raise RecordNotFound.

class ReencryptionRequest(db_transaction: lmdb.Transaction, record_id: Union[int, str], writeable: bool = False)

Bases: nucypher.datastore.base.DatastoreRecord

unwrap_records(func: Callable[[…], Generator[List[Type[DatastoreRecord]], None, None]]) → Callable[[…], List[Type[nucypher.datastore.base.DatastoreRecord]]]

Used to safely unwrap results of a query. Suitable only for reading DatastoreRecord`s. Use `find_* functions if you want to modify records.

Since results returned by Datastore.query_by() are lazy (wrapped in a @contextmanager generator) we have to unwrap them and handle RecordNotFound error, if any. DatastoreRecord`s are not writable after unwrapping, because exiting `@contextmanager is also closing Datastore transaction.

get_reencryption_requests(ds: nucypher.datastore.datastore.Datastore) → List[nucypher.datastore.models.ReencryptionRequest]