0.23 Python bindings

From MythTV Official Wiki
Revision as of 08:30, 11 February 2010 by Wagnerrp (Talk | contribs)

Jump to: navigation, search

The Python bindings received a rewrite in the 0.23 development cycle.

All objects which may use the database for any purpose will have a 'db' keyword input, providing it an existing database connection to use. This allows one to specify the database to use at the beginning of the application, and have it carried through out all subsequent calls. The input will accept any object or subclass of type 'MythDBConn'.


Data Objects



StorageGroup(id=None, db=None, raw=None)

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

Job(id=None, chanid=None, starttime=None, db=None, raw=None)

Channel(chanid=None, db=None, raw=None)

Video(id=None, db=None, raw=None)

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

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

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

Connection Objects

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

This is the database connection class. It accepts connection settings through the 'args' input as a tuple of tuples, or through several keywords. The usable keywords are 'DBHostName', 'DBName', 'DBUserName', 'DBPassword', 'DBPort', and 'SecurityPin'.

>>> db1 = MythDB(args=(('DBHostname','mybackend'),
>>> db2 = MythDB(DBHostname='mybackend',  DBName='mythconverg',
            DBUserName='mythtv',     DBPassword='mythtv')
>>> db3 = MythDB(db=db2)

If the connection settings are not given by the user, they are searched for in '~/.mythtv/config.xml'. If not found there, the object will attempt to find a backend on the network over UPnP, using 0000 if 'SecurityPin' has not been defined.


This is a pseudo-variable with access to the settings table. It accepts two values, the hostname (or 'NULL') and the setting name, and can take them as keys or attributes.

>>> db.settings.NULL.DBSchemaVer
>>> db.settings['mybackend']['BackendServerPort']
>>> db.settings.mybackend.BackendServerPort = 6553


This is another pseudo-variable providing access to the database field names.

>>> db.tablefields.jobqueue
[u'id', u'chanid', u'starttime', u'inserttime', u'type', u'cmds', u'flags', u'status', u'statustime', u'hostname', u'args', u'comment', u'schedruntime']
>>> db.tablefields['storagegroup']
[u'id', u'groupname', u'hostname', u'dirname']


This returns a cursor for manual database access. Queries are automatically logged, and an initialized logging object can be specified.

getStorageGroup(groupname=None, hostname=None)

Return a tuple of StorageGroup objects, optionally filtering by groupname and hostname.

>>> db.getStorageGroup(groupname='Videos')
(<StorageGroup 'myth://Videos@mybackend/mnt/mythtv/store/media/video/' at 0x8031eff90,)


Attempt to connect to all frontends listed in the database, and return a tuple of Frontend objects to all successfully connected to.


Attempt to connect to a single frontend, using the port defined in the database for the given hostname.


Return a tuple of Channel objects.

getRecorded(title=None, subtitle=None, chanid=None, starttime=None, progstart=None)

Return a single Recorded object, or None, matching the specified search parameters.


Return a tuple of Recorded objects, matching the specified search parameters. Accepts the following keywords: title, subtitle, chanid, starttime, progstart, category, hostname, autoexpire, commflagged, stars, recgroup, playgroup, duplicate, transcoded, watched, storagegroup, airdate, stereo, subtitled, hdtv, closecaptioned, partnumber, parttotal, seriesid, showtype, syndicatedepisodenumber, programid, manualid, generic, cast, livetv.

>>> db.searchRecorded(cast='Kiefer Sutherland')
(<Recorded '24','2010-01-18 20:00:00' at 0x803922850>, <Recorded '24','2010-01-25 21:00:00' at 0x803924310>)

>>> db.searchRecorded(title='24', subtitle='Day 8: 6:00PM - 8:00PM') (<Recorded '24','2010-01-18 20:00:00' at 0x80391ff50>,)


Return a tuple of OldRecorded objects, matching the specified search parameters. Accepts the following keywords: title, subtitle, chanid, starttime, endtime, category, seriesid, programid, station, duplicate, generic.


Return a tuple of Job objects, matching the specified search parameters. Accepts the following keywords: chanid, starttime, type, status, hostname, title, subtitle, flags, olderthan, newerthan.


Return a tuple of Guide objects, matching the specified search parameters. Accepts the following keywords: chanid, starttime, endtime, title, subtitle, category, airdate, stars, previouslyshown, stereo, subtitled, hdtv, closecaptioned, partnumber, parttotal, seriesid, originalairdate, showtype, syndicatedepisodenumber, programid, generic, startbefore, startafter, endbefore, endafter.

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

This is the backend socket connection class. It accepts a 'backend' as a hostname, or IP, otherwise using the master backend. Port number is always pulled from the database. Type can be either 'Monitor' or 'Playback', to determine whether or not the backend is allowed to shut down. This class provides automatic connection sharing between multiple instances, and 'single' tells the class to always create a new connection.











getRecording(chanid, starttime)








walkSG(host, sg, top)

getSGList(host, sg, path, filenamesonly=False)

getSGFile(host, sg, path)


Frontend(host, port)









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

This class behaves similarly to MythDB, and accepts the same input arguments. Additionally, the 'settings', 'tablefields', and 'getStorageGroup()' functions are available.


This function performs a scan of the storage groups directories on each machine with a Videos group listed. It returns a tuple containing two lists of Video objects. The function checks new files against existing hashes, and the two lists are new videos to be added, and old videos to be deleted, respectively. The function will remove old videos from the database automatically by default, and new videos are uninitialized, but populated with 'title', 'subtitle', 'season', 'episode', 'host', and 'hash'.


Return a list of Video objects, matching the specified search parameters. Accepts the following keywords: title, subtitle, season, episode, host, director, year, cast, genre, country, file, exactfile, insertedbefore, insertedafter.


Behaves identically to searchVideos, but returns the first response.

MythXML(backend=None, db=None)



Returns a list of unique hosts found in the settings table.


Returns a list of unique keys found in the settings table.

getSetting(key, hostname=None, default=None)

Returns the requested setting value from the settings table, accepting a default value.

getProgramGuide(starttime, enddime, startchan=None, numchan=None)

Returns a list of Guide objects for the specified time period, taking an optional starting channel and channel range.

getProgramDetails(chanid, starttime)

Returns a Program object for the specified show.


Returns a channel icon.


Returns a list of Program objects for all recorded shows


Returns a list of Program objects for recorded shows nearing expiration.

System Objects

Grabber(path=None, setting=None, db=None)

Basic handler for external data handlers. Accepts either an absolute path to the external executable, or a field in the settings table containing the path.


Permanently appends one or more arguments to the executable path, separated by spaces.


Calls the executable with one or more arguments appended to the existing command, and returns the standard output as a string. Raises an exception if the return code is not equal to one. The return code and standard error can be retrieved through the exception, or through Grabber.returncode and Grabber.stderr.

VideoGrabber(mode, lang='en', db=None)

Modified Grabber class, taking 'TV' and 'Movie' for mode.


Accepts a tuple of tuples containing a show title and matching inetref. Allows overriding the responses returned by the searchTitle function.

searchTitle(title, year=None)

Returns a list of tuples containing title, inetref, and year.

searchEpisode(title, subtitle)

Returns a tuple containing season and episode.

getData(inetref, season=None, episode=None, additional=False)

Returns a tuple containing a data dictionary, lists of cast, genre, and country, and optionally an additional dictionary. The first dictionary is data directly applicable to a Video object. The second contains any additional data provided by the grabber but not used by the videometadata table.

NetVisionGrabber(name, type, db=None)

searchXML(title, page=1)



Accessory Objects

MythLog(module='pythonbindings', lstr=None, lbit=None, db=None, logfile=None)

log(level, message, detail=None)


This class accepts a single error string, or an error code followed by additional inputs defined by the error code. An error string is available in both the 'args' attribute as a single item in a tuple and 'message' attribute as a string. The error code is available in 'ecode', and additional attributes may be available dependent on the error code.

This class is duplicated in 'MythDBError', 'MythBEError', 'MythFEError', and 'MythFileError', for further filtering ability.

Advanced Objects