Difference between revisions of "0.24 Python bindings/Connection Handlers"

Latest revision as of 17:28, 17 March 2011

Database Connections

shared

All database connection objects share these common utilities.

tablefields

MythDB.tablefields is populated with an object providing information of database table fields. Tables can be selected as an attribute or item, and return a subclass with further information. The subclass can be converted into a list of field names, or information about each field can be accessed.

>>> db = MythDB()
>>> db.tablefields.settings
[u'value', u'data', u'hostname']
>>> db.tablefields.settings.value
{'default': u'', 'null': u'NO', 'type': u'varchar(128)', 'key': u'MUL', 'extra': u''}
>>> db.tablefields.settings.value.null
u'NO'

settings

MythDB.settings is populated with an object providing access to settings table data. Data is accessed through two levels, first the hostname, and then value. The second level supports a '.getall()' method that returns all settings set for that host. Global settings can be accessed through the 'NULL' hostname.

>>> db = MythDB()
>>> db.settings.NULL.DBSchemaVer
u'1262'
>>> db.settings.NULL.getall()
<itertools.izip object at 0x804e4ac20>

getStorageGroup

Inputs	Outputs	Description
groupname=None hostname=None	StorageGroup iterable	Returns an iterable of all storagegroup folders matching the optional filter settings.

Example:

>>> db = MythDB()
>>> db.getStorageGroup(groupname='Videos').next()
<StorageGroup 'myth://Videos@mythbe/mnt/mythtv/videos/' at 0x804e7d560>

cursor

Inputs	Outputs	Description
log=None	LoggedCursor object	Returns a cursor, with an optional log object.

Example:

db = MythDB()
with db as cursor:
    cursor.execute("""select ...""")

log = MythLog('custom log')
with db.cursor(log) as cursor:
    cursor.execute("""insert ...""")

MythDB

searchRecorded

Inputs

Outputs

Description

**kwargs

Recorded iterable

Returns an iterable of Recorded objects, matching the given search filters. Accepts the following keywords:

title
autoexpire
watched
closecaptioned
generic
hostname
category

subtitle
commflagged
storagegroup
partnumber
cast
transcoded
duplicate

chanid
stars
category_type
parttotal
livetv
hdtv
subtitled

starttime
recgroup
airdate
seriesid
basename
manualid

progstart
playgroup
stereo
showtype
syndicatedepisodenumber
programid

Example:

>>> db.searchRecorded(title='Chuck')
>>> db.searchRecorded(category='Documentary', hdtv=True)

searchOldRecorded

Inputs

Outputs

Description

**kwargs

OldRecorded iterable

Returns an iterable of OldRecorded objects, matching the given search filters. Accepts the following keywords:

title
category
generic

subtitle
seriesid
recstatus

chanid
programid

starttime
station

endtime
duplicate

searchJobs

Inputs

Outputs

Description

**kwargs

Job iterable

Returns an iterable of Job objects, matching the given search filters. Accepts the following keywords:

chanid
title

starttime
subtitle

type
flags

status
olderthan

hostname
newerthan

searchGuide

Inputs

Outputs

Description

**kwargs

Guide iterable

Returns an iterable of Guide objects, matching the given search filters. Accepts the following keywords:

chanid
category
subtitled
seriesid
syndicatedepisodenumber

starttime
airdate
hdtv
originalairdate

endtime
stars
closecaptioned
showtime

title
previouslyshown
partnumber
programid

subtitle
stereo
parttotal
generic

searchRecord

Inputs

Outputs

Description

**kwargs

Record iterable

Returns an iterable of recording rules, matching the given search filters. Accepts the following keywords:

type
enddate
recgroup

chanid
title
station

starttime
subtitle
seriesid

startdate
category
programid

endtime
profile
playgroup

searchInternetContent

Inputs

Outputs

Description

**kwargs

InternetContentArticles iterable

Returns an iterable of internet content, matching the given search filters. Accepts the following keywords:

feedtitle
url
width
ondate
country

title
type
height
olderthan
description

subtitle
author
language
newerthan

season
rating
podcast
longerthan

episode
player
downloadable
shorterthan

getFrontends

Inputs	Outputs	Description
n/a	active Frontend iterable	Tests all frontends listed in the database, and returns connection objects for all those that respond properly.

getFrontend

Inputs	Outputs	Description
host	Frontend object	Returns a Frontend object, pulling the connection port from the database.

MythVideo

scanStorageGroups

Inputs	Outputs	Description
deleteold=True	newvids oldvids	Scans through all storage groups on all accessible hosts, and returns a pair of lists: new content to be added, and old content to be deleted. If `deleteold` is True, the old content has already been deleted, and is just returned for information.

searchRecorded

Inputs

Outputs

Description

**kwargs

Video iterable

Returns an iterable of Video objects, matching the given search filters. Accepts the following keywords:

title
directory
category

subtitle
year
insertedbefore

season
cast
insertedafter

episode
genre

host
country

MythMusic

searchMusic

Inputs

Outputs

Description

**kwargs

Music iterable

Returns an iterable of Music objects, matching the given search filters. Accepts the following keywords:

name
year
bitrate

track
genre

disc_number
rating

artist
format

album
sample_rate

MythProto Connections

MythBE

backendCommand

Inputs	Outputs	Description
command	backend response	This method is low level access to the backend socket. It can be used to send and receive raw strings with the backend. The command and response length is automatically processed and does not have to be provided in the string.

getRecording

Inputs	Outputs	Description
chanid starttime	Program object	Returns information for a single recording, or None if no match is found. chanid can be a string or integer, starttime can be any format supported by the datetime class.

deleteRecording

Inputs	Outputs	Description
Program object force=False	retcode	Deletes a single recording on the backend, optionally forcing the deletion of database information if the cannot be found. Returns -1 on success, or -2 on failure.

forgetRecording

