pafera.db.DB Class Reference

The main database object. More...

Inheritance diagram for pafera.db.DB:

Public Member Functions
def	__del__ (self)
	Standard destructor to automatically close the database connection. More...
def	__getitem__ (self, key, value=None)
	Utility function to allow the database object itself to work like a big DB2 store. More...
def	__init__ (self, connectionname=None, dbname=None, dbhost='localhost', dbtype='sqlite', dbuser=None, dbpassword=None, dbflags=DB_SECURE|DB_TRACK_CHANGES|DB_TRACK_VALUES, closeondelete=1)
	Basic database constructor. More...
def	__setitem__ (self, key, value)
	Utility function to allow the database object itself to work like a big DB2 store. More...
def	ApplyAccess (self, origaccess, newaccess)
	Utility function to calculate access control. More...
def	ApplyACL (self, access, aclid)
	Get the rules for the given ACL. More...
def	Begin (self)
	Begins a transaction. More...
def	Close (self)
	Close the database connection. More...
def	Commit (self)
	Commits the current transaction. More...
def	CreateLinkTable (self, obj1, obj2)
	Creates the link table if necessary. More...
def	Debug (self, state)
	Enable or disable query debugging. More...
def	Delete (self, model, cond='', params=[])
	Deletes the given object or objects of the same type matching cond and params. More...
def	Execute (self, query, params=[], many=0, returndict=0)
	Executes a query upon the database. More...
def	ExecuteMany (self, query, params=[])
	Convenience function to execute many statements at once. More...
def	Find (self, model, cond='', params=[], **kwargs)
	The Pafera equivalent to SQL SELECT. More...
def	GetAccess (self, obj)
	Utility function to calculate the current user's access to the given database object. More...
def	GetACL (self, aclid)
	Get the rules for the given ACL. More...
def	GetLinkTable (self, obj1, obj2)
	Utility function to get the name of the database table between two objects. More...
def	HasGroup (self, groupname)
	Returns true if the current user belongs to the given group. More...
def	HasLink (self, model1, model1id, model2, model2id, linktype=0)
	Convenience function to check if two objects are linked without actually loading the objects themselves. More...
def	HasTable (self, table)
	Quick utility function to see if a table exists. More...
def	Insert (self, obj)
	db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code. More...
def	Link (self, obj1, obj2, linktype=0, linknum=0, comment='', flags=0)
	Linking is one of the fundamental concepts in Pafera. More...
def	LinkArray (self, obj1, obj2list, linktype=0, comment='', flags=0)
	A version of db.Link() that will erase all previous links of the same type and store the given links as an array. More...
def	Linked (self, obj1, model2, linktype=0, start=0, limit=1000, fields=' *', orderby='', cond='', params=[])
	Return the list of objects linked to this object with the given linktype. More...
def	LinkedToID (self, model1, model1id, model2, linktype=0, start=0, limit=1000, fields=' *', orderby='', cond='', params=[])
	Convenience function for checking what objects are linked to model1id without having to load the object itself. More...
def	Load (self, model, objid, fields=' *')
	Loads an object given its ID. More...
def	LoadMany (self, model, ids, fields=' *')
	Does the same thing as db.Load(), only you can load a number of objects at once. More...
def	MapFieldType (self, fieldtype)
	This function is responsible for mapping python types to their database representations. More...
def	Query (self, query, params=[])
	Convenience function to execute many statements at once. More...
def	RegisterModel (self, model)
	All models must be registered before use, which means creating the table, indexes, and storing a record of the model for use in the web database management interface. More...
def	Replace (self, obj)
	db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code. More...
def	RequireGroup (self, groupname, errmsg)
	Throws an exception if the current user does not belong to one of the groups listed in groupname. More...
def	Rollback (self)
	Rolls back the current transaction. More...
def	Save (self, obj, method='')
	This is the function where we convert python types and store them into the database. More...
def	Sudo (self, state)
	Enable or disable administrator mode, bypassing security for the current user. More...
def	Unlink (self, obj1, obj2, linktype=0)
	Unlink two objects, or if obj2 is a model, unlink every object of the given linktype. More...
def	UnregisterModel (self, model)
	Removes the model from the system registry. More...
def	Update (self, obj)
	db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code. More...

Public Attributes
	acls
	closed
	closeondelete
	connectionname
	cursor
	dbconn
	dbflags
	dbname
	dbtype
	debug
	groups
	language
	numdebugs
	numsudos
	objtypes
	userid

Static Public Attributes
dictionary	CONNECTIONS = {}
dictionary	DBTYPES
	DEFAULTCONN = None
