Agent
Using agents
Agents are used as database connection for Record and Selection instances. (see Record and Selection)What is an agent?
An agent instance is the core container of a database connection.
It not only knows the graffle it applies to (graffle), but also does selection, caching, etc.
The record caching is through weak references only, so records get called by __del__ when deleted. They will ask the agent to write them to the database if changed. If the graffle is None then a dictionary with table/field descriptors should be defined “manually”.
The record caching is through weak references only, so records get called by __del__ when deleted. They will ask the agent to write them to the database if changed. If the graffle is None then a dictionary with table/field descriptors should be defined “manually”.
An overview
The Agent class contains the following methods:| Method | Attributes | Docstring or default value |
|---|---|---|
| closedb | ||
| count | table where |
Answer the size of the selection.
|
| delete | id table |
Delete the record from the database and the cache.
|
| deletecache | id table |
Delete all records from the cache (thus making them save themselves if changed
and if there is not other reference to any of them).
|
| deleterecord | id table |
Frist delete all records the cache, to make there there are no links to the record to be deleted.
Then delete the record for the table named table with id id. Note: We assume here that the record has record._readonly set to False. |
| dump | path table |
Make a dump of the whole database to a local file as defined by the path attribute
as an SQL insert instruction set. If the table is defined, then only make a dump of the content of that table. Note: The structure of the database tables is not written to the file. |
| exists | id table where |
Test if there are records that fit this where clause. If id is defined, then add this to the defined where clause. id can be either None, int and string. Python example agent = Agent('test/datamodel.graffle', 'elia') agent.open() print agent.exists('address', 12345) print agent.exists('address', 19) agent.closedb() |
| fieldnames | table |
The fieldnames method does answer the fieldnames of the agent’s database
for the requested table. If the descriptor does not exist (e.g. when there was no
graffle defined), then answer None.
Python example agent.fieldnames('address') |
| fillnormalized | data table |
Remove all normalized records and fill the table named table with the content of data
dictionary with the layout {1: 'aaa', 2: 'bbb', ...} or layout ((1, 'aaa'), (2, 'bbb'), ...).
This method is especially used to initialize (small) normalized option tables from a Python source.
Python example options = {1: 'aaa', 2: 'bbb', 3: 'ccc', 4: 'ddd', 5: 'eee'} agent.fillnormalized('address_options_n', options) |
| getcache | id table |
Get a record from the cache.
|
| getdescriptor | table |
Answer the descriptor of the table named table. If the descriptor does not
exist (e.g. when there was no graffle defined) or if it the descriptor does not contain
the request table name, then answer None.
|
| getdescriptors |
Answer the descriptors of all tables of the agent database.
|
|
| getnormalized | order table where |
Read a whole set of normalized values at once so they can be used e.g. in popup option sets.
Always order them alphabetically on the values. Answer a tuple of a list of records of type [{'id': 1, 'value': 'aaa'}, ...]
(used as option list in a popup) and a dictionary for type {1: 'aaa', 2: 'bbb', ...} to be used to find the
value for a specific normalized id. This was a bug intil 2008-10-01, where the core records were answered. They behave very strange when converted to strings.
Now we create a record like dictionary to answer, which is compatible to the original record. If the value is of type basestring then convert it into unicode. See also: fillnormalized Python example agent.getnormalized('address_options_n') |
| getquery | query |
The getquery does execute query and then answers the result.
Transform the unicode query to UTF-8 before calling the database driver.
The last query executed is retrieved by agent.lastquery().
|
| getrecord | id table |
Read a single records from the database with the specified id.
This method should not be called from an application, since it only answers the datastructure of
the query. Better to call xpyth.xierpa.db.record.getrecord. See also: xpyth.xierpa.db.record.getrecord See also: Record Python example record = agent.getrecord('address', 123) |
| getselection | astable distinct fields mode order slice start table where |
Read muliple records from the database in the defined order as slice. The where is added
as SQL qhere clause to the SQL query. This method should not be called from an application, since it only answers the datastructure of the query. Better to call xpyth.xierpa.db.selection.getselection. If the astable attribute is defined, that use that as name in the ... tablename as aliasname ... query construction. See also: xpyth.xierpa.db.selection.getselection See also: Selection Python example selection = agent.getselection('address', readonly=False) |
| lastquery |
Answer the last executed query.
|
|
| max | field table where |
Answer the max value of field (default value is 'id' of all selected records.
Used with the id field, this can be used to get the id of the latest inserted record.
Python example agent = Agent('test/datamodel.graffle', 'elia') agent.open() print agent.max('address') > 0 agent.closedb() |
| opendb | ||
| putcache | id record table |
Put a record in the cache.
|
| query | query |
The getquery does execute query.
Transform the unicode query to UTF-8 before calling the database driver.
The last query executed is retrieved by agent.lastquery().
|
| querycount |
Answer the current number of executed queries.
|
|
| read | id table |
Read actual data from database when not done before.
Make sure there is only one record result. Or else we have a non-existing id or there are multiples. Note: All fields of a record are used as plain names, so all other attributes have a preceeding "_". |
| write | changedfields data forceinsert id table |
Write the record only when it changed AND when the record is writable AND there is any data to write.
(This record may already have been deleted). Do an insert or update depending on the value of id.
Only write the fields which names are in the changedfields list. Fields that contain None are set as SQL NULL. Todo: Better to block the record between insert and getting max id value, since in theory another record can be made by another application. |