[mythtv-commits] Ticket #8577: Python Bindings Reorganization

[MythTV]

#8577: Python Bindings Reorganization
-------------------------------+--------------------------------------------
 Reporter:  wagnerrp           |       Owner:  wagnerrp  
     Type:  task               |      Status:  new       
 Priority:  minor              |   Milestone:  0.24      
Component:  Bindings - Python  |     Version:  Trunk Head
 Severity:  medium             |     Mlocked:  0         
-------------------------------+--------------------------------------------
 This tracking ticket is for an internal reorganization of the python
 bindings. The first goal is to split the existing files into smaller, more
 manageable files.
  * static.py        - formerly MythStatic.py, same purpose
  * exceptions.py    - MythError class and subclasses
  * logging.py       - MythLog class
  * msearch.py       - generic UPnP M-Search implementation, split out from
 the database autodetect code
  * utility.py       - decorators, utility classes, modified socket
  * altdict.py       - altered dictionary-like classes
  * connections.py   - base connection classes for database, backend,
 frontend, and xml
  * database.py      - managed database data access, and connection cache
  * system.py        - classes for running external programs and metadata
 grabbers
  * mythproto.py     - backend connection cache, event handler, and file
 transfers
  * dataheap.py      - collection of database access and manipulation
 classes
  * methodheap.py    - collection of methods for use with database,
 backend, frontend, and xml connections

 This reorganization is intended to be largely transparent to the upper
 level user. There are two significant changes that will be visible
 externally.
  1. To facilitate the reorganization and cut down on dependency issues,
 several methods have been rewritten as classmethods. Previous methods such
 as 'Program().getRecorded()' will now be performed as
 'Recorded.fromProgram()'.
  2. Several methods that previously returned lists will now return
 generators. While this means their output will always be an iterable, and
 checks for 'None' are unnecessary, it also means if you want to check
 length, or use the data multiple times, you will need to use 'list()'
 first. Methods providing iterables will now return instantly, as
 processing will be performed as data is requested. Additionally, errors
 may be raised during use of the iterable, rather than only at its
 creation.

 Some other changes that will affect lower level users are as follows:
  1. The use of classmethods instead of overloaded constructors has been
 followed through in a number of other places.
      a. The FEConnection and XMLConnection have .fromUPNP() methods that
 return generators of objects from a UPNP search.
      b. DBData subclasses no longer accept raw input. That is now provided
 by a .fromRaw() method.
      c. Guide and Program no longer have a etree input, with that
 functionality now being in .fromEtree() instead.
      d. getAllEntries() for DBData subclasses is now a classmethod,
 meaning it does not have to be called from an instantiated object.
  2. MythLog no longer accepts a file input, but now offers _setfile and
 _setfileobject classmethods, accepting a file path and opened file object,
 respectively. These will, by default, close the previous log file, unless
 that is 'stdout'. As before, the file is used globally by all instances of
 MythLog.
  3. The DictData class, and all subsequent subclasses, are now based
 directly on 'dict'.  DictData._data no longer exists, and there may be
 other minor changes to behavior when used by subclasses.
  4. The DBDataRef and DBDataCRef classes have been cleaned up and are now
 based directly on 'list'.  Existing markup and cast information for
 Recorded and Video should behave similarly externally, but subclassing the
 two will be different (and hopefully more consistent).
  5. The Exception classes are no longer exact duplicates. The individual
 error codes can only be used against their related exception type. All
 Exceptions can still be caught using the base MythError class.

 These changes have been tested against JAMU and MiroBridge, with only
 minor patching needed, and any other python code in the repository should
 be unaffected.

-- 
Ticket URL: <http://svn.mythtv.org/trac/ticket/8577>
MythTV <http://www.mythtv.org/>
MythTV