string	DEFAULTFILE = "default.db"
dictionary	LANGUAGES

Detailed Description

The main database object.

Note that Pafera allows you to create as many database objects as you want, so you can keep one part of your logic in a MySQL database, one part in an Sqlite database, and so forth.

The current access is saved in db.userid and db.groups. Root access can be enabled at any time by calling db.Sudo(), while debugging is enabled through db.Debug().

Definition at line 163 of file db.py.

Constructor & Destructor Documentation

__init__()

def pafera.db.DB.__init__	(		self,
			connectionname = None,
			dbname = None,
			dbhost = 'localhost',
			dbtype = 'sqlite',
			dbuser = None,
			dbpassword = None,
			dbflags = DB_SECURE | DB_TRACK_CHANGES | DB_TRACK_VALUES,
			closeondelete = 1
	)

Basic database constructor.

Note that security must be enabled on *both* the database and the model to take effect.

Using closeondelete means that the object will automatically close the database
connection when it goes out of scope.

Definition at line 190 of file db.py.

__del__()

def pafera.db.DB.__del__

(

self

)

Standard destructor to automatically close the database connection.

Definition at line 285 of file db.py.

Member Function Documentation

__getitem__()

def pafera.db.DB.__getitem__	(		self,
			key,
			value = None
	)

Utility function to allow the database object itself to work like a big DB2 store.

Definition at line 813 of file db.py.

__setitem__()

def pafera.db.DB.__setitem__	(		self,
			key,
			value
	)

Utility function to allow the database object itself to work like a big DB2 store.

Definition at line 825 of file db.py.

ApplyAccess()

def pafera.db.DB.ApplyAccess	(		self,
			origaccess,
			newaccess
	)

Utility function to calculate access control.

You should not need to call this yourself since it's automatically handled by db.GetAccess()

Definition at line 522 of file db.py.

ApplyACL()

def pafera.db.DB.ApplyACL	(		self,
			access,
			aclid
	)

Get the rules for the given ACL.

You should not need to call this yourself since it's automatically handled by db.GetAccess()

Definition at line 500 of file db.py.

Begin()

def pafera.db.DB.Begin

(

self

)

Begins a transaction.

Useful if you don't use auto-commit mode.

Definition at line 306 of file db.py.

Close()

def pafera.db.DB.Close

(

self

)

Close the database connection.

You should normally never need to call this since the object will automatically close the connectino when it goes out of scope

Definition at line 292 of file db.py.

Commit()

def pafera.db.DB.Commit

(

self

)

Commits the current transaction.

Be sure to call this at the end of your script or none of your changes will take effect.

Definition at line 320 of file db.py.

CreateLinkTable()

def pafera.db.DB.CreateLinkTable	(		self,
			obj1,
			obj2
	)

Creates the link table if necessary.

Definition at line 1179 of file db.py.

Debug()

def pafera.db.DB.Debug	(		self,
			state
	)

Enable or disable query debugging.

Definition at line 430 of file db.py.

Delete()

def pafera.db.DB.Delete	(		self,
			model,
			cond = '',
			params = []
	)

Deletes the given object or objects of the same type matching cond and params.

As with any deletion function, make sure that you're *really* sure before
using this. If in doubt, enable DB_TRACK_VALUES on this model so that you can
get the object back if you've made a mistake.

Definition at line 1118 of file db.py.

Execute()

def pafera.db.DB.Execute	(		self,
			query,
			params = [],
			many = 0,
			returndict = 0
	)

Executes a query upon the database.

Use db.Query() if you need a version which automatically wraps the returned values into a dict. Use db.Debug() to see what is being done behind the scenes.

Definition at line 342 of file db.py.

ExecuteMany()

def pafera.db.DB.ExecuteMany	(		self,
			query,
			params = []
	)

Convenience function to execute many statements at once.

Separated into its own function for more readable code.

Definition at line 407 of file db.py.

Find()

def pafera.db.DB.Find	(		self,
			model,
			cond = '',
			params = [],
		**	kwargs
	)

The Pafera equivalent to SQL SELECT.

All it does is to pass the parameters to DBList()'s constructor.

cond is the filter such as WHERE or HAVING

params is a list of parameters to be used in the query. SQL injections are still a thing in 2016, so if you're still manually constructing queries, be sure that you know what you're doing.

Other available parameters are fields, start, limit, and orderby. They do pretty much what you think they do in constructing the underlying SQL query.

Definition at line 1090 of file db.py.

GetAccess()

def pafera.db.DB.GetAccess	(		self,
			obj
	)

Utility function to calculate the current user's access to the given database object.

