Difference between revisions of "0.24 Python bindings/Upgrade Guide"
(Created page with 'While not so abrupt as the 0.23 release, there have been a number of changes in the Python bindings that may break uses of them. == Alterations == === Deletions === === Internal…') |
m |
||
(7 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
== Alterations == | == Alterations == | ||
=== Deletions === | === Deletions === | ||
+ | Several of the old methods from the 0.22 bindings have been removed. Most have been replaced with new methods, some are no longer necessary. | ||
+ | {| border="1" cellspacing="0" cellpadding="5" style="border-collapse:collapse; border-color:#8eabd0; background:#e7edf5" | ||
+ | |- style="background: lightsteelblue" | ||
+ | ! Old method | ||
+ | ! New method | ||
+ | |- | ||
+ | | MythTV() || renamed to MythBE() | ||
+ | |- | ||
+ | | MythDB.getChannel() || Replaced by Channel() | ||
+ | |- | ||
+ | | MythDB.getGuideData() || Replaced by MythDB.searchGuide() | ||
+ | |- | ||
+ | | MythDB.getSetting || Accessible through MythDB.settings attribute | ||
+ | |- | ||
+ | | MythDB.setSetting || Accessible through MythDB.settings attribute | ||
+ | |- | ||
+ | | MythVideo.pruneMetadata() || Replaced by MythVideo.scanStorageGroups(). | ||
+ | |- | ||
+ | | MythVideo.getTitleId() || Behavior not directly replaced, as there should be no need for direct search for IDs. Use MythVideo.searchVideos() instead. | ||
+ | |- | ||
+ | | MythVideo.getMetadataDictionary() || Accessible through dict(Video()). | ||
+ | |- | ||
+ | | MythVideo.setMetadata() || Replaced by Video.update(). | ||
+ | |- | ||
+ | | MythVideo.getMetadataId() || Behavior not directly replaced, as there should be no need for direct search for IDs. Use MythVideo.searchVideos() instead. | ||
+ | |- | ||
+ | | MythVideo.hasMetadata() || Behavior not directly replaced. Use MythVideo.searchVideos() instead. | ||
+ | |- | ||
+ | | MythVideo.rmMetadata() || Replaced by Video.delete(). | ||
+ | |- | ||
+ | | MythVideo.rtnVideoStorageGroup() || Replaced by MythDB.getStorageGroup(groupname='Videos'). | ||
+ | |- | ||
+ | | MythVideo.getTableFieldNames() || Accessible through MythDB.tablefields attribute. | ||
+ | |- | ||
+ | | MythVideo.setCast() || Replaced by Video.cast.add(). | ||
+ | |- | ||
+ | | MythVideo.setGenres() || Replaced by Video.genres.add(). | ||
+ | |- | ||
+ | | MythVideo.setCountry() || Replaced by Video.country.add(). | ||
+ | |- | ||
+ | | MythVideo.cleanCast() || Replaced by Video.cast.clean() | ||
+ | |- | ||
+ | | MythVideo.cleanGenres() || Replaced by Video.genre.clean() | ||
+ | |- | ||
+ | | MythVideo.cleanCountry() || Replaced by Video.country.clean() | ||
+ | |} | ||
=== Internal Rename === | === Internal Rename === | ||
+ | Internal variables in the DictData family have been prepended with underscores, to prevent any possible name collisions with database field names. This should be transparent externally, but will cause problems if one has written subclasses. | ||
+ | |||
+ | The base connection classes have been renamed to DBConnection, BEConnection, and XMLConnection for the connections, and DBCache and BECache for the caches. The higher level classes (MythBE, MythDB, MythXML, MythVideo) will remain the same. | ||
=== Grabbers === | === Grabbers === | ||
+ | The Grabber class has been split between Grabber, and a more generic System class, for any managed call of external functions. The VideoGrabber class has been updated to support the new XML metadata format used for those grabbers, and the Recorded and Video classes have an importMetadata method that accept the response from the grabber. | ||
+ | |||
+ | === ReOrg === | ||
+ | For 0.24, there has been an internal re-organization to the bindings. Most database classes now return a generator. This is an iterable, but like an iterator, it can only be looped once. If multiple accesses are needed, a result must be run through 'list()'. The advantage is that data is only processed as needed, resulting in faster responses. | ||
+ | |||
+ | Due to dependency issues, the 'to***' methods have been replaced with 'from***' methods. These are now all classmethods, and do not need to be called against an existing object. | ||
== Additions == | == Additions == | ||
=== Thread Safety === | === Thread Safety === | ||
+ | The socket code has been rewritten to be non-blocking. MythBE now accepts a 'timeout' keyword as the default for the connection, as does backendCommand for a one-time override. The Backend and Database connection classes both provide proper locking to be thread safe. An individual cursor from the database connection cannot be considered thread safe. | ||
+ | |||
=== Event Handling === | === Event Handling === | ||
+ | Several classes have been added for interfacing with events being sent by the backend. As a result, BECache (and by proxy MythBE) have slightly different inputs. The 'type' keyword is replaced with a boolean 'noshutdown', to decide whether the connection will be 'Monitor' or 'Playback'. | ||
+ | |||
+ | ==== BEEvent ==== | ||
+ | This class adds event support to the base BECache class. It adds 'systemevents' and 'generalevents' keywords to denote which types it wants to receive. This class provides automatic registering of any handlers listed by the '_listhandlers' method. Any handlers registered using this method should optionally accept an event string. If the event is not given, it is to return a regular expression for matching against event strings. | ||
+ | |||
+ | Eventhandlers can be manually registered using the BEConnection.registerevent(regex, func) method. | ||
+ | |||
+ | ==== BEEventMonitor ==== | ||
+ | This class has a simple catch-all expression, and prints all received events to the log. | ||
+ | |||
+ | ==== MythSystemEvent ==== | ||
+ | This class duplicates the event handling behavior of each frontend, backend, and jobqueue, introduced in changeset {{changeset|23012}}. Database defined actions can be overridden by providing a function of the same name as the event, in lowercase. The 'systemeventhandler' decorator class provides regular expressions and event string processing. Decorated methods are given a dictionary capable of being processed by the SystemEvent class. | ||
+ | |||
+ | ==== SystemEvent ==== | ||
+ | This is a modified System class, intended for processing and execution of system event command strings specified in the database. | ||
+ | |||
=== New Data Classes === | === New Data Classes === | ||
− | === New | + | ==== Music ==== |
+ | MythMusic now has support with classes for Song, Album, Artist, MusicPlaylist, and MusicDirectory. | ||
+ | |||
+ | === New Utilities === | ||
+ | ==== OrdDict ==== | ||
+ | Provides an ordered dictionary class. | ||
+ | |||
+ | ==== DictInvert ==== | ||
+ | Provides a pair of entangled dictionaries, which have their keys and values reversed from each other. | ||
+ | |||
+ | ==== MSearch ==== | ||
+ | Provides a UPnP M-search implementation, to discover compatible devices on the network. Currently used for auto-detection of frontends and backends. | ||
+ | |||
+ | ==== MythMusic ==== | ||
+ | A modified database connection class providing a searchMusic method. | ||
+ | |||
+ | [[Category:0.24_Python_Bindings]] |
Latest revision as of 09:10, 9 November 2010
While not so abrupt as the 0.23 release, there have been a number of changes in the Python bindings that may break uses of them.
Contents
Alterations
Deletions
Several of the old methods from the 0.22 bindings have been removed. Most have been replaced with new methods, some are no longer necessary.
Old method | New method |
---|---|
MythTV() | renamed to MythBE() |
MythDB.getChannel() | Replaced by Channel() |
MythDB.getGuideData() | Replaced by MythDB.searchGuide() |
MythDB.getSetting | Accessible through MythDB.settings attribute |
MythDB.setSetting | Accessible through MythDB.settings attribute |
MythVideo.pruneMetadata() | Replaced by MythVideo.scanStorageGroups(). |
MythVideo.getTitleId() | Behavior not directly replaced, as there should be no need for direct search for IDs. Use MythVideo.searchVideos() instead. |
MythVideo.getMetadataDictionary() | Accessible through dict(Video()). |
MythVideo.setMetadata() | Replaced by Video.update(). |
MythVideo.getMetadataId() | Behavior not directly replaced, as there should be no need for direct search for IDs. Use MythVideo.searchVideos() instead. |
MythVideo.hasMetadata() | Behavior not directly replaced. Use MythVideo.searchVideos() instead. |
MythVideo.rmMetadata() | Replaced by Video.delete(). |
MythVideo.rtnVideoStorageGroup() | Replaced by MythDB.getStorageGroup(groupname='Videos'). |
MythVideo.getTableFieldNames() | Accessible through MythDB.tablefields attribute. |
MythVideo.setCast() | Replaced by Video.cast.add(). |
MythVideo.setGenres() | Replaced by Video.genres.add(). |
MythVideo.setCountry() | Replaced by Video.country.add(). |
MythVideo.cleanCast() | Replaced by Video.cast.clean() |
MythVideo.cleanGenres() | Replaced by Video.genre.clean() |
MythVideo.cleanCountry() | Replaced by Video.country.clean() |
Internal Rename
Internal variables in the DictData family have been prepended with underscores, to prevent any possible name collisions with database field names. This should be transparent externally, but will cause problems if one has written subclasses.
The base connection classes have been renamed to DBConnection, BEConnection, and XMLConnection for the connections, and DBCache and BECache for the caches. The higher level classes (MythBE, MythDB, MythXML, MythVideo) will remain the same.
Grabbers
The Grabber class has been split between Grabber, and a more generic System class, for any managed call of external functions. The VideoGrabber class has been updated to support the new XML metadata format used for those grabbers, and the Recorded and Video classes have an importMetadata method that accept the response from the grabber.
ReOrg
For 0.24, there has been an internal re-organization to the bindings. Most database classes now return a generator. This is an iterable, but like an iterator, it can only be looped once. If multiple accesses are needed, a result must be run through 'list()'. The advantage is that data is only processed as needed, resulting in faster responses.
Due to dependency issues, the 'to***' methods have been replaced with 'from***' methods. These are now all classmethods, and do not need to be called against an existing object.
Additions
Thread Safety
The socket code has been rewritten to be non-blocking. MythBE now accepts a 'timeout' keyword as the default for the connection, as does backendCommand for a one-time override. The Backend and Database connection classes both provide proper locking to be thread safe. An individual cursor from the database connection cannot be considered thread safe.
Event Handling
Several classes have been added for interfacing with events being sent by the backend. As a result, BECache (and by proxy MythBE) have slightly different inputs. The 'type' keyword is replaced with a boolean 'noshutdown', to decide whether the connection will be 'Monitor' or 'Playback'.
BEEvent
This class adds event support to the base BECache class. It adds 'systemevents' and 'generalevents' keywords to denote which types it wants to receive. This class provides automatic registering of any handlers listed by the '_listhandlers' method. Any handlers registered using this method should optionally accept an event string. If the event is not given, it is to return a regular expression for matching against event strings.
Eventhandlers can be manually registered using the BEConnection.registerevent(regex, func) method.
BEEventMonitor
This class has a simple catch-all expression, and prints all received events to the log.
MythSystemEvent
This class duplicates the event handling behavior of each frontend, backend, and jobqueue, introduced in changeset [23012]. Database defined actions can be overridden by providing a function of the same name as the event, in lowercase. The 'systemeventhandler' decorator class provides regular expressions and event string processing. Decorated methods are given a dictionary capable of being processed by the SystemEvent class.
SystemEvent
This is a modified System class, intended for processing and execution of system event command strings specified in the database.
New Data Classes
Music
MythMusic now has support with classes for Song, Album, Artist, MusicPlaylist, and MusicDirectory.
New Utilities
OrdDict
Provides an ordered dictionary class.
DictInvert
Provides a pair of entangled dictionaries, which have their keys and values reversed from each other.
MSearch
Provides a UPnP M-search implementation, to discover compatible devices on the network. Currently used for auto-detection of frontends and backends.
MythMusic
A modified database connection class providing a searchMusic method.