Inputs	Outputs	Description
Program object force=False	n/a	Marks an existing recording as available for re-recording.

deleteFile

Inputs	Outputs	Description
file storagegroup	retcode	Manually delete a single file on the backend. file is a path relative to the root of the storage group.

getHash

Inputs	Outputs	Description
file storagegroup	file hash	Calculate the hash value for a managed file. file is a path relative to the root of the storage group.

reschedule

Inputs	Outputs	Description
recordid=-1 wait=False	n/a	Issues a scheduler run, optionally limiting it to a single rule. Optionally wait for the scheduler run to complete before returning.

fileExists

Inputs	Outputs	Description
file sgroup='Default'	absolute path	Searches for a file on the backend, returning the full path, or None if not found.

download

Inputs	Outputs	Description
url	file object	Issues a download on the backend to a temporary path, and provides a file object to access it. File will be deleted automatically when the object is closed.

downloadTo

Inputs	Outputs	Description
url storagegroup file path openfile=False	file object	Issues a download on the backend to the defined storagegroup and relative path. Optionally provides a file object to the in-progress download.

allocateEventLock

Inputs	Outputs	Description
compiled regex	mutex object	Creates a new mutex which will remain locked until the specified event has been received.

getPendingRecordings

Inputs	Outputs	Description
n/a	Program list	Returns a list of programs scheduled to be recorded.

getScheduledRecordings

Inputs	Outputs	Description
n/a	Program list	Returns a list of programs scheduled to be recorded.

getUpcomingRecordings

Inputs	Outputs	Description
n/a	Program list	Returns a list of programs scheduled to be recorded, filtered for only those that will be recorded.

getConflictedRecordings

Inputs	Outputs	Description
n/a	Program list	Returns a list of programs scheduled to be recorded, filtered for only those with scheduling conflicts.

getRecorderList

Inputs	Outputs	Description
n/a	list of integers	Returns a list of defined card IDs.

getFreeRecorderList

Inputs	Outputs	Description
n/a	list of integers	Returns a list of defined card IDs.

lockTuner

Inputs	Outputs	Description
int=None	card id video node audio node VBI node	Attempts to lock the specified tuner, or automatically chooses one if none specified. Returns the information about the locked tuner, -1 if no tuners are available, or -2 if the optionally requested tuner is already locked. Note: All locked tuners are automatically unlocked prior to closing the connection to the backend.

freeTuner

Inputs	Outputs	Description
int=None	n/a	Free all tuners currently locked by this connection, or one specific tuner. This is automatically run when the connection is closed.

getCurrentRecording

Inputs	Outputs	Description
recorder	Program object	Returns the program currently being recorded by the specified recorder.

isRecording

Inputs	Outputs	Description
recorder	boolean	Returns whether the recorder is actively being used.

isActiveBackend

Inputs	Outputs	Description
hostname	boolean	Returns whether the hostname is connected as a backend.

getRecordings

Inputs	Outputs	Description
n/a	Program list	Returns a list of existing recordings.

getExpiring

Inputs	Outputs	Description
n/a	Program list	Returns a list of existing recordings nearing expiration.

getCheckfile

Inputs	Outputs	Description
Program object	absolute path	Returns the path to the recording on the backend.

getFreeSpace

Inputs	Outputs	Description
all=False	FreeSpace object	Returns information about the recording directories on the local or all backends.

getFreeSpaceSummary

Inputs	Outputs	Description
n/a	total space used space	Returns information about disk usage (in KB).

getLoad

Inputs	Outputs	Description
n/a	1,5,15 averages	Returns the load averages.

getUptime

Inputs	Outputs	Description
n/a	uptime	Returns uptime, in seconds.

walkSG

Inputs	Outputs	Description
n/a	n/a	None

getSGList

Inputs	Outputs	Description
n/a	n/a	None

getSGFile

Inputs	Outputs	Description
n/a	n/a	None

getLastGuideData

Inputs	Outputs	Description
n/a	datetime	Pulls data of last guide data available in the database.

BEEventMonitor

This class is intended for development use only. Its purpose is to connect to the backend, listen for any events, and print them in raw form to the terminal.

MythSystemEvent

Other Connections

MythXML

fromUPNP

Inputs

Outputs

Description

pin=0

credentials dict

This method is used to retrieve the database connection information from the backend. It is generally only used for UPnP auto-detection of the backend, and accepts a PIN. Database may contain:

DBUserName
DBName

DBPort
SecurityPin

DBPassword

getServDesc

Inputs	Outputs	Description
n/a	generator of tuples	Returns a generator of all available commands and inputs. Each item will be in the form (command, {in:(inputs), out:(outputs)})

getHosts

Inputs	Outputs	Description
n/a	hostname list	List of all unique hostnames found in the settings table in the database.

getKeys

Inputs	Outputs	Description
n/a	key list	List of all unique settings keys found in the settings table in the database.

getSetting

Inputs	Outputs	Description
key hostname=None default=None	setting or default	Returns defined setting, or default if setting does not exist.

getProgramGuide

Inputs	Outputs	Description
starttime endtime startchan numchan=None	Guide iterable	Returns an iterable of Guide objects spanning the time and channel range given. Response is limited to 1000 items.

getProgramDetails

Inputs	Outputs	Description
chanid starttime	Program object	Returns a Program object for a single recording.

getChannelIcon

Inputs	Outputs	Description
chanid	image binary	None

getRecorded

Inputs	Outputs	Description
descending=True	Program iterable	Returns a generator that iterates through all recorded programs.

getExpiring

Inputs	Outputs	Description
n/a	Program iterable	Returns a generator that iterates through all recorded programs in order of expiration.

getInternetSource

Inputs	Outputs	Description
n/a	InternetSource iterable	Returns a generator that iterates through all internet video grabbers available over the xml interface.

getPreviewImage