It's only effective if security is enabled on both the database and the object's model.

Definition at line 464 of file db.py.

GetACL()

def pafera.db.DB.GetACL	(		self,
			aclid
	)

Get the rules for the given ACL.

You should not need to call this yourself since it's automatically handled by db.GetAccess()

Definition at line 487 of file db.py.

GetLinkTable()

def pafera.db.DB.GetLinkTable	(		self,
			obj1,
			obj2
	)

Utility function to get the name of the database table between two objects.

Use this if you need to do any manual operations on link tables.

Definition at line 1160 of file db.py.

HasGroup()

def pafera.db.DB.HasGroup	(		self,
			groupname
	)

Returns true if the current user belongs to the given group.

Definition at line 458 of file db.py.

HasLink()

def pafera.db.DB.HasLink	(		self,
			model1,
			model1id,
			model2,
			model2id,
			linktype = 0
	)

Convenience function to check if two objects are linked without actually loading the objects themselves.

Commonly used to check for membership in a group.

Definition at line 1423 of file db.py.

HasTable()

def pafera.db.DB.HasTable	(		self,
			table
	)

Quick utility function to see if a table exists.

For model tables, the same functionality could be achieved by checking db._objtypes,
but there is always the possibility that another script has created a table between
the initialization of the database object and the current running code, so it's 
always best to be sure by directly querying the database itself.

Definition at line 798 of file db.py.

Insert()

def pafera.db.DB.Insert	(		self,
			obj
	)

db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code.

Definition at line 832 of file db.py.

Link()

def pafera.db.DB.Link	(		self,
			obj1,
			obj2,
			linktype = 0,
			linknum = 0,
			comment = '',
			flags = 0
	)

Linking is one of the fundamental concepts in Pafera.

It's essentially a foreign key mechanism that can link two arbitary objects via their database IDs, thus you can do things like

u = new user g = new group

Link the user and group

db.Link(u, g)

prints g's information

print(db.Linked(u, group))

Linking is a bidirectional operation, meaning that both db.Linked(u, group) and db.Linked(g, user) will work. For unidirectional links, it's suggested to store the linked IDs in a NEWLINELIST field in an object itself.

Behind the scenes, linking works by create a separate table that connects IDs between one table and other. Any attempt to find links are returned in a DBList() object which performs a SQL JOIN for one query results.

Linking supports different types of links via the linktype parameter.

The linknum parameter is used to create results that are returned in order of linknum, guaranteeing that the same sequence will be returned every time.

flags can be used to store application-specific meanings outside of linktype.

Definition at line 1204 of file db.py.

LinkArray()

def pafera.db.DB.LinkArray	(		self,
			obj1,
			obj2list,
			linktype = 0,
			comment = '',
			flags = 0
	)

A version of db.Link() that will erase all previous links of the same type and store the given links as an array.

This is useful for representing tree diagrams from the normally flat SQL architecture outside of advanced usage in PostgreSQL and the sort.

Definition at line 1286 of file db.py.

Linked()

def pafera.db.DB.Linked	(		self,
			obj1,
			model2,
			linktype = 0,
			start = 0,
			limit = 1000,
			fields = '*',
			orderby = '',
			cond = '',
			params = []
	)

Return the list of objects linked to this object with the given linktype.

Note that this function returns a DBList(), so if you have many objects linked, it will automatically separate them into chunks while iterating through them.

Definition at line 1451 of file db.py.

LinkedToID()

def pafera.db.DB.LinkedToID	(		self,
			model1,
			model1id,
			model2,
			linktype = 0,
			start = 0,
			limit = 1000,
			fields = '*',
			orderby = '',
			cond = '',
			params = []
	)

Convenience function for checking what objects are linked to model1id without having to load the object itself.

Definition at line 1527 of file db.py.

Load()

def pafera.db.DB.Load	(		self,
			model,
			objid,
			fields = '*'
	)

Loads an object given its ID.

Like many other database designers, I consider giving every row its own ID value to be convenient despite the added space requirements.

Definition at line 1034 of file db.py.

LoadMany()

def pafera.db.DB.LoadMany	(		self,
			model,
			ids,
			fields = '*'
	)

Does the same thing as db.Load(), only you can load a number of objects at once.

This is separated into its own function since it actually involves different syntax in returning an array versus returning a single object.

Definition at line 1066 of file db.py.

MapFieldType()

def pafera.db.DB.MapFieldType	(		self,
			fieldtype
	)

This function is responsible for mapping python types to their database representations.

If you are using a database outside of MySQL or SQLite, be sure to add the conversions here.

Definition at line 709 of file db.py.

Query()

