API Reference¶
KYDB Interface¶
-
class
kydb.interface.
KYDBInterface
¶ The interface that all KYDB adheres to
This class and all derived classes are never instantiated directly.Instead use the
connect
. i.e.:import kydb db = kydb.connect('dynamodb://my-table')
-
__getitem__
(key: str)¶ Get data from the DB based on key
To be implemented by derived class
param key: str: The key to get. example:
db[key] # returns the object with key
-
__setitem__
(key: str, value)¶ Set data from the DB based on key
param key: str: The key to set. param value: The python object example:
db[key] = value # sets key to value
Note: key cannot have any component that has a dot (.) prefix.
i.e. the below are illegal and would raise KeyError
db['.foo'] = 123 # raises KeyError db['/.foo'] = 123 # raises KeyError db['/my/folder/.foo'] 123 # raises KeyError db['/my-folder/.another-folder/foo'] = 123 # raises KeyError
-
cache_context
() → kydb.interface.KYDBInterface¶ returns the cache context
See Cache Context
-
delete
(key: str)¶ Delete a key from the db. To be implemented by derived class
param key: str: The key to delete. example:
db.delete(key) # Deletes data with key
-
exists
(key) → bool¶ Check if a key exists in the DB
param key: the key returns: True if key exists, False otherwise. Example:
db['/my/key'] = 123 db.exists('/my/key') # returns True
-
is_dir
(folder: str) → bool¶ Is this a directory?
param folder: Returns True if is directory example:
db.mkdir('/foo/bar') db.is_dir('/foo/bar') # returns True
-
list_dir
(folder: str, include_dir=True, page_size=200)¶ List the folder
Parameters: folder – The folder to lsit Parm include_dir: include subfolders Parm page_size: The number of items to fetch at a time from DB The result would be identical, only controls performance Note Folders always ends with
/
Objects does not
-
ls
(folder: str, include_dir=True)¶ Similar to list_dir, but returns a list (not generator)
Parameters: folder – The folder to lsit Parm include_dir: include subfolders Parm page_size: The number of items to fetch at a time from DB The result would be identical, only controls performance Note Folders always ends with
/
mbjects does not
-
mkdir
(folder: str)¶ Make a directory (recursively if required)
param folder: The folder path. example:
db.mkdir('/foo/bar') db.ls('/foo') # returns ['bar/']
-
new
(class_name: str, key: str, **kwargs)¶ Create a new object on the DB. The object is not persisted until obj.write() is called.
param class_name: str: name of the class. This name must be in the config registry param key: str: The key to persist on the DB param kwargs: the stored attributes to set on the obj returns: an obj of type defined by class_name example:
obj = db.new('MyClass', key, foo=3)
-
read
(key: str, reload=False)¶ Read object from DB given the key. If key has been read before, this call would simply return the cached value. Use reload to force reloading from DB.
param key: str: key to DB param reload: Optionally force reloading of the object from db (Default value = False) returns: The object from DB example:
obj = db.new('MyClass', key) obj.write() db.read(key) # read from cache db.read(key, reload=True) # Force loading from DB
-
refresh
(key=None)¶ Flush the cache
param key: Optionally choose which key to flush (Default value = None) example:
obj = db.new('MyClass', key) obj.write() db[key] # read from cache db.refresh() # Or db.refresh(key) db[key] # read from DB
-
rm_tree
(key: str)¶ recursively delete folder
Warning
Be careful when using this. For example
rm_tree('/')
would wipe out the entire database!
-
rmdir
(key: str)¶ Delete folder based on key
param key: str: The key to folder to delete example:
db.rmdir(folder) # Deletes folder with key
-
set
(key: str, value, system_obj=False)¶ Set data from the DB based on key
Parameters: - key – str: The key to set.
- value – The python object
- system_obj – bool: True if a system object
Same as __setitem__ except it can write system objects i.e. object with a (.) dot prefix.
Note: only use this if you know what you’re doing
-
upload_objdb_config
(config)¶ Upload ObjDB config to KYDB
param config: The config dict
This should only need to be done when new classes are registered or existing ones changes path.
db = kydb.connect('memory://decorated_py_obj') db.upload_objdb_config({ 'Greeter': { 'module_path': 'path.to.module', 'class_name': 'Greeter' } })
-
Decored Python Object¶
-
class
kydb.dbobj.
DbObj
(db, class_name: str, key: str, **kwargs)¶ Derive this class to enable it for Python Object DB API
exampleclass Greeter(kydb.DbObj): def init(self): self.greet_count = 0 @kydb.stored def name(self): return 'John' def greet(self): self.greet_count += 1 return 'Hello ' + self.name()
-
get_stored_dict
()¶ The dictionary to be serialised and stored in DB.
Example:class Greeter(kydb.DbObj): def init(self): self.greet_count = 0 ## Not persisted @kydb.stored def name(self): return 'John' def greet(self): self.greet_count += 1 return 'Hello ' + self.name() greeter.get_stored_dict() # returns {'name': 'Mary'}
-
init
()¶ Implement this to add additional initialisation
exampleclass MyClass(kydb.DbObj): def init(self): self._some_network_resource = get_network_resource()
-
Stored Value¶
-
class
kydb.dbobj.
StoredValue
(default_func)¶ - Any function decorated with @kydb.stored would
- turn the function into a StoredValue
- For example, the method
name
would turn into a StoredValue
because of the decorator.
- For example, the method
class Greeter(kydb.DbObj): @kydb.stored def name(self): return 'John'
-
clear
()¶ Clears the value.
This sets the value back to default.example:
greeter = db.new('Greeter', key) # Default is 'John' greeter.name.setvalue('Jane') greeter.name() # returns 'Jane' greater.clear() greeter.name() # returns 'John'
-
setvalue
(value)¶ - Set the value
params value: the value to set
example:
greeter = db.new('Greeter', key) greeter.name.setvalue('Jane') greeter.name() # returns 'Jane'