Difference between revisions of "0.24 Python Bindings"

From MythTV Official Wiki
Jump to: navigation, search
m (Utility)
m (missed one)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
The MythTV Python bindings are a set of bindings designed to provide access to the MythTV database and interfaces in an object oriented, 'pythonic' manner.  If upgrading from 0.23, please see the [[Trunk Python bindings/Upgrade Guide|upgrade guide]].
+
The MythTV Python bindings are a set of bindings designed to provide access to the MythTV database and interfaces in an object oriented, 'pythonic' manner.  If upgrading from 0.23, please see the [[0.24 Python bindings/Upgrade Guide|upgrade guide]].
  
 
=== Requirements ===
 
=== Requirements ===
Line 13: Line 13:
 
The data model used in the bindings is based around the DictData class, an ordered dictionary class intended to abstract lists of data provided by the backend and database, and provide them to users as dictionary values or object attributes.
 
The data model used in the bindings is based around the DictData class, an ordered dictionary class intended to abstract lists of data provided by the backend and database, and provide them to users as dictionary values or object attributes.
  
== [[Trunk Python bindings/Connection Handlers|Connection Classes]] ==
+
== [[0.24 Python bindings/Connection Handlers|Connection Classes]] ==
* [[Trunk Python bindings/Connection Handlers#MythDB|MythDB]] - top level database connection
+
* [[0.24 Python bindings/Connection Handlers#MythDB|MythDB]] - top level database connection
* [[Trunk Python bindings/Connection Handlers#MythBE|MythBE]] - top level [[:Category:Myth Protocol|mythproto]] connection
+
* [[0.24 Python bindings/Connection Handlers#MythBE|MythBE]] - top level [[:Category:Myth Protocol|mythproto]] connection
* [[Trunk Python bindings/Connection Handlers#MythXML|MythXML]] - pseudo-connection for accessing the XML interface
+
* [[0.24 Python bindings/Connection Handlers#MythXML|MythXML]] - pseudo-connection for accessing the XML interface
* [[Trunk Python bindings/Connection Handlers#Frontend|Frontend]] - connection to frontend telnet control
+
* [[0.24 Python bindings/Connection Handlers#Frontend|Frontend]] - connection to frontend socket control
* [[Trunk Python bindings/Connection Handlers#MythVideo|MythVideo]] - database connection for managing mythvideo
+
* [[0.24 Python bindings/Connection Handlers#MythVideo|MythVideo]] - database connection for managing mythvideo
* [[Trunk Python bindings/Connection Handlers#MythMusic|MythMusic]] - database connection for managing mythmusic
+
* [[0.24 Python bindings/Connection Handlers#MythMusic|MythMusic]] - database connection for managing mythmusic
* [[Trunk Python bindings/Connection Handlers#BEEventMonitor|BEEventMonitor]] - diagnostic mythproto connection for displaying events
+
* [[0.24 Python bindings/Connection Handlers#BEEventMonitor|BEEventMonitor]] - diagnostic mythproto connection for displaying events
* [[Trunk Python bindings/Connection Handlers#MythSystemEvent|MythSystemEvent]] - implementation of the [[MythTV System Events|system event]] handler
+
* [[0.24 Python bindings/Connection Handlers#MythSystemEvent|MythSystemEvent]] - implementation of the [[MythTV System Events|system event]] handler
  
== [[Trunk Python bindings/Data Handlers|Data Classes]] ==
+
== [[0.24 Python bindings/Data Handlers|Data Classes]] ==
=== [[Trunk_Python_bindings/Data_Handlers#Backend_Data|Backend Data]] ===
+
=== [[0.24 _Python_bindings/Data_Handlers#Backend_Data|Backend Data]] ===
* [[Trunk Python bindings/Data Handlers#FreeSpace|FreeSpace]]
+
* [[0.24 Python bindings/Data Handlers#FreeSpace|FreeSpace]]
* [[Trunk Python bindings/Data Handlers#Program|Program]]
+
* [[0.24 Python bindings/Data Handlers#Program|Program]]
=== [[Trunk_Python_bindings/Data_Handlers#Database_Read-Only|Database Read-Only]] ===
+
=== [[0.24 _Python_bindings/Data_Handlers#Database_Read-Only|Database Read-Only]] ===
* [[Trunk Python bindings/Data Handlers#Guide|Guide]]
+
* [[0.24 Python bindings/Data Handlers#Guide|Guide]]
* [[Trunk Python bindings/Data Handlers#InternetContent|InternetContent]]
+
* [[0.24 Python bindings/Data Handlers#InternetContent|InternetContent]]
* [[Trunk Python bindings/Data Handlers#InternetContentArticles|InternetContentArticles]]
+
* [[0.24 Python bindings/Data Handlers#InternetContentArticles|InternetContentArticles]]
=== [[Trunk_Python_bindings/Data_Handlers#Database_Read-Write|Database Read-Write]] ===
+
=== [[0.24 _Python_bindings/Data_Handlers#Database_Read-Write|Database Read-Write]] ===
* [[Trunk Python bindings/Data Handlers#Record|Record]]
+
* [[0.24 Python bindings/Data Handlers#Record|Record]]
* [[Trunk Python bindings/Data Handlers#Recorded|Recorded]]
+
* [[0.24 Python bindings/Data Handlers#Recorded|Recorded]]
* [[Trunk Python bindings/Data Handlers#RecordedProgram|RecordedProgram]]
+
* [[0.24 Python bindings/Data Handlers#RecordedProgram|RecordedProgram]]
* [[Trunk Python bindings/Data Handlers#OldRecorded|OldRecorded]]
+
* [[0.24 Python bindings/Data Handlers#OldRecorded|OldRecorded]]
* [[Trunk Python bindings/Data Handlers#Job|Job]]
+
* [[0.24 Python bindings/Data Handlers#Job|Job]]
* [[Trunk Python bindings/Data Handlers#Channel|Channel]]
+
* [[0.24 Python bindings/Data Handlers#Channel|Channel]]
* [[Trunk Python bindings/Data Handlers#Video|Video]]
+
* [[0.24 Python bindings/Data Handlers#Video|Video]]
* [[Trunk Python bindings/Data Handlers#Song|Song]]
+
* [[0.24 Python bindings/Data Handlers#Song|Song]]
* [[Trunk Python bindings/Data Handlers#Album|Album]]
+
* [[0.24 Python bindings/Data Handlers#Album|Album]]
* [[Trunk Python bindings/Data Handlers#Artist|Artist]]
+
* [[0.24 Python bindings/Data Handlers#Artist|Artist]]
* [[Trunk Python bindings/Data Handlers#MusicPlaylist|MusicPlaylist]]
+
* [[0.24 Python bindings/Data Handlers#MusicPlaylist|MusicPlaylist]]
* [[Trunk Python bindings/Data Handlers#MusicDirectory|MusicDirectory]]
+
* [[0.24 Python bindings/Data Handlers#MusicDirectory|MusicDirectory]]
  
== [[Trunk_Python_bindings/System_Calls|External Classes]] ==
+
== [[0.24 Python_bindings/System_Calls|External Classes]] ==
 
These classes provide access to external functions.
 
These classes provide access to external functions.
* [[Trunk_Python_bindings/System_Calls#System|System]] - manages calling external scripts and programs
+
* [[0.24 Python_bindings/System_Calls#System|System]] - manages calling external scripts and programs
* [[Trunk_Python_bindings/System_Calls#Grabber|Grabber]] - modified system class for the [[MythTV_Universal_Metadata_Format|universal grabber syntax]]
+
* [[0.24 Python_bindings/System_Calls#Grabber|Grabber]] - modified system class for the [[MythTV_Universal_Metadata_Format|universal grabber syntax]]
* [[Trunk_Python_bindings/System_Calls#VideoGrabber|VideoGrabber]] - modified grabber class for pulling data from MythVideo grabbers
+
* [[0.24 Python_bindings/System_Calls#VideoGrabber|VideoGrabber]] - modified grabber class for pulling data from MythVideo grabbers
* [[Trunk_Python_bindings/System_Calls#InternetSource|InternetSource]] - class for pulling data from MythNetvision grabbers over MythXML
+
* [[0.24 Python_bindings/System_Calls#InternetSource|InternetSource]] - class for pulling data from MythNetvision grabbers over MythXML
* [[Trunk_Python_bindings/System_Calls#SystemEvent|SystemEvent]] - modified system class emulating the system event handler in MythTV
+
* [[0.24 Python_bindings/System_Calls#SystemEvent|SystemEvent]] - modified system class emulating the system event handler in MythTV
  
 
== Other Classes ==
 
== Other Classes ==
Line 150: Line 150:
 
=== datetime ===
 
=== datetime ===
  
== [[Trunk_Python_bindings/Advanced|Advanced Use]] ==
+
== [[0.24 Python_bindings/Advanced|Advanced Use]] ==
* [[Trunk_Python_bindings/Advanced#schemaUpdate|schemaUpdate]]
+
* [[0.24 Python_bindings/Advanced#schemaUpdate|schemaUpdate]]
* [[Trunk_Python_bindings/Advanced#databaseSearch|databaseSearch]]
+
* [[0.24 Python_bindings/Advanced#databaseSearch|databaseSearch]]
* [[Trunk_Python_bindings/Advanced#SplitInt|SplitInt]]
+
* [[0.24 Python_bindings/Advanced#SplitInt|SplitInt]]
* [[Trunk_Python_bindings/Advanced#CMPVideo|CMPVideo]]
+
* [[0.24 Python_bindings/Advanced#CMPVideo|CMPVideo]]
* [[Trunk_Python_bindings/Advanced#CMPRecord|CMPRecord]]
+
* [[0.24 Python_bindings/Advanced#CMPRecord|CMPRecord]]
* [[Trunk_Python_bindings/Advanced#deadlinesocket|deadlinesocket]]
+
* [[0.24 Python_bindings/Advanced#deadlinesocket|deadlinesocket]]
* [[Trunk_Python_bindings/Advanced#MARKUPLIST|MARKUPLIST]]
+
* [[0.24 Python_bindings/Advanced#MARKUPLIST|MARKUPLIST]]
* [[Trunk_Python_bindings/Advanced#DictData|DictData]]
+
* [[0.24 Python_bindings/Advanced#DictData|DictData]]
* [[Trunk_Python_bindings/Advanced#DBData|DBData]]
+
* [[0.24 Python_bindings/Advanced#DBData|DBData]]
* [[Trunk_Python_bindings/Advanced#DBDataWrite|DBDataWrite]]
+
* [[0.24 Python_bindings/Advanced#DBDataWrite|DBDataWrite]]
* [[Trunk_Python_bindings/Advanced#DBDataRef|DBDataRef]]
+
* [[0.24 Python_bindings/Advanced#DBDataRef|DBDataRef]]
* [[Trunk_Python_bindings/Advanced#DBDataCRef|DBDataCRef]]
+
* [[0.24 Python_bindings/Advanced#DBDataCRef|DBDataCRef]]
* [[Trunk_Python_bindings/Advanced#DBConnection|DBConnection]]
+
* [[0.24 Python_bindings/Advanced#DBConnection|DBConnection]]
* [[Trunk_Python_bindings/Advanced#BEConnection|BEConnection]]
+
* [[0.24 Python_bindings/Advanced#BEConnection|BEConnection]]
* [[Trunk_Python_bindings/Advanced#FEConnection|FEConnection]]
+
* [[0.24 Python_bindings/Advanced#FEConnection|FEConnection]]
* [[Trunk_Python_bindings/Advanced#XMLConnection|XMLConnection]]
+
* [[0.24 Python_bindings/Advanced#XMLConnection|XMLConnection]]
* [[Trunk_Python_bindings/Advanced#DBCache|DBCache]]
+
* [[0.24 Python_bindings/Advanced#DBCache|DBCache]]
* [[Trunk_Python_bindings/Advanced#BECache|BECache]]
+
* [[0.24 Python_bindings/Advanced#BECache|BECache]]
* [[Trunk_Python_bindings/Advanced#BEEvent|BEEvent]]
+
* [[0.24 Python_bindings/Advanced#BEEvent|BEEvent]]
  
[[Category:Trunk_Python_Bindings]]
+
[[Category:0.24_Python_Bindings]]

Latest revision as of 08:43, 9 November 2010

Introduction

The MythTV Python bindings are a set of bindings designed to provide access to the MythTV database and interfaces in an object oriented, 'pythonic' manner. If upgrading from 0.23, please see the upgrade guide.

Requirements

These are the external runtime dependencies required by the python bindings. They are checked at configure time prior to installation, and the bindings will not install if these are not met.

Due to the MySQLdb dependency, Python 2.7 is currently not supported.

Data Model

The data model used in the bindings is based around the DictData class, an ordered dictionary class intended to abstract lists of data provided by the backend and database, and provide them to users as dictionary values or object attributes.

Connection Classes

Data Classes

Backend Data

Database Read-Only

Database Read-Write

External Classes

These classes provide access to external functions.

Other Classes

Logging

The MythLog class intends to provide a logging faculty emulating that used by the MythTV libraries. The class accepts three keyword inputs:

  • module - (optional) string, to be used for identification of log entries (def: 'pythonbindings')
  • lstr - (optional) string, comma separated list of log filters
  • lbit - (optional) bitwise, operator defining which log filters are active

The log filters are a number of keywords defining what sections of logs should be displayed. The stored filter is a bitwise operator, so multiple sections can be active simultaneously. If any bit in the filter matches the section specified in an individual log entry, the log will be passed. If neither 'lstr' nor 'lbit' is defined, the class will default to 'important,general'. The log filter is a global value, and will be shared among all instances of the MythLog class.

The MythLog.log method takes three inputs:

  • level - bitwise operator to test against log filter
  • message - log message to output
  • detail - (optional) additional detail to output

The level accepts multiple values, and if any bit matches with the filter, the message will be formatted and outputted by the log. The formatting exists as:

YYYY-MM-DD HH:mm:ss.ttt <module>: <message>
YYYY-MM-DD HH:mm:ss.ttt <module>: <message> - <detail>

The logger accepts multi-line messages, and will format them as:

YYYY-MM-DD HH:mm:ss.ttt <module>: <message line 1>
                                  <message line 2>
                                  <message line ...>
                                      <detail line 1>
                                      <detail line ...>

Objects of the MythLog class are callable directly, and will run this 'log' method.

classmethods

The MythLog class contains several classmethods for altering the function of all open instances.

  • _setlevel - accepts 'lstr' and 'lbit' inputs, can be used to directly alter the log filter
  • _setfile - accepts a filename, opens a new file path to log to, closing the previous (WARNING: file will be truncated)
  • _setfileobject - accepts a file object to log to, closing the previous

Exceptions

Five exception classes are available for error handling. All errors will have at minimum 'ecode', 'ename', and 'args' defined as attributes. 'args' will be a list with a single string at index 0. The exceptions may provide additional attributes depending on the error code.

MythError

Base exception class, can be used to except all internally thrown errors.

  • GENERIC
  • SYSTEM - retcode, command, stderr
  • SOCKET - sockcode, sockerr

MythDBError

  • DB_RAW - sqlerr
  • DB_CONNECTION - dbconn
  • DB_CREDENTIALS
  • DB_SETTING - setting, hostname
  • DB_SCHEMAMISMATCH - setting, remote, local
  • DB_SCHEMAUPDATE - sqlerr

MythBEError

  • PROTO_CONNECTION - backend, port
  • PROTO_ANNOUNCE - backend, port, response
  • PROTO_MISMATCH - remote, local
  • PROTO_PROGRAMINFO

MythFEError

  • FE_CONNECTION - frontend, port
  • FR_ANNOUNCE - frontend, port

MythFileError

  • FILE_ERROR
  • FILE_FAILED_READ - file
  • FILE_FAILED_WRITE - file, reason

For 'try' statements, MythError is a catch-all class. The exception will provide three attributes:

  • args - tuple containing a single error string
  • ename - string with the name of the error code
  • ecode - numeric error code

Utility

OrdDict

The OrdDict class provides an ordered dictionary implementation. It behaves exactly as a normal dictionary, except that order of values are maintained in the order that they are added. Python 2.7 now includes an ordered dictionary implementation, so this class should be considered obsolete, and due for removal at such time as Python 2.7 or 3.x is make a minimum requirement.

DictInvert

The DictInvert class provides a pair of entangled dictionaries, which have their values and keys swapped. Any new entries added to one is automatically mapped to the other.

UPnP Search

The MSearch class provides a basic UPnP search utility. The search method accepts the following inputs:

  • timeout - float, number of seconds to run the search before being automatically terminated
  • filter - a single string or list/tuple of strings, if given, only results whose URN is listed in the filter will be passed

The search method is a generator, only processing results as requested by the user. As with all iterables, the result is only available once, and must be stored manually if multiple uses are desired. The method returns a dictionary with the following fields:

  • content-length
  • request
  • date
  • usn
  • location
  • cache-control
  • server
  • ext
  • st

The search method can be terminated prematurely by the terminate method.

Canned searches of searchMythBE and searchMythFE will return one instance per host found.

EventLock

This class connects to a backend and will remain locked until it has received an event matching a given compiled regular expression. The 'wait' method will block until the event is received and the object unlocked.

ftopen

The function takes a Myth URI and returns a file object, either from the local file system if found locally, or from a FileTransfer socket connected to the backend.

datetime

Advanced Use