def pafera.db.DB.Query	(		self,
			query,
			params = []
	)

Convenience function to execute many statements at once.

Separated into its own function for more readable code.

Definition at line 414 of file db.py.

RegisterModel()

def pafera.db.DB.RegisterModel	(		self,
			model
	)

All models must be registered before use, which means creating the table, indexes, and storing a record of the model for use in the web database management interface.

You normally do not need to call this function itself since any database function like db.Find(), db.Load(), and db.Save() will automatically do it for you.

Definition at line 564 of file db.py.

Replace()

def pafera.db.DB.Replace	(		self,
			obj
	)

db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code.

Definition at line 848 of file db.py.

RequireGroup()

def pafera.db.DB.RequireGroup	(		self,
			groupname,
			errmsg
	)

Throws an exception if the current user does not belong to one of the groups listed in groupname.

It's a less expensive check than going through object security.

Definition at line 439 of file db.py.

Rollback()

def pafera.db.DB.Rollback

(

self

)

Rolls back the current transaction.

This will also automatically be done if you end the script without calling db.Commit()

Definition at line 331 of file db.py.

Save()

def pafera.db.DB.Save	(		self,
			obj,
			method = ''
	)

This is the function where we convert python types and store them into the database.

Any fields named "rid" or "rbid" will be automatically given a randomized non-existing value. You can check its value on the object after this function returns.

Security fields will be automatically added if security is enabled for both the database and the object's model.

Definition at line 856 of file db.py.

Sudo()

def pafera.db.DB.Sudo	(		self,
			state
	)

Enable or disable administrator mode, bypassing security for the current user.

Definition at line 421 of file db.py.

Unlink()

def pafera.db.DB.Unlink	(		self,
			obj1,
			obj2,
			linktype = 0
	)

Unlink two objects, or if obj2 is a model, unlink every object of the given linktype.

Use with caution.

Definition at line 1373 of file db.py.

UnregisterModel()

def pafera.db.DB.UnregisterModel	(		self,
			model
	)

Removes the model from the system registry.

Useful if you're uninstalling an app.

Definition at line 698 of file db.py.

Update()

def pafera.db.DB.Update	(		self,
			obj
	)

db.Insert(), db.Update(), and db.Replace() are all convenient wrappers to the underlying db.Save() function for easier readability of code.

Definition at line 840 of file db.py.

Member Data Documentation

acls

pafera.db.DB.acls

Definition at line 221 of file db.py.

closed

pafera.db.DB.closed

Definition at line 220 of file db.py.

closeondelete

pafera.db.DB.closeondelete

Definition at line 218 of file db.py.

connectionname

pafera.db.DB.connectionname

Definition at line 225 of file db.py.

CONNECTIONS

dictionary pafera.db.DB.CONNECTIONS = {}

static

Definition at line 185 of file db.py.

cursor

pafera.db.DB.cursor

Definition at line 219 of file db.py.

dbconn

pafera.db.DB.dbconn

Definition at line 233 of file db.py.

dbflags

pafera.db.DB.dbflags

Definition at line 217 of file db.py.

dbname

pafera.db.DB.dbname

Definition at line 226 of file db.py.

dbtype

pafera.db.DB.dbtype

Definition at line 216 of file db.py.

DBTYPES

dictionary pafera.db.DB.DBTYPES

static

Initial value:

=   {
    'sqlite':     1,
    'mysql':      2,
    'postgresql': 3,
  }

Definition at line 179 of file db.py.

debug

pafera.db.DB.debug

Definition at line 208 of file db.py.

DEFAULTCONN

pafera.db.DB.DEFAULTCONN = None

static

Definition at line 186 of file db.py.

DEFAULTFILE

string pafera.db.DB.DEFAULTFILE = "default.db"

static

Definition at line 187 of file db.py.

groups

pafera.db.DB.groups

Definition at line 212 of file db.py.

language

pafera.db.DB.language

Definition at line 209 of file db.py.

LANGUAGES

dictionary pafera.db.DB.LANGUAGES

static

Initial value:

=   {
    1:  ('en', 'English', 'English'),
    2:  ('zh', 'Chinese', '中文'),
  }

Definition at line 174 of file db.py.

numdebugs

pafera.db.DB.numdebugs

Definition at line 215 of file db.py.

numsudos

pafera.db.DB.numsudos

Definition at line 214 of file db.py.

objtypes

pafera.db.DB.objtypes

Definition at line 210 of file db.py.

userid

pafera.db.DB.userid

Definition at line 211 of file db.py.

---

The documentation for this class was generated from the following file:

• /srv/flasksite/pafera/db.py