Difference between revisions of "0.23 Python bindings/Advanced"

Revision as of 08:40, 11 February 2010

This page contains an advanced reference to the low level objects available in the Python bindings. Note that most of these objects were never intended to be used directly, and will have to be subclassed before they function.

MythDBConn(dbconn)

This takes a single dictionary as an argument, containing the keys 'DBUserName', 'DBHostName', 'DBPassword', 'DBName', and 'DBPort'. Unless you have very good reason to, you shouldn't be using this class directly.

MythDBBase(db=None, args=None, **kwargs)

The input arguments for this behave identically to those in MythDB or MythVideo. This is the basic database connection class, and provides a subset of the functions found therein. Available functions are the 'tablefields' and 'settings' objects, as well as the getStorageGroup() and cursor() functions. Cursor returns an object of type MythDBCursor, which can be altered using the 'cursorclass' attribute. This class manages caching of MythDBConn connections, and automatically disconnects them when no longer in use. This class handles reading of database config files, as well as UPnP auto-negotiation.

MythDBCursor(connection)

This is the altered MySQLdb cursor class used by the Python bindings. This behaves identically to a normal cursor, however it has a 'log' attribute that is used for logging. The execute() and executemany() functions have been overridden to perform logging on each statement sent to the SQL server.

MythBEConn(backend, type, db=None)

This takes 'backend' as a IP or hostname, pulling the port from the database. If 'backend' is None, the master settings are used. This provides a single connection to the backend, and should probably never be used directly.

MythBEBase(backend=None, type='Monitor', db=None, single=False)

The input arguments for this behave identically to those in MythBE. This is the basic backend socket connection class. Provided functions are backendCommand(), joinInt(), and splitInt(). The latter two are for dealing with int64 values, transferred over the backend socket as a pair of int32 values. The former takes a string command, and returns the string response from the backend. This class provides connection caching of MythBEConn connections, automatically closing them when no longer in use.

announce(type)

The announce function can be overwritten, as exampled in FileTransfer. It's purpose is to identify itself to the backend, and error if the correct response is not given.

MythXMLConn(backend=None, db=None, port=None)

This class sets up a backend to connect to and pull data from the status server. Unless provided, the port and if necessary, master backend IP, will be pulled from the database. This does not have any persistent connection.

_query(path=None, **keyvars)

Returns a string of the response from:

http://<host>:<port>/
  ---or---
http://<host>:<port>/Myth/<path>

?key1=value1&key2=value2&...

_queryTree(path=None, **keyvars)

Behaves as _query, but returns an ElementTree object of the response.

databaseSearch(func)

This is a decorator class used for the search functions in MythVideo() and MythDB(). Functions using this decorator must provide the 'init', 'key', and 'value' input arguments.

The 'init' input is a boolean called once to describe the function to the decorator. The function must return a tuple containing three or more values.

1. Database table to be searched
2. Class to be used for handling responses
3. Tuple of keys that must be passed whether given during the call or not
4. (optional) One or more 'join' descriptors of the following format.
   1. New table to add in the join
   2. Existing table to be joined to
   3. Tuple of columns names to be used for matching in the join
   4. (optional) Tuple of column names in the existing table. If not provided, previous tuple of names are used for both tables.

The 'key' and 'value' pairs are used by the function to define a 'where' string, and if necessary, perform processing on the value. The function must return a tuple containing the following three values.

1. Where string
2. Value to be used in the where string
3. Bitwise identifier to denote that one or more of the defined 'joins' must be used

DictData(raw)

DBData(data=None, db=None, raw=None)

DBDataWrite(data=None, db=None, raw=None)

DBDataRef(where, db=None)

DBDataCRef(where, db=None)