Inputs	Outputs	Description
chanid starttime width=None height=None secsin=None	InternetSource iterable	Polls the preview generator for a preview image.

Frontend

jump

Frontend.jump is populated with an object intended for use sending jumppoints to the frontend. The '.list()' and '.dict()' methods return the available jumppoints, and jumps can be sent by accessing a jumppoint as an attribute or item. Returns True on successful jump.

>>> fe = Frontend.fromUPNP().next()
>>> fe.sendQuery('location')
'mainmenu'
>>> fe.jump.mythvideo
True
>>> fe.sendQuery('location')
'mythvideo'
>>> fe.jump['playbackrecordings']
True
>>> fe.sendQuery('location')
'playbackbox'

key

Frontend.key is populated with an object intended for use sending keypresses to the frontend. The '.list()' method returns a list of special keys allowed, in addition to any alphanumeric keys. Keypresses can be sent as an attribute or item, and accept both literal strings and ordinal scancodes. Returns True on success.

>>> fe = Frontend.fromUPNP().next()
>>> fe.key
['#', '$', '%', '&', '(', ')', ..... ,'tab', 'underscore', 'up', '|']
>>> fe.key.escape
True
>>> fe.key['enter']
True
>>> fe.key[68]
True

getQuery

Inputs	Outputs	Description
n/a	n/a	Returns a list of queries in the form (query string, description).

sendQuery

Inputs	Outputs	Description
n/a	n/a	Sends a query to the backend, returning the unprocessed response.

getPlay

Inputs	Outputs	Description
n/a	n/a	Returns a list of playback commands in the form (command, description).

sendPlay

Inputs	Outputs	Description
n/a	n/a	Sends a command to the backend, returning success or failure.

play

Inputs	Outputs	Description
n/a	n/a	Plays the given media on the frontend. Accepts media of types Recorded, Video, or Program.

getLoad

Inputs	Outputs	Description
n/a	1,5,15 load avg	None

getUptime

Inputs	Outputs	Description
n/a	timedelta	None

getTime

Inputs	Outputs	Description
n/a	datetime	None

getMemory

Inputs	Outputs	Description
n/a	memory usage	Returns memory usage in the form (totalmem, freemem, totalswap, freeswap) in MB.

@@ Line 1: / Line 1: @@
+{{TOC limit|3}}
 == Database Connections ==
-=== MythDB ===
+=== shared ===
+All database connection objects share these common utilities.
 ==== tablefields ====
 MythDB.tablefields is populated with an object providing information of database table fields.  Tables can be selected as an attribute or item, and return a subclass with further information.  The subclass can be converted into a list of field names, or information about each field can be accessed.
@@ Line 21: / Line 23: @@
 <itertools.izip object at 0x804e4ac20>
 </pre>
