python-xmltv
============

Introduction
------------
python-xmltv is a Python module that provides access to XMLTV data. XMLTV is
an XML format for storing TV listings.

More information on XMLTV can be found at http://membled.com/work/apps/xmltv/


Requirements
------------

python-xmltv requires ElementTree, which can be found at
http://effbot.org/zone/element-index.htm


Installing
----------

Get python-xmltv from http://www.funktronics.ca/python-xmltv/releases/python-xmltv-1.3.tar.gz

After untarring, you can install it with the following command::

    python setup.py install


Usage
-----
Usage of the module is generally straight-forward::

    import xmltv
    from pprint import pprint
    
    # If you need to change the locale:
    # xmltv.locale = 'Latin-1'
    
    # If you need to change the date format used in the XMLTV file:
    # xmltv.date_format = '%Y%m%d%H%M%S %Z'
    
    filename = '/path/to/xmltv/file'
    
    # Print info for XMLTV file (source, etc.)
    pprint(xmltv.read_data(open(filename, 'r')))
    
    # Print channels
    pprint(xmltv.read_channels(open(filename, 'r')))

    # Print programmes
    pprint(xmltv.read_programmes(open(filename, 'r')))

There are currently three functions for reading that should be used:

    **read_data** ``(file_object) -> dict``
	Get the source and other info from an XMLTV file.

        Returns a dictionary of <tv> attributes, eg::
	
	    {'date': u'20030702230041 -0300',
	     'generator-info-name': u'tv_grab_na V3.20030629',
	     'generator-info-url': u'http://sourceforge.net/projects/xmltv',
	     'source-info-name': u'Zap2It',
	     'source-info-url': u'http://www.zap2it.com'}

    **read_channels** ``(file_object) -> list``
	Get all of the channels.
	
	Returns a list of hashes, each representing a channel, eg::
	
	    [{'display-name': [(u'Channel 10 ELTV', u'')],
	      'id': u'C10eltv.zap2it.com'},
	     {'display-name': [(u'Channel 11 CBHT', u'')],
	      'icon': [{'desc': '','src': u'http://tvlistings2.zap2it.com/tms_network_logos/cbc.gif'}],
	      'id': u'C11cbht.zap2it.com'}]
	
    **read_programmes** ``(file_object) -> list``
	Get all of the programmes.
	
	Returns a list of hashes, each representing a programme, eg::
	
	    [{'audio': [{'stereo': [u'stereo']}],
	      'category': [(u'Biz', u''), (u'Fin', u'')],
	      'channel': u'C23robtv.zap2it.com',
	      'start': u'20030702000000 ADT',
	      'stop': u'20030702003000 ADT',
	      'title': [(u'This Week in Business', u'')]},
	     {'audio': [{'stereo': [u'stereo']}],
	      'channel': u'C36wuhf.zap2it.com',
	      'desc': [(u'In an effort to grow up, George proposes marriage to former girlfriend Susan.',
	                u'')],
	      'rating': [{'system': u'VCHIP', 'value': u'PG'}],
	      'start': u'20030702000000 ADT',
	      'stop': u'20030702003000 ADT',
	      'sub-title': [(u'The Engagement', u'')],
	      'subtitles': [{'type': u'teletext'}],
	      'title': [(u'Seinfeld', u'')]}]
	      
There is also a Writer class. It should always write proper XMLTV data. All
strings, except for dictionary keys, should be in Unicode.

It contains the following methods:

    **__init__** ``(fp, encoding="iso-8859-1", date=None, source_info_url=None, source_info_name=None, generator_info_url=None, generator_info_name=None)`` -> ``Writer``
        Returns a Writer object.
	
	Arguments:
	
	    ``fp``
		A File object to write XMLTV data to

            ``encoding``
		The text encoding that will be used. *Defaults to
		``iso-8859-1``*

            ``date``
		The date this data was generated. *Optional*

            ``source_info_url``
		A URL for information about the source of the data. *Optional*

            ``source_info_name``
		A human readable description of ``source_info_url``.
		*Optional*

            ``generator_info_url``
		A URL for information about the program that is generating the
		XMLTV document. *Optional*

            ``generator_info_name``
		A human readable description of ``generator_info_url``.
		*Optional*

    **write_channel** ``(channel)``
	Write a channel dictionary
	
	Here's an example channel dictionary::
	
	    {'display-name': [(u'Channel 11 CBHT', u'en')],
             'icon': [{'src': u'http://tvlistings2.zap2it.com/tms_network_logos/cbc.gif'}],
             'id': u'C11cbht.zap2it.com',
	     'url': u:'http://www.cbc.com'}
	     
    **write_programme** ``(programme)``
	Write a programme dictionary
	
	Here's an example programme dictionary::
	
	    {'audio': [{'stereo': u'stereo'}],
             'category': [(u'Comedy', u'')],
             'channel': u'C36wuhf.zap2it.com',
             'country': [(u'USA', u'')],
             'credits': [{'producer': [u'Larry David'], 'actor': [u'Jerry Seinfeld']}],
             'date': [u'1995'],
             'desc': [(u'In an effort to grow up, George proposes marriage to former girlfriend Susan.',
                       u'')],
             'episode-num': [(u'7 . 1 . 1/1', u'xmltv_ns')],
             'language': [(u'English', u'')],
             'last-chance': [(u'Hah!', u'')],
             'length': [{'units': u'minutes', 'length': 22}],
             'new': [1],
             'orig-language': [(u'English', u'')],
             'premiere': [(u'Not really. Just testing', u'en')],
             'previously-shown': [{'channel': u'C12whdh.zap2it.com',
                                   'start': u'19950921103000 ADT'}],
             'rating': [{'icon': [{'height': u'64',
                                   'src': u'http://some.ratings/PGicon.png',
                                   'width': u'64'}],
                         'system': u'VCHIP',
                         'value': u'PG'}],
             'star-rating': [{'icon': [{'height': u'32',
                                        'src': u'http://some.star/icon.png',
                                        'width': u'32'}],
                              'value': u'4/5'}],
             'start': u'20030702000000 ADT',
             'stop': u'20030702003000 ADT',
             'sub-title': [(u'The Engagement', u'')],
             'subtitles': [{'type': u'teletext', 'language': (u'English', u'')}],
             'title': [(u'Seinfeld', u'')],
             'video': [{'colour': 1, 'aspect': u'4:3', 'present': 1}]}

    **end** ``()``
	Write end tag
	
	Call this before closing a file.

Reporting Bugs
--------------
Please send all bugs, comments, and questions to James Oakley
<jfunk@funktronics.ca>
