Home       Trees       Indices       Help   
Package ivs :: Package inout :: Module database :: Class Database
[hide private]
[frames] | no frames]

Class Database

source code

A database class.

The class creates and manages a dictionary saved to the hard disk.

It functions as a python dictionary with the extra option of synchronizing the database instance with the dictionary saved on the hard disk.

No changes will be made to the hard disk copy, unless Database.sync() is called.

Note that changes made on a deeper level than the (key,value) pairs of the Database (for instance in the case where value is a dict() type itself) will not be automatically taken into account when calling the sync() method. The key for which the value has been changed on a deeper level has to be added to the Database.__changed list by calling addChangedKey(key) manually.

Running the Database.sync() method will not read the database from the hard disk if no changes were made or if changes were made on a deeper level only. In order to get the most recent version of the Database, without having made any changes, use the .read() method. Note that if changes were made on a deeper level, they will be lost.

Example:

>>> import os
>>> from ivs.inout import database
>>> filename = 'mytest.db'
>>> db = database.Database(filename)
No database present at mytest.db. Creating a new one.
>>> db['test'] = 1
>>> db['test2'] = 'robin'
>>> db.sync()
>>> db2 = database.Database(filename)
>>> print db2['test']
1
>>> print db2['test2'] 
robin
>>> db2['test'] = 2
>>> db2.sync()
>>> db.sync()
>>> print db['test']
1
>>> db.read()
>>> print db['test']
2
>>> del db2['test2']
>>> db2.sync()
>>> print db['test2']
robin
>>> db.read()
>>> print db['test2']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'test2'
>>> test_dict = dict()
>>> db['test'] = test_dict
>>> db.sync()
>>> db2.read()
>>> print db2['test']
{}
>>> db['test']['test'] = 1
>>> db.sync()
>>> db2.read()
>>> print db2['test']
{}
>>> db.addChangedKey('test')
>>> db.sync()
>>> db2.read()
>>> print db2['test']
{'test': 1}
>>> db.setdefault('test','defkey')
{'test': 1}
>>> db.setdefault('test3','defval')
'defval'
>>> db.sync()
>>> db2.read()
>>> print db2['test3']
defval
>>> os.system('rm %s'%filename)
0
Instance Methods [hide private] 
new empty dictionary
__init__(self, db_path)
Initializing a Database class.		 source code
 
__delitem__(self, key)
Delete a key from the database.		 source code
 
__setitem__(self, key, value)
Set a dict key with value.		 source code
D.get(k,d), also set D[k]=d if k not in D
setdefault(self, key, *args)
Return key's value, if present.		 source code
v, remove specified key and return the corresponding value
pop(self, key, *args)
If database has key, remove it from the database and return it, else return default.		 source code
(k, v), remove and return some (key, value) pair as a
popitem(self)
Remove and return an arbitrary (key, value) pair from the database.		 source code
None
update(self, *args, **kwargs)
Update the database with new entries, as with a dictionary.		 source code
 
read(self)
Read the database from the hard disk.		 source code
 
sync(self)
Update the database on the harddisk and in the memory.		 source code
 
__save(self)
Save a database.		 source code
 
addChangedKey(self, key)
Add a key to the list of changed keys in the database.		 source code
list
getDeletedKeys(self)
Return a list of all keys that have been deleted from the database in memory.		 source code
list
getChangedKeys(self)
Return a list of all keys that have been changed in the database in memory.		 source code

Inherited from dict: __cmp__, __contains__, __eq__, __ge__, __getattribute__, __getitem__, __gt__, __iter__, __le__, __len__, __lt__, __ne__, __new__, __repr__, __sizeof__, clear, copy, fromkeys, get, has_key, items, iteritems, iterkeys, itervalues, keys, values, viewitems, viewkeys, viewvalues

Inherited from object: __delattr__, __format__, __reduce__, __reduce_ex__, __setattr__, __str__, __subclasshook__

Class Variables [hide private]

Inherited from dict: __hash__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, db_path)
(Constructor)

source code 

Initializing a Database class.

Upon initialization, the class will read the dictionary saved at the db_path given as a dictionary.

Note that cPickle is used to write and read these dictionaries.

If no database exists at db_path, a new dictionary will be created.

Parameters:
  • db_path (string) - The path to the database on the hard disk.
Returns: 
new empty dictionary
Overrides: object.__init__

