root/bbox/README

BBox, a feed collector with optional spatial index
--------------------------------------------------

BBox is an RSS / Atom / RDF feed aggregator. 

Please see the file INSTALL for instructions on setting up a BBox.
It details the software dependencies, mainly the Redland RDF tookit;
http://librdf.org/ , optionally PostGIS for a spatial index 
(which will be replaced with a non-dependent, standalone one in future.)

Setting PYTHONPATH
------------------

These modules must be locatable by Python. 
Set PYTHONPATH to wherever your main 'bbox' directory lives.

    #> export PYTHONPATH=~/consumotronic/bbox
    
From within a script, set this by stating

    import sys
    sys.path.append('/home/jo/consumotronic/bbox')
    
Running BBox
------------

A new BBox must be *bootstrapped* with an RDF model.
The file 'store/boot.rdf' contains a map of RDF namespaces 
to aliases for them.

Either edit bbox/config.py (instructions are in the INSTALL file)
or pass in the name of BBox's data store via the command line:

Without config options set:
    #> python store/boot.py /path/to/directory/and/filename
    OR
    #> python store/boot.py filename
    
With config options set:
    #> python store/boot.py 
    

Using a BBox in application code
--------------------------------
    
    from bbox import BBox

    bbox = BBox() # loads options from bbox/config.py
    bbox = BBox(db='box2') # uses this filename as storage instead
    bbox = BBox(spatial='bboxdb') # add optional spatial index
    
    m = rdfobj.Model('box2',db=1)
    bbox = BBox(model=m) # uses this model instead of making its own
 
Please see 'pydoc bbox' for interface documentation, or read
the section 'The BBox Console', below, and ask it 'help(bbox)'

Please see 'pydoc rdfobj' or ask the console for 'help(rdfobj)'
for details on querying and manipulating BBox's data store.


Feeds that BBox will read
-------------------------

BBox uses Mark Pilgrim's feedparser - http://feedparser.org/
This will eat all flavours of RSS, Atom, etc. To put a feed through
feedparser, 

    bbox.subscribe('http://example.org/index.rss',format='rss')

Bbox also uses a generic RDF parser, raptor from Redland - http://librdf.org/ 
To put a file through raptor:

    bbox.subscribe('http://example.org/index.rdf',format='rdf')

   
The BBox Console
----------------

The console is the quickest way to get started with BBox.

    #> python bbox/console.py filename
        
This is a custom Python console with BBox, rdfobj and the set of 
RDF namespace aliases loaded into it.

Sample session:

 [jo@vishnu bbox]$ python bbox/console.py testing
 BBox console (the BBox 'testing' is loaded as 'b')
        b.subscriptions()
        b.subscribe('http://example.org/test.rss',format='rss')
        b.read_subscriptions

 For more help, try help(bbox)

 >>> b.subscribe('http://frot.org/devlog/index.rss',format='rss')
 >>> b.subscribe('http://www.evnt.org/zool/changes.rss',format='rss')
 >>> b.read_subscriptions()
 >>> subs = b.subscriptions()
 >>> for s in subs: print s.fbox_channel      
 ... 
 http://frot.org/devlog/index.rss
 http://frot.org/bin/ghug/tag/nodel

 >>> for s in subs: print s.fbox_last_etag
 ... 
 "1070424-e066-8a7dfd80"
 None
 >>> for s in subs: print s.fbox_last_modified
 ... 
 Tue, 21 Jun 2005 19:34:30 GMT
 None

    
BBox as simple RDF/RSS parser
-----------------------------

You can use bbox in applications without having to use its subscription
management / HTTP header support, just as a simple frontend to an RDF
data store.

    objects = bbox.read_rss('http://example.org/index.rss')

    objects = bbox.read_rdf('http://example.org/index.rdf')

    for o in objects:
        print o.dc_title
        # or whatever 

Both the read_rdf and read_rss methods return a list of rdfobj.Objects
These are python objects that keep their properties in the Redland 
store, and can be address with a pythonic syntax. Short example
    
    >>> person = bbox.model.create(foaf.Person)
    >>> print foaf.name
    http://xmlns.com/foaf/0.1/name
    >>> person[foaf.name] = 'Jo Walsh'