-==== getStorageGroup ====
+{|
-;inputs:
+|{{FunctionDoc|level=h4
-: groupname=None <string>
+|name=getStorageGroup
-: hostname=None <string>
+|inputs=groupname=None<br>hostname=None
-;outputs:
+|outputs=[[Trunk_Python_bindings/Data_Handlers#StorageGroup|StorageGroup]] iterable
-: StorageGroup generator
+|description=Returns an iterable of all storagegroup folders matching the optional filter settings.
-;description
+|example=<pre>
-: The two optional arguments can be used to filter the available storage groups.
-<pre>
 >>> db = MythDB()
 >>> db.getStorageGroup(groupname='Videos').next()
 <StorageGroup 'myth://Videos@mythbe/mnt/mythtv/videos/' at 0x804e7d560>
-</pre>
+</pre>}}
+|-
+|{{FunctionDoc|level=h4
+|name=cursor
+|inputs=log=None
+|outputs=LoggedCursor object
+|description=Returns a cursor, with an optional log object.
+|example=<pre>
+db = MythDB()
+with db as cursor:
+    cursor.execute("""select ...""")
-==== cursor ====
+log = MythLog('custom log')
-;inputs:
+with db.cursor(log) as cursor:
-: log=None <MythLog object>
+    cursor.execute("""insert ...""")
-;outputs:
+</pre>}}
-: LoggedCursor object
+|-
-;description
+|}
-: Returns a cursor for direct database access
-==== searchRecorded ====
+=== MythDB ===
-;inputs:
+{|
-: All inputs are optional, and can be mixed and matched.
+|{{FunctionDoc|level=h4
-{| cellpadding="10"
+|name=searchRecorded
-|
+|inputs=**kwargs
-title     <br>autoexpire  <br>watched       <br>closecaptioned <br>generic
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Recorded|Recorded]] iterable
-|
+|description=Returns an iterable of Recorded objects, matching the given search filters. Accepts the following keywords:<br>
-subtitle  <br>commflagged <br>storagegroup  <br>partnumber     <br>cast
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-|
+<td>title     <br>autoexpire  <br>watched       <br>closecaptioned <br>generic                 <br>hostname   <br>category</td>
-chanid    <br>stars       <br>category_type <br>parttotal      <br>livetv
+<td>subtitle  <br>commflagged <br>storagegroup  <br>partnumber     <br>cast                    <br>transcoded <br>duplicate</td>
-|
+<td>chanid    <br>stars       <br>category_type <br>parttotal      <br>livetv                  <br>hdtv       <br>subtitled</td>
-starttime <br>recgroup    <br>airdate       <br>seriesid       <br>basename
+<td>starttime <br>recgroup    <br>airdate       <br>seriesid       <br>basename                <br>manualid   <br>&nbsp;</td>
-|
+<td>progstart <br>playgroup   <br>stereo        <br>showtype       <br>syndicatedepisodenumber <br>programid  <br>&nbsp;</td>
-progstart <br>playgroup   <br>stereo        <br>showtype       <br>syndicatedepisodenumber
+</tr></table>
-|
+|example=<pre>
-category  <br>duplicate   <br>subtitled     <br>programid      <br>&nbsp;
-|
-hostname  <br>transcoded  <br>hdtv          <br>manualid       <br>&nbsp;
-|}
-;outputs:
-: Recorded generator
-;description
-: Returns multiple recordings matching the given data
-<pre>
 >>> db.searchRecorded(title='Chuck')
 >>> db.searchRecorded(category='Documentary', hdtv=True)
-</pre>
+</pre>}}
+|-
-==== searchOldRecorded ====
+|{{FunctionDoc|level=h4
-;inputs:
+|name=searchOldRecorded
-: All inputs are optional, and can be mixed and matched.
+|inputs=**kwargs
-{| cellpadding="10"
+|outputs=[[Trunk_Python_bindings/Data_Handlers#OldRecorded|OldRecorded]] iterable
-|
+|description=Returns an iterable of OldRecorded objects, matching the given search filters. Accepts the following keywords:<br>
-title     <br>category   <br>generic
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-|
+<td>title     <br>category    <br>generic</td>
-subtitle  <br>seriesid   <br>recstatus
+<td>subtitle  <br>seriesid    <br>recstatus</td>
-|
+<td>chanid    <br>programid   <br>&nbsp;</td>
-chanid    <br>programid  <br>&nbsp;
+<td>starttime <br>station     <br>&nbsp;</td>
-|
+<td>endtime   <br>duplicate   <br>&nbsp;</td>
-starttime <br>station    <br>&nbsp;
+</tr></table>}}
-|
+|-
-endtime   <br>duplicate  <br>&nbsp;
+|{{FunctionDoc|level=h4
-|}
+|name=searchJobs
-;outputs:
+|inputs=**kwargs
-: OldRecorded generator
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Job|Job]] iterable
-;description
+|description=Returns an iterable of Job objects, matching the given search filters. Accepts the following keywords:<br>
-: Returns multiple old recordings matching the given data
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
+<td>chanid    <br>title</td>
-==== searchJobs ====
+<td>starttime <br>subtitle</td>
-;inputs:
+<td>type      <br>flags</td>
-: All inputs are optional, and can be mixed and matched.
+<td>status    <br>olderthan</td>
-{| cellpadding="10"
+<td>hostname  <br>newerthan</td>
-|
+</tr></table>}}
-chanid    <br>title
+|-
-|
+|{{FunctionDoc|level=h4
-starttime <br>subtitle
+|name=searchGuide
-|
+|inputs=**kwargs
-type      <br>flags
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Guide|Guide]] iterable
-|
+|description=Returns an iterable of Guide objects, matching the given search filters. Accepts the following keywords:<br>
-status    <br>olderthan
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-|
+<td>chanid    <br>category        <br>subtitled      <br>seriesid        <br>syndicatedepisodenumber</td>
-hostname  <br>newerthan
+<td>starttime <br>airdate         <br>hdtv           <br>originalairdate <br>&nbsp;</td>
-|}
+<td>endtime   <br>stars           <br>closecaptioned <br>showtime        <br>&nbsp;</td>
-;outputs:
+<td>title     <br>previouslyshown <br>partnumber     <br>programid       <br>&nbsp;</td>
-: Job generator
+<td>subtitle  <br>stereo          <br>parttotal      <br>generic         <br>&nbsp;</td>
-;description
+</tr></table>}}
-: Returns multiple job entries matching the given data
+|-
+|{{FunctionDoc|level=h4
-==== searchGuide ====
+|name=searchRecord
-;inputs:
+|inputs=**kwargs
-: All inputs are optional, and can be mixed and matched.
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Record|Record]] iterable
-{| cellpadding="10"
+|description=Returns an iterable of recording rules, matching the given search filters. Accepts the following keywords:<br>
-|
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-chanid    <br>category        <br>subtitled      <br>seriesid        <br>syndicatedepisodenumber
+<td>type      <br>enddate  <br>recgroup</td>
-|
+<td>chanid    <br>title    <br>station</td>
-starttime <br>airdate         <br>hdtv           <br>originalairdate <br>&nbsp;
+<td>starttime <br>subtitle <br>seriesid</td>
-|
+<td>startdate <br>category <br>programid</td>
-endtime   <br>stars           <br>closecaptioned <br>showtype        <br>&nbsp;
+<td>endtime   <br>profile  <br>playgroup</td>
-|
+</tr></table>}}
-title     <br>previouslyshown <br>partnumber     <br>programid       <br>&nbsp;
+|-
-|
+|{{FunctionDoc|level=h4
-subtitle  <br>stereo          <br>parttotal      <br>generic         <br>&nbsp;
+|name=searchInternetContent
-|}
+|inputs=**kwargs
-;outputs:
+|outputs=[[Trunk_Python_bindings/Data_Handlers#InternetContentArticles|InternetContentArticles]] iterable
-: Guide generator
+|description=Returns an iterable of internet content, matching the given search filters. Accepts the following keywords:<br>
-;description
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-: Returns multiple guide programs matching the given data
+<td>feedtitle <br>url     <br>width        <br>ondate      <br>country</td>
+<td>title     <br>type    <br>height       <br>olderthan   <br>description</td>
-==== searchRecord ====
+<td>subtitle  <br>author  <br>language     <br>newerthan   <br>&nbsp;</td>
-;inputs:
+<td>season    <br>rating  <br>podcast      <br>longerthan  <br>&nbsp;</td>
-: All inputs are optional, and can be mixed and matched.
+<td>episode   <br>player  <br>downloadable <br>shorterthan <br>&nbsp;</td>
-{| cellpadding="10"
+</tr></table>}}
-|
+|-
-type      <br>enddate    <br>recgroup
+|{{FunctionDoc|level=h4
-|
+|name=getFrontends
-chanid    <br>title      <br>station
+|outputs=active [[Trunk_Python_bindings/Connection_Handlers#Frontend|Frontend]] iterable
-|
+|description=Tests all frontends listed in the database, and returns connection objects for all those that respond properly.}}
-starttime <br>subtitle   <br>seriesid
+|-
-|
+|{{FunctionDoc|level=h4
-startdate <br>category   <br>programid
+|name=getFrontend
-|
+|inputs=host
-endtime   <br>profile    <br>playgroup
+|outputs=[[Trunk_Python_bindings/Connection_Handlers#Frontend|Frontend]] object
-|}
+|description=Returns a Frontend object, pulling the connection port from the database.}}
-;outputs:
+|-
-: OldRecorded generator
-;description
-: Returns multiple recording rules matching the given data
-==== searchInternetContent ====
-;inputs:
-: All inputs are optional, and can be mixed and matched.
-{| cellpadding="10"
-|
-feedtitle <br>url    <br>width        <br>ondate      <br>country
-|
-title     <br>type   <br>height       <br>olderthan   <br>description
-|
-subtitle  <br>author <br>language     <br>newerthan   <br>&nbsp;
-|
-season    <br>rating <br>podcast      <br>longerthan  <br>&nbsp;
-|
-episode   <br>player <br>downloadable <br>shorterthan <br>&nbsp;
 |}
-;outputs:
-: InternetContentArticles generator
-;description
-: Returns multiple internet video entries matching the given data
-==== getFrontends ====
-;inputs:
-;outputs:
-:generator of active Frontends
-;description
-:this tests all frontends listed in the database, and returns those that respond properly to a connection
-==== getFrontend ====
-;inputs:
-:host <string>
-;outputs:
-:Frontend object
-;description
-:this returns a Frontend object for a single frontend defined in the database
 === MythVideo ===
-{| border=1 cellspacing=0 cellpadding=5
+{|
-| Command
+|{{FunctionDoc|level=h4
-| Inputs
+|name=scanStorageGroups
-| Returns
+|inputs=deleteold=True
-| Description
+|outputs=newvids<br>oldvids
+|description=Scans through all storage groups on all accessible hosts, and returns a pair of lists: new content to be added, and old content to be deleted.  If `deleteold` is True, the old content has already been deleted, and is just returned for information.}}
+|-
+|{{FunctionDoc|level=h4
+|name=searchRecorded
+|inputs=**kwargs
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Video|Video]] iterable
+|description=Returns an iterable of Video objects, matching the given search filters. Accepts the following keywords:<br>
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
+<td>title    <br>directory <br>category</td>
+<td>subtitle <br>year      <br>insertedbefore</td>
+<td>season   <br>cast      <br>insertedafter</td>
+<td>episode  <br>genre     <br>&nbsp;</td>
+<td>host     <br>country   <br>&nbsp;</td>
+</tr></table>}}
 |-
-| getStorageGroup
-|
-|
-|
-|-
-| cursor
-|
-|
-|
-|-
-| scanStorageGroups
-|
-|
-|
-|-
-| searchVideo
-|
-|
-|
-|-
-| getVideo
-|
-|
-|
 |}
 === MythMusic ===
-=== MythVideo ===
+{|
-{| border=1 cellspacing=0 cellpadding=5
+|{{FunctionDoc|level=h4
-| Command
+|name=searchMusic
-| Inputs
+|inputs=**kwargs
-| Returns
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Music|Music]] iterable
-| Description
+|description=Returns an iterable of Music objects, matching the given search filters. Accepts the following keywords:<br>
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
+<td>name        <br>year        <br>bitrate</td>
+<td>track       <br>genre       <br>&nbsp;</td>
+<td>disc_number <br>rating      <br>&nbsp;</td>
+<td>artist      <br>format      <br>&nbsp;</td>
+<td>album       <br>sample_rate <br>&nbsp;</td>
+</tr></table>}}
 |-
-| getStorageGroup
-|
-|
-|
-|-
-| cursor
-|
-|
-|
-|-
-| searchMusic
-|
-|
-|
 |}
 == [[:Category:Myth Protocol|MythProto]] Connections ==
 === MythBE ===
-==== backendCommand ====
+{|
-;inputs
+|{{FunctionDoc|level=h4
-:command <string>
+|name=backendCommand
-;outputs
+|inputs=command
-:response <string>
+|outputs=backend response
-;description
+|description=This method is low level access to the backend socket. It can be used to send and receive raw strings with the backend. The command and response length is automatically processed and does not have to be provided in the string.}}
-:This method sends a low level string to the backend, and returns the response.
+|-
-==== getRecording ====
+|{{FunctionDoc|level=h4
-;inputs
+|name=getRecording
-:chanid <str or int>
+|inputs=chanid<br>starttime
-:starttime <datetime>
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object
-;outputs
+|description=Returns information for a single recording, or None if no match is found. '''chanid''' can be a string or integer, '''starttime''' can be any format supported by the [[Trunk_Python_Bindings#datetime|datetime]] class.}}
-:None -- if recording not found
+|-
-:[[Trunk Python bindings/Data Handlers#Program|Program]] object
+|{{FunctionDoc|level=h4
-;description
+|name=deleteRecording
-:Returns information for a single recording
+|inputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object<br>force=False
-==== deleteRecording ====
+|outputs=retcode
-;inputs
+|description=Deletes a single recording on the backend, optionally forcing the deletion of database information if the cannot be found. Returns '''-1''' on success, or '''-2''' on failure.}}
-:program <Program object>
+|-
-:force=False <boolean>
+|{{FunctionDoc|level=h4
-;description
+|name=forgetRecording
-:Informs the backend to delete the recording using whatever mechanism was selected
+|inputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object<br>force=False
-==== forgetRecording ====
+|description=Marks an existing recording as available for re-recording.}}
-;inputs
+|-
-:program <Program object>
+|{{FunctionDoc|level=h4
-;description
+|name=deleteFile
-:Informs the backend to mark a recording as re-recordable
+|inputs=file<br>storagegroup
-==== deleteFile ====
+|outputs=retcode
-;inputs
+|description=Manually delete a single file on the backend. '''file''' is a path relative to the root of the storage group.}}
-:relative file path <string>
+|-
-:storage group name <string>
+|{{FunctionDoc|level=h4
-;description
+|name=getHash
-:Delete a single managed file on the backend
+|inputs=file<br>storagegroup
-==== getHash ====
+|outputs=file hash
-;inputs
+|description=Calculate the [http://trac.opensubtitles.org/projects/opensubtitles/wiki/HashSourceCodes hash] value for a managed file. '''file''' is a path relative to the root of the storage group.}}
-:relative file path <string>
+|-
-:storage group name <string>
+|{{FunctionDoc|level=h4
-;outputs
+|name=reschedule
-:file hash <string>
+|inputs=recordid=-1<br>wait=False
-;description
+|description=Issues a scheduler run, optionally limiting it to a single rule.  Optionally wait for the scheduler run to complete before returning.}}
-:Calculate the [http://trac.opensubtitles.org/projects/opensubtitles/wiki/HashSourceCodes hash] value for a managed file
+|-
-==== reschedule ====
+|{{FunctionDoc|level=h4
-;inputs
+|name=fileExists
-:recordid=-1 <int>
+|inputs=file<br>sgroup='Default'
-:wait=False <boolean>
+|outputs=absolute path
-;description
+|description=Searches for a file on the backend, returning the full path, or None if not found.}}
-:Issue a scheduler run on all rules, or on one specific rule if other than '-1'. Will optionally wait for the scheduler to finish before returning.
+|-
-==== fileExists ====
+|{{FunctionDoc|level=h4
-| relative path to file<br>sgroup='Default' (optional)
+|name=download
-| None or full path to file
+|inputs=url
-| Searches storage groups on the backend for given file
+|outputs=file object
-==== download ====
+|description=Issues a download on the backend to a temporary path, and provides a file object to access it. File will be deleted automatically when the object is closed.}}
-| url
+|-
-| DownloadFileTransfer object
+|{{FunctionDoc|level=h4
-| Starts a managed download on the backend to the Temp storage group, and returns a file object. The downloaded file will be automatically deleted when the file is closed.
+|name=downloadTo
-==== downloadTo ====
+|inputs=url<br>storagegroup<br>file path<br>openfile=False
-| url<br>storage group<br>relative path to file<br>openfile=False (optional)
+|outputs=file object
-| None or DownloadFileTransfer object (if openfile is True)
+|description=Issues a download on the backend to the defined storagegroup and relative path.  Optionally provides a file object to the in-progress download.}}
-| Starts a managed download on the backend to the specified location. Optionally opens the new file for reading.
+|-
-==== allocateEventLock ====
+|{{FunctionDoc|level=h4
-| regular expression
+|name=allocateEventLock
-| EventLock object
+|inputs=compiled regex
-| Opens a lock object that cannot be acquired until an event matching the regular expression has been received.
+|outputs=mutex object
-==== getPendingRecordings ====
+|description=Creates a new mutex which will remain locked until the specified event has been received.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getPendingRecordings
-:Returns a list of programs scheduled to be recorded
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getScheduledRecordings ====
+|description=Returns a list of programs scheduled to be recorded.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getScheduledRecordings
-:Returns a list of programs scheduled to be recorded
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getUpcomingRecordings ====
+|description=Returns a list of programs scheduled to be recorded.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getUpcomingRecordings
-:Returns a list of programs scheduled to be recorded, filtered for only those that will be recorded
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getConflictedRecordings ====
+|description=Returns a list of programs scheduled to be recorded, filtered for only those that will be recorded.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getConflictedRecordings
-:Returns a list of programs scheduled to be recorded, filtered for only those with scheduling conflicts
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getRecorderList ====
+|description=Returns a list of programs scheduled to be recorded, filtered for only those with scheduling conflicts.}}
-;outputs
+|-
-:list of integers
+|{{FunctionDoc|level=h4
-;description
+|name=getRecorderList
-:Returns a list of defined card IDs
+|outputs=list of integers
-==== getFreeRecorderList ====
+|description=Returns a list of defined card IDs.}}
-;outputs
+|-
-:list of integers
+|{{FunctionDoc|level=h4
-;description
+|name=getFreeRecorderList
-:Returns a list of available card IDs
+|outputs=list of integers
-==== lockTuner ====
+|description=Returns a list of defined card IDs.}}
-;inputs
+|-
-:id=None <int>
+|{{FunctionDoc|level=h4
-;outputs
+|name=lockTuner
-:(ID <int>, video node <string>, audio node <string>, VBI node <string>)
+|inputs=int=None
-:error value <int>
+|outputs=card id<br>video node<br>audio node<br>VBI node
-;description
+|description=Attempts to lock the specified tuner, or automatically chooses one if none specified.  Returns the information about the locked tuner, -1 if no tuners are available, or -2 if the optionally requested tuner is already locked.  Note: All locked tuners are automatically unlocked prior to closing the connection to the backend.}}
-:Returns the information about the locked tuner, -1 if no tuners are available, or -2 if the optionally requested tuner is already locked.
+|-
-==== freeTuner ====
+|{{FunctionDoc|level=h4
-;inputs
+|name=freeTuner
-:id=None <int>
+|inputs=int=None
-;description
+|description=Free all tuners currently locked by this connection, or one specific tuner.  This is automatically run when the connection is closed.}}
-:Free all tuners currently locked by this connection, or one specific tuner.  This is automatically run when the connection is closed.
+|-
-==== getCurrentRecording ====
+|{{FunctionDoc|level=h4
-;inputs
+|name=getCurrentRecording
-:recorder <int>
+|inputs=recorder
-;outputs
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object
-:Program object
+|description=Returns the program currently being recorded by the specified recorder.}}
-;description
+|-
-:Returns the program currently being recorded by the given ID.
+|{{FunctionDoc|level=h4
-==== isRecording ====
+|name=isRecording
-;inputs
+|inputs=recorder
-:recorder <int>
+|outputs=boolean
-;outputs
+|description=Returns whether the recorder is actively being used.}}
-:isrecording <boolean>
+|-
-;description
+|{{FunctionDoc|level=h4
-:Returns True or False whether the recorder is actively being used.
+|name=isActiveBackend
-==== isActiveBackend ====
+|inputs=hostname
-;inputs
+|outputs=boolean
-:hostname <string>
+|description=Returns whether the hostname is connected as a backend.}}
-;outputs
+|-
-:isactive <boolean>
+|{{FunctionDoc|level=h4
-;description
+|name=getRecordings
-:Returns True or False whether the provided host is connected as a backend.
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getRecordings ====
+|description=Returns a list of existing recordings.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getExpiring
-:Returns a list of existing recordings.
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] list
-==== getExpiring ====
+|description=Returns a list of existing recordings nearing expiration.}}
-;outputs
+|-
-:list of Program objects
+|{{FunctionDoc|level=h4
-;description
+|name=getCheckfile
-:Returns a list of existing recordings nearing expiration.
+|inputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object
-==== getCheckfile ====
+|outputs=absolute path
-;inputs
+|description=Returns the path to the recording on the backend.}}
-:program <Program object>
+|-
-;outputs
+|{{FunctionDoc|level=h4
-:absolute path <string>
+|name=getFreeSpace
-:error code <int>
+|inputs=all=False
-;description
+|outputs=[[Trunk_Python_bindings/Data_Handlers#FreeSpace|FreeSpace]] object
-:Returns the path to the recording on the backend.
+|description=Returns information about the recording directories on the local or all backends.}}
-==== getFreeSpace ====
+|-
-;inputs
+|{{FunctionDoc|level=h4
-:all=False <boolean>
+|name=getFreeSpaceSummary
-;outputs
+|outputs=total space<br>used space
-:list of FreeSpace objects
+|description=Returns information about disk usage (in KB).}}
-;description
+|-
-:Returns information about the recording directories on the local or all backends.
+|{{FunctionDoc|level=h4
-==== getFreeSpaceSummary ====
+|name=getLoad
-;outputs
+|outputs=1,5,15 averages
-:(total space, used space) <int KB>
+|description=Returns the load averages.}}
-;description
+|-
-:Returns information about disk usage.
+|{{FunctionDoc|level=h4
-==== getLoad ====
+|name=getUptime
-;outputs
+|outputs=uptime
-:(1, 5, 15) <int>
+|description=Returns uptime, in seconds.}}
-==== getUptime ====
+|-
-;outputs
+|{{FunctionDoc|level=h4
-:uptime <int secs>
+|name=walkSG}}
-==== walkSG ====
+|-
+|{{FunctionDoc|level=h4
+|name=getSGList }}
+|-
+|{{FunctionDoc|level=h4
+|name=getSGFile }}
+|-
+|{{FunctionDoc|level=h4
+|name=getLastGuideData
+|outputs=datetime
+|description=Pulls data of last guide data available in the database.
+}}
+|-
+|}
+=== BEEventMonitor ===
+This class is intended for development use only.  Its purpose is to connect to the backend, listen for any events, and print them in raw form to the terminal.
-==== getSGList ====
-==== getSGFile ====
-==== getLastGuideData ====
-;outputs
-:date of last guide data <datetime>
-=== BEEventMonitor ===
 === MythSystemEvent ===
 == Other Connections ==
 === MythXML ===
-{| border=1 cellspacing=0 cellpadding=5
+{|
-| Command
+|{{FunctionDoc|level=h4
-| Inputs
+|name=fromUPNP
-| Returns
+|inputs=pin=0
-| Description
+|outputs=credentials dict
-|-
+|description=This method is used to retrieve the database connection information from the backend.  It is generally only used for UPnP auto-detection of the backend, and accepts a PIN. Database may contain:<br>
-| _queryObject
+<table border="0" style="background-color:transparent; padding-left: 2em;"><tr>
-|
+<td>DBUserName  <br>DBName</td>
-|
+<td>DBPort      <br>SecurityPin</td>
-|
+<td>DBPassword  <br>&nbsp;</td>
-|-
+</tr></table>}}
-| _query
+|-
-|
+|{{FunctionDoc|level=h4
-|
+|name=getServDesc
-|
+|outputs=generator of tuples
-|-
+|description=Returns a generator of all available commands and inputs. Each item will be in the form (command, {in:(inputs), out:(outputs)})}}
-| _queryTree
+|-
-|
+|{{FunctionDoc|level=h4
-|
+|name=getHosts
-|
+|outputs=hostname list
-|-
+|description=List of all unique hostnames found in the settings table in the database.}}
-| getConnectionInfo
+|-
-|
+|{{FunctionDoc|level=h4
-|
+|name=getKeys
-|
+|outputs=key list
-|-
+|description=List of all unique settings keys found in the settings table in the database.}}
-| getServDesc
+|-
-|
+|{{FunctionDoc|level=h4
-|
+|name=getSetting
-|
+|inputs=key<br>hostname=None<br>default=None
-|-
+|outputs=setting or default
-| getHosts
+|description=Returns defined setting, or '''default''' if setting does not exist.}}
-|
+|-
-|
+|{{FunctionDoc|level=h4
-|
+|name=getProgramGuide
-|-
+|inputs=starttime<br>endtime<br>startchan<br>numchan=None
-| getKeys
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Guide|Guide]] iterable
-|
+|description=Returns an iterable of Guide objects spanning the time and channel range given. Response is limited to 1000 items.}}
-|
+|-
-|
+|{{FunctionDoc|level=h4
-|-
+|name=getProgramDetails
-| getSetting
+|inputs=chanid<br>starttime
-|
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] object
-|
+|description=Returns a Program object for a single recording.}}
-|
+|-
-|-
+|{{FunctionDoc|level=h4
-| getProgramGuide
+|name=getChannelIcon
-|
+|inputs=chanid
-|
+|outputs=image binary}}
-|
+|-
-|-
+|{{FunctionDoc|level=h4
-| getProgramDetails
+|name=getRecorded
-|
+|inputs=descending=True
-|
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] iterable
-|
+|description=Returns a generator that iterates through all recorded programs.}}
 |-
-| getChannelIcon
+|{{FunctionDoc|level=h4
-|
+|name=getExpiring
-|
+|outputs=[[Trunk_Python_bindings/Data_Handlers#Program|Program]] iterable
-|
+|description=Returns a generator that iterates through all recorded programs in order of expiration.}}
 |-
-| getRecorded
+|{{FunctionDoc|level=h4
-|
+|name=getInternetSource
-|
+|outputs=InternetSource iterable
-|
+|description=Returns a generator that iterates through all internet video grabbers available over the xml interface.}}
 |-
-| getExpiring
+|{{FunctionDoc|level=h4
-|
+|name=getPreviewImage
-|
+|inputs=chanid<br>starttime<br>width=None<br>height=None<br>secsin=None
-|
+|outputs=InternetSource iterable
-|-
+|description=Polls the preview generator for a preview image.}}
-| getInternetSources
-|
-|
-|
-|}
-=== Frontend ===
-{| border=1 cellspacing=0 cellpadding=5
-| Command
-| Inputs
-| Returns
-| Description
 |-
-| getQuery
-|
-| list of 2-tuples, [(location string, description)]
-| returns all available data queries from the backend
-|-
-| sendQuery
-| query (string)
-| response (string)
-| sends a query to the backend, returning the unprocessed result
-|-
-| getPlay
-|
-| list of 2-tuples, [(playback command, description)]
-| returns all available playback commands from the backend
-|-
-| sendPlay
-| command (string)
-| boolean
-| sends a command to the backend, returning success or failure
-|-
-| play
-| media (any object with _playOnFe method)
-| boolean
-| plays the given media object on the frontend, currently works with Recorded, Program, or Video
-|-
-| getLoad
-|
-| tuple
-| returns the 1/5/15 load averages
-|-
-| getUptime
-|
-| timedelta
-| returns the system uptime
-|-
-| getTime
-|
-| datetime
-| returns the current system time
-|-
-| getMemory
-|
-| dict
-| returns a dictionary of memory and swap usage in megabytes
 |}
+=== Frontend ===
 ==== jump ====
 Frontend.jump is populated with an object intended for use sending jumppoints to the frontend. The '.list()' and '.dict()' methods return the available jumppoints, and jumps can be sent by accessing a jumppoint as an attribute or item. Returns True on successful jump.
@@ Line 585: / Line 481: @@
 </pre>
-[[Category:Trunk_Python_Bindings]]
+{|
+|{{FunctionDoc|level=h4
+|name=getQuery
+|output=list of queries
+|description=Returns a list of queries in the form (query string, description).}}
+|-
+|{{FunctionDoc|level=h4
+|name=sendQuery
+|input=query
+|output=response
+|description=Sends a query to the backend, returning the unprocessed response.}}
+|-
+|{{FunctionDoc|level=h4
+|name=getPlay
+|output=list of play commands
+|description=Returns a list of playback commands in the form (command, description).}}
+|-
+|{{FunctionDoc|level=h4
+|name=sendPlay
+|input=play command
+|output=response
+|description=Sends a command to the backend, returning success or failure.}}
+|-
+|{{FunctionDoc|level=h4
+|name=play
+|input=media
+|description=Plays the given media on the frontend. Accepts media of types Recorded, Video, or Program.}}
+|-
+|{{FunctionDoc|level=h4
+|name=getLoad
+|outputs=1,5,15 load avg}}
+|-
+|{{FunctionDoc|level=h4
+|name=getUptime
+|outputs=timedelta}}
+|-
+|{{FunctionDoc|level=h4
+|name=getTime
+|outputs=datetime}}
+|-
+|{{FunctionDoc|level=h4
+|name=getMemory
+|outputs=memory usage
+|description=Returns memory usage in the form (totalmem, freemem, totalswap, freeswap) in MB.}}
+|-
+|}
+[[Category:0.24_Python_Bindings]]

Difference between revisions of "0.24 Python bindings/Connection Handlers"

Latest revision as of 17:28, 17 March 2011

Contents

Database Connections

shared

tablefields

settings

getStorageGroup

cursor

MythDB

searchRecorded

searchOldRecorded

searchJobs

searchGuide

searchRecord

searchInternetContent

getFrontends

getFrontend

MythVideo

scanStorageGroups

searchRecorded

MythMusic

searchMusic

MythProto Connections

MythBE

backendCommand

getRecording

deleteRecording

forgetRecording

deleteFile

getHash

reschedule

fileExists

download

downloadTo

allocateEventLock

getPendingRecordings

getScheduledRecordings

getUpcomingRecordings

getConflictedRecordings

getRecorderList

getFreeRecorderList

lockTuner

freeTuner

getCurrentRecording

isRecording

isActiveBackend

getRecordings

getExpiring

getCheckfile

getFreeSpace

getFreeSpaceSummary

getLoad

getUptime

walkSG

getSGList

getSGFile

getLastGuideData

BEEventMonitor

MythSystemEvent

Other Connections

MythXML

fromUPNP

getServDesc

getHosts

getKeys

getSetting

getProgramGuide

getProgramDetails

getChannelIcon

getRecorded

getExpiring

getInternetSource

getPreviewImage

Frontend

jump

key

getQuery

sendQuery

getPlay