0.25 Python Bindings/Advanced

This page is for advanced objects, not included in the normal import of the bindings, and for most purposes are not needed.

Connection Classes

DBConnection

This connection takes a single input, dbconn, which is a dictionary containing:

• DBUserName
• DBHostName
• DBPassword
• DBName
• DBPort

This class provides automatic connection pooling. All database access is performed through the cursor interface, and in order to maintain thread safety, a single connection will only be shared among cursors of the same thread. If more threads attempt to access the database simultaneously than there are connections, a new single use connection will be opened for that specific cursor.

'release' and 'acquire' methods are available to manage the use of connections in the pool, and to automatically spawn new ones if needed. '__enter__' and '__exit__' exist for use as a context manager, and will return a new cursor to use. Each thread is given its own stack in the context manager, so multiple nested cursors are allowed.

The pool size is adjustable. The default pool size for new connection objects can be set with the 'setDefaultSize' classmethod, and an existing connection can be resized with the 'resizePool' method.

BEConnection

This connection takes the following inputs:

• backend - must be an IP address
• port
• localname=None - if not set, will pull it from socket.gethostname()
• opts=None - a BEConnOpts dictionary providing the capabilities of the connection
• deadline=10 - a float specifying how long a query may wait for a response

Data Handling Classes

DictData

This class is based off the ordered dictionary implementation, and intends to provide access to lists of data as dictionary fields and class attributes. For use, this must be subclassed, and the following attributes provided:

• _field_order - a list of strings containing field names in the order they will be input
• _field_type - a list of integers indicating the type of data for each field
  1. integer
  2. float
  3. string
  4. unix timestamp (epoch time)
  5. date in ISO8601 format
  6. timestamp in RFC822 format

This class is initialized by providing a list of data, conforming to the provided _field_order and _field_type.

DBData

This class is based off DictData, and provides similar access for database entries. This class will set itself up completely automatically if allowed, but its defaults can be overridden by the following attributes:

• _logmodule - used to identify the component printing the log

defaults to 'Python %s' % cls.__name__

• _table - used to specify which database table this class should pull from

defaults to cls.__name__

• _key - used to determine what fields to use to uniquely identify a database entry

defaults to table primary key

• _where - used to generate SQL to search for unique entry

defaults to <_key[0]>=%s AND <_key[1]>=%s AND <_key[2]>=%s AND ...

• _setwheredat - used to set _wheredat and provide the necessary arguments to the _where clause

defaults to self.<_key[0]>,self.<_key[1]>,self.<_key[2]>,...

This class can be initialized in three manners:

1. Supply the necessary information for the _key

   Recorded((chanid,starttime))

2. Supply the raw data from the database

   Recorded.fromRaw(cursor.fetchone())

3. Pull all information from the database table

   Recorded.getAllEntries()

DBDataWrite

This class is based off DBData, and allows for creating, editing, and deleting entries. This class allows an extra attribute _defaults which can be used to populate default values when creating new entries. Any field marked as None will be stripped before being sent to the database, for creation or updates.

Assorted Utility

SchemaUpdate

This class is intended to facilitate managing database schema for external plugins. This class must be subclassed, providing a _schema_name string, matching the setting field used to store the schema version. The create method is called if the variable is not set, and up<version> is called to update the schema. The final schema must issue a StopIteration to terminate the loop.

class MySchemaUpdate( SchemaUpdate ):
    _schema_name = 'MyDBSchemaVer'
    def create(self):
        with self.db.cursor(self.log) as cursor:
            cursor.execute("""CREATE TABLE ....""")
        return 1000
    def up1000(self):
        with self.db.cursor(self.log) as cursor:
            cursor.execute("""UPDATE ....""")
    def up1001(self):
        with self.db.cursor(self.log) as cursor:
            cursor.execute("""UPDATE ....""")
    def up1002(self): raise StopIteration

db = MythDB()
up = MySchemaUpdate(db)
up.run()

This class can also be passed to the DBCache._check_schema() call, or run automatically by setting the _schema_update variable in a DBData class.

databaseSearch

This class is a decorator intended to be used on methods of DBCache classes. The decorator allows for simple construction of complex queries, returning a generator of DBData or DBDataWrite objects. The method being wrapped must accept three keyword inputs.

• init
• key
• value

init

This argument will only be provided when the search is being set up. Init is the wrapper, which must be configured to properly use the database. Several attributes must be defined before the decorator will function.

• table - the database table to pull information from.
• handler - the DBData or DBDataWrite class to feed data to. Must at minimum provide a fromRaw classmethod.
• required - a tuple of any fields that must be used in the query, whether provided when called or not.
• joins - a tuple of Join objects, defining any additional tables to JOIN in during the search.

Join

This class defines a new table to be joined in during a search, and requires the following keywords.

• table - the new database table to pull in
• tableto - the existing table to JOIN it to

Additionally, one of the following two sets must be provided.

• matching field names in both tables
  • fields - a tuple of fields to JOIN on, if the two tables use the same names
• different field names in each table
  • fieldsfrom - a tuple of fields used in the new table being pulled in
  • fieldsto - a tuple of matching fields used in the existing table

use

If init is not provided, key and value will be populated. These are the key/value pairs used when the method is called during use. The method must return a tuple containing a string with a WHERE argument, a value to pass into that argument, and a bitwise argument of what JOIN definitions to pull in during the search.

SplitInt

This class is to be included for use with dealing with data over Myth Protocol. It provides two staticmethods, splitInt and joinInt, which convert between a 64-bit long and two 32-bit ints.

CMPVideo

This class is to be included in DictData classes with title and subtitle fields. It allows comparison between classes with such fields for alphabetical sorting, first using title and then subtitle.

CMPRecord

This class is to be included in DictData classes dealing with recordings. It allows comparison between classes for alphabetical sorting , first using starttime and then chanid, falling through to CMPVideo if those fields do not exist.

MARKUPLIST

This class is to be included in classes dealing with markup information. It includes a _buildlist(start, end) method used to produce edit lists.

>>> rec = Recorded.getAllEntries().next()
## pull list of commercial breaks
>>> rec.markup._buildlist(static.MARKUP.MARK_COMM_START,static.MARKUP.MARK_COMM_END)
[(21113, 25761), (39842, 45553), (56389, 62395), (79798, 85832), (93379, 99973), (109325, 110523)]
## pull list of wanted content
>>> rec.markup._buildlist(static.MARKUP.MARK_COMM_END,static.MARKUP.MARK_COMM_START)
[(0, 21113), (25761, 39842), (45553, 56389), (62395, 79798), (85832, 93379), (99973, 109325), (110523, 9999999)]