Package: pynzb
Introduction------------NZB is an XML-based file format for retrieving posts from NNTP (Usenet)servers.Since NZB is XML-based, it's relatively easy to build one-off parsers to parseNZB files.  This project is an attempt to consolidate those many one-off NZBparsers into one simple interface.This package includes three implementations: one based on expat, anotherbasedon ElementTree, and a final implementation based on lxml.  The order in whichthey were listed is in order of compatibility.  The expat version should work onall versions of Python > 2.0, the lxml one will work on all versions > 2.5, andlxml will only work if you have lxml installed.A Note on Installing lxml-------------------------While lxml is not a requirement, I have had a hard time installing lxml in thepast.  I have found this set of commands to work perfectly::STATIC_DEPS=true easy_install 'lxml>=2.2beta4'STATIC_DEPS=true sudo easy_install 'lxml>=2.2beta4'API Documentation-----------------Accessing the Default Parser============================Simply import nzb_parser from the pynzb package.  It's an instantiated versionof the fastest available parser that your system can support.Other Parser Locations======================``ExpatNZBParser``:Available in the ``pynzb.expat_nzb`` namespace.``ETreeNZBParser``:Available in the ``pynzb.etree_nzb`` namespace.``LXMLNZBParser``:Available in the ``pynzb.lxml_nzb`` namespace.Using the NZB Parser====================If you're using a specific parser, like the ``ETreeNZBParser``, you will firsthave to instantiate it::nzb_parser = ETreeNZBParser()Otherwise, you can just import the default parser for your system::from pynzb import nzb_parserThen, simply call the ``parse`` method, giving it the xml string as the onlyargument::files = nzb_parser.parse('<?xml ... my nzb file here ... </nzb>')This will return a list of ``NZBFiles`` for you to use.NZBFile Objects===============All of the parsers return ``NZBFile`` objects, which are objects with thefollowing properties:``poster``:The name of the user who posted the file to the newsgroup.``date``:A ``datetime.date`` representation of when the server first saw the file.``subject``:The subject used when the user posted the file to the newsgroup.``groups``:A list of strings representing the newsgroups in which this file may befound.``segments``:A list of ``NZBSegment`` objects talking about where to get the contentsof this file.NZBSegment Objects==================Each ``NZBFile`` has a list of ``NZBSegment`` objects, which includeinformationon how to retrieve a part of a file.  Here's what you can find on an``NZBSegment`` object:``number``:The number of the segment in the list of files.``bytes``:The size of the segment, in bytes.``message_id``:The Message-ID of the segment (useful for retrieving the full contents)Example--------In this example, we will grab an Ubuntu NZB and parse the file, printing outsome information about each file and its segments::from pynzb import nzb_parserfrom urllib2 import urlopen# Grab a sample Ubuntu NZBubuntu_nzb = urlopen('http://media.eflorenzano.com/misc/sample-ubuntu-nzb.nzb').read()# Parse the NZB into filesfiles = nzb_parser.parse(ubuntu_nzb)# Print out each file's subject and the first two segment message idsfor nzb_file in files:print nzb_file.subjectfor segment in nzb_file.segments[:2]:print '    ' + segment.message_idif len(nzb_file.segments) > 2:print '    ...'