
Dippy Example: Image Search

--------------------------------------------------------------------------------
quick start
--------------------------------------------------------------------------------

1. open dippy/example/build.py to see what you're about to run

2. in a python shell, run: 
>>> import dippy.example.build as b; reload( b ); b.run( 'clinton' )

3. open clinton.html in a web browser, it should be rendered vertically

4. in dippy/example/build.py, uncommend the horizontal render implementation

5. rerun:
>>> import dippy.example.build as b; reload( b ); b.run( 'clinton' )

6. refresh clinton.html, it should be rendered horizontally

7. browse the code in dippy/example/ to see how the components are structured using Dippy

8. browse the other code in dippy/ to see how Dippy is implemented

--------------------------------------------------------------------------------
example: image search
--------------------------------------------------------------------------------

This example implements an image search web page, by wrapping an http search api
such as Google's json api.

We will decompose the task of mapping from:
  topic -> gallery
into:
  topic -> url -> json_doc -> doc -> images -> gallery 

These components are written using dependency inversion, with the help of Dippy.

For the sake of simplicity, this example avoids error checking, string escaping,
object-oriented programming, and other things you'd find in production quality 
code.

--------------------------------------------------------------------------------
component interfaces
--------------------------------------------------------------------------------

note that we use x__y as the python name of a function mapping x -> y 

json: serializes and deserializes json (implemented with something like cjson)
  json__obj  
  obj__json

api: generates api urls and parses api documents
  topic__url
  doc__images

download: downloads a url (implemented with something like urllib2)
  url__doc
  
render: renders images to html
  images__gallery

search: top level component of our image search app
  topic__gallery (topic__url -> url__doc -> json__obj -> doc__images -> images__gallery)

--------------------------------------------------------------------------------
component implementations
--------------------------------------------------------------------------------

json
  cjson
  simplejson

api
  mock
  google images
  possibilities: yahoo images, flickr, ...

download
  mock
  urllib2
  possibilities: pycurl, multi-threaded downloader, download cluster, ...

gallery
  vertical
  horizontal
  possibilities: various js / flash slideshows, ...

search
  any combination of download + api + gallery


