0.23 Python bindings/Advanced

From MythTV Official Wiki
Revision as of 13:15, 20 July 2010 by Wagnerrp (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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>
Additional keyword arguments are used as GET parameters in the form:
?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)

This class is intended for processing lists of text data, generally received from the backend over Myth Protocol. This class requires two class variables to be defined.

  • field_order - This is a list of strings of field names, in the order they are expected to be received.
  • field_type - This is an integer list of types of data contained within the fields. The raw input is processed as per the types specified in this list. If the list is instead a single string 'Pass', no processing is performed
    • 0 - integer
    • 1 - float
    • 2 - boolean
    • 3 - string
    • 4 - timestamp

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

This class is a customized DictData class, for the purpose of receiving data from a database table. One instance of this class corresponds to one line in the database. This class requires the following class variables to be defined.

  • table - This is a string of the database table to perform operations against.
  • where - This is a string to be used in the WHERE clause of the SQL command.
  • setwheredat - This is a string that when eval(setwheredat) is run, a tuple containing the data to match 'where' is returned.

In addition, there are several other class variables that alter the behavior of this class.

  • allow_empty - This boolean determines whether an object is allowed to be created without initializing against a database entry.
  • schema_value - This is an alternate settings value to use to check for matching database schema versions.
  • schema_version - This is an integer of the local value of the schema the class is designed to work with.
  • schema_name - This is a human readable name to be used in logging and error output.

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

This class is a customized DBData class, allowing editing and creation of database entries. In addition to the class variables used by DBData, this offers an additional optional variable.

  • defaults - This is a dictionary containing the default values to be used when creating a new entry. If a value is set to 'None', the class will never attempt to alter the value of that field stored in the database.

DBDataRef(where, db=None)

DBDataCRef(where, db=None)