pynzbpynzb is a unified API for parsing NZB files, with several concrete implementations includedIntroduction
------------
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 parse
NZB files. This project is an attempt to consolidate those many one-off NZB
parsers into one simple interface.
This package includes three implementations: one based on expat, another
based
on ElementTree, and a final implementation based on lxml. The order in which
they were listed is in order of compatibility. The expat version should work on
all versions of Python > 2.0, the lxml one will work on all versions > 2.5, and
lxml 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 the
past. 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 version
of 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 first
have to instantiate it::
nzb_parser = ETreeNZBParser()
Otherwise, you can just import the default parser for your system::
from pynzb import nzb_parser
Then, simply call the ``parse`` method, giving it the xml string as the only
argument::
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 the
following 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 be
found.
``segments``:
A list of ``NZBSegment`` objects talking about where to get the contents
of this file.
NZBSegment Objects
==================
Each ``NZBFile`` has a list of ``NZBSegment`` objects, which include
information
on 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 out
some information about each file and its segments::
from pynzb import nzb_parser
from urllib2 import urlopen
# Grab a sample Ubuntu NZB
ubuntu_nzb = urlopen('http://media.eflorenzano.com/misc/sample-ubuntu-
nzb.nzb').read()
# Parse the NZB into files
files = nzb_parser.parse(ubuntu_nzb)
# Print out each file's subject and the first two segment message ids
for nzb_file in files:
print nzb_file.subject
for segment in nzb_file.segments[:2]:
print ' ' + segment.message_id
if len(nzb_file.segments) > 2:
print ' ...'Eric Florenzano9304583376bb8a3de3ed15eebe0a75d191b282350.1.0