__delitem__(self, key)
(Index deletion operator)

source code 

Delete a key from the database.

This deletion is also done in the hard disk version of the database when the sync() method is called.

This method can be called by using syntax: del db[key]

Parameters:
  • key (a type valid for a dict key) - a dict key that will be deleted from the Database in memory
Overrides: dict.__delitem__

__setitem__(self, key, value)
(Index assignment operator)

source code 

Set a dict key with value.

This change is only added to the database saved on the hard disk when the sync() method is called.

The key is added to the Database.__changed list.

This method can be called by using syntax: db[key] = value

Parameters:
  • key (a type valid for a dict key) - a dict key that will be added to the Database in memory
  • key (a type valid for a dict key) - value of the key to be added
  • value (any)
Overrides: dict.__setitem__

setdefault(self, key, *args)

source code 

Return key's value, if present. Otherwise add key with value default and return.

Database.__changed is updated with the key if it is not present yet.

Parameters:
  • key (any valid dict() key) - the key to be returned and/or added.
  • args (any type) - A default value added to the dict() if the key is not present. If not specified, default defaults to None.
Returns: D.get(k,d), also set D[k]=d if k not in D
key's value or default
Overrides: dict.setdefault

pop(self, key, *args)

source code 

If database has key, remove it from the database and return it, else return default.

If both default is not given and key is not in the database, a KeyError is raised.

If deletion is successful, this change is only added to the database saved on the hard disk when the sync() method is called.

The key is added to the Database.__deleted list, if present originally.

Parameters:
  • key (a type valid for a dict key) - a dict key that will be removed from the Database in memory
  • args (any) - value of the key to be returned if key not in Database
Returns: v, remove specified key and return the corresponding value
value for key, or default
Overrides: dict.pop

popitem(self)

source code 

Remove and return an arbitrary (key, value) pair from the database.

A KeyError is raised if the database has an empty dictionary.

If removal is successful, this change is only added to the database saved on the hard disk when the sync() method is called.

The removed key is added to the Database.__deleted list.

Returns: (k, v), remove and return some (key, value) pair as a
(key, value) pair from Database
Overrides: dict.popitem

update(self, *args, **kwargs)

source code 

Update the database with new entries, as with a dictionary.

This update is not synched to the hard disk! Instead Database.__changed includes the changed keys so that the next sync will save these changes to the hard disk.

Parameters:
  • args (dict()) - A dictionary type object to update the Database.
  • kwargs (any type that is allowed as a dict key type.) - Any extra keywords are added as keys with their values.
Returns: None
Overrides: dict.update

read(self)

source code 

Read the database from the hard disk.

Whenever called, the database in memory is updated with the version saved on the hard disk.

Any changes made outside the session of this Database() instance will be applied to the database in memory!

Any changes made to existing keys in current memory before calling read() will be undone! Use sync() instead of read if you want to keep current changes inside the session.

If no database is present at the path given to Database() upon initialisation, a new Database is made by saving an empty dict() at the requested location.

Reading and saving of the database is done by cPickle-ing the dict().

sync(self)

source code 

Update the database on the harddisk and in the memory.

The database is read anew, ie updated with the hard disk version to account for any changes made by a different program. Next, the changes made to the database in memory are applied, before saving the database to the hard disk again.

Any items deleted from the database in memory will also be deleted from the version saved on the hard disk!

The keys that are changed explicitly are all listed in self.__changed, to which entries can be added manually using the addChangedKey method, or automatically by calling .update(), .__setitem__() or .setdefault().

__save(self)

source code 

Save a database.

Only called by Database() internally. Use sync() to save the Database to the hard disk.

Reading and saving of the database is done by cPickle-ing the dict().

addChangedKey(self, key)

source code 

Add a key to the list of changed keys in the database.

This is useful if a change was made to an entry on a deeper level, meaning that the __set__() method of Database() is not called directly.

If the key is not added to this list manually, it will not make it into the database on the hard disk when calling the sync() method.

Parameters:
  • key (string) - the key you want to include in the next sync() call.

getDeletedKeys(self)

source code 

Return a list of all keys that have been deleted from the database in memory.

Returns: list
list of keys

getChangedKeys(self)

source code 

Return a list of all keys that have been changed in the database in memory.

Returns: list
list of keys

   Home       Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Fri Mar 30 10:45:20 2018 http://epydoc.sourceforge.net