Python Data Portability library examples
----------------------------------------

To get this running, simply do the following:

1. Run the bootstrap.py file with your python interpreter:
   
   python bootstrap.py

2. Run the generated buildout script:

   bin/buildout 

Now you have example scripts in the bin/ directory:

bin/mf_bsoup   -- runs the microformat suite over my twitter page using Beautiful Soup.
bin/mf_etree   -- runs the microformat suite over my twitter page using ElementTree.
bin/xrds       -- parses an example XRDS file and prints the ouput of the libraries



What's in the pydataportability library for now?
------------------------------------------------

The following packages are available:

pydataportability.microformats.base  

    the base microformats parser package.
    It provides for now two HTML parser implementations, based on ElementTree (faster but needs valid XHTML) or 
    BeautifulSoup (slower but more forgiving regarding HTML). This package relies on plugins to actually find
    and process microformats in HTML pages.

pydataportability.microformats.hcard 
    
    provides a plugin to parse the hCard microformat. It returns VCard objects which you can then use.

pydataportability.microformats.xfn 
    
    provides a plugin to parse the XFN microformat. It returns XFNRelationship objects which you can then use.

pydataportability.xrds

    parses files in XRDS-Simple format. It returns Service objects which in turn contain URI objects for these services.


You need to install the corresponding eggs which are available on the cheeseshop.


How to use the library
----------------------

To use the library you first need to import various packages:

>>> from zope.component import getUtility

This package is needed to retrieve the HTML parser you want. Now you need to import the
plugins you want to use. When imported they will register themselves with the base package:

>>> import pydataportability.microformats.hcard
>>> import pydataportability.microformats.xfn

We also need to import the interface of the HTML Parser:
>>> from pydataportability.microformats.base.interfaces import IHTMLParser

Now we can retrieve a factory for our parser. We can choose right now between "beautifulsoup" and "elementtree".
You can also register your own HTML parser if you want. Documentation for this will be added later.
>>> parser = getUtility(IHTMLParser,name="beautifulsoup")()

Now we can open an URL and retrieve a page. We receive a parser instance:
>>> mf = parser.fromString(data)

And we can let the parser look for microformats:
>>> mf.parse()

Now we can iterate over the found items (xfn or hcard objects):

>>> for name,result in mf.microformats.items():
...    print "**",name,"**"
...    for r in result:
...        print r



For more information look into the example scripts or the source code.



Source Code
-----------


The source code can be found at: 

http://code.google.com/p/pydataportability/source/brows

The important packages are:

https://pydataportability.googlecode.com/svn/pydataportability.microformats.base/trunk
https://pydataportability.googlecode.com/svn/pydataportability.microformats.hcard/trunk
https://pydataportability.googlecode.com/svn/pydataportability.microformats.xfn/trunk
https://pydataportability.googlecode.com/svn/pydataportability.xrds/trunk
https://pydataportability.googlecode.com/svn/pydataportability.examples/trunk

If you want to get the development buildout, check out this:

svn co http://pydataportability.googlecode.com/svn/buildouts/microformats

Then again run bootstrap.py and bin/buildout as described above.


AUTHORS
-------

Christian Scholz, COM.lounge (mrtopf@gmail.com, cs@comlounge.net, http://mrtopf.de)

License
-------

LGPL