Difference between revisions of "0.24 Python bindings/Upgrade Guide"

From MythTV Official Wiki
Jump to: navigation, search
(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 Functions ===
+
==== 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.

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.