  DEVELOPMENT OF IMDbPY
  =====================

A lot of other information useful to IMDbPY developers are available
in the "README.package" file.

Sections in this file:
* STRUCTURE OF THE IMDbPY PACKAGE
* GENERIC DESCRIPTION
* HOW TO EXTEND


  STRUCTURE OF THE IMDbPY PACKAGE
  ===============================

imdb (package)
 |
 +-> _exceptions
 +-> Movie
 +-> Person
 +-> utils
 +-> parser (package)
       |
       +-> http (package)
       |    |
       |    +-> movieParser
       |    +-> personParser
       |    +-> searchMovieParser
       |    +-> searchPersonParser
       |    +-> utils
       |
       +-> local (package)
            |
            +-> movieParser
            +-> personParser
            +-> utils

Description:
imdb (package): contains the IMDb function, the IMDbBase class and imports
                the IMDbError exception class.
_exceptions: defines the exceptions internally used.
Movie: contains the Movie class, used to describe and manage a movie.
Person: contains the Person class, used to describe and manage a person.
utils: miscellaneous utilities used by many IMDbPY modules.
parser (package): a package containing a package for every data access system
                  implemented.
http (package): contains the IMDbHTTPAccessSystem class which is a subclass
                of the imdb.IMDbBase class; it provides the methods used to
                retrieve and manage data from the web server (using,
                in turn, the other modules in the package).
                It defines methods to get a movie and to search for a title.
http.movieParser: parse html strings from the pages on the IMDb web server about
                  a movie; returns dictionaries of {key: value}
http.personParser: parse html strings from the pages on the IMDb web server
                   about a person; returns dictionaries.
http.searchMovieParser: parse an html string, result of a query for a movie
                        title.
http.searchPersonParser: parse an html string, result of a query for a person
                         name.
http.utils: miscellaneous utilities used only by the http package.

The modules under the parser.local package are the same of the
parser.http package (the search functions are placed directly in the
IMDbLocalAccessSystem class); obviously they manage a local installation
of the database.


  GENERIC DESCRIPTION
  ===================

I wanted to stay independent from the source of the data for a given
movie/person, and so the imdb.IMDb function returns an instance of a class
that provides specific methods to access a given data source (web server,
local installation, etc.)

Unfortunately this means that the movieID in the Movie class and the
personID in the Person class are dependent by the data access system
used.  So, when a Movie or Person object is instantiated, the accessSystem
instance variable is set to a string used to identify the used data access
system.


  HOW TO EXTEND
  =============

To introduce a new data access system, you've to write a new package
inside the "parser" package; this new package must provide a subclass
of the imdb.IMDb class which must define at least the following methods:
 _search_movie(title)  - to search for a given title; must return a
                         list of (movieID, {movieData}) tuples.
 _search_person(name)  - to search for a given name; must return a
                         list of (movieID, {personData}) tuples.
 get_movie_*(movieID)  - a set of methods, one for every set of information
                         defined for a Movie object; should return
                         a dictionary with the relative information.
 get_person_*(personID) - a set of methods, one for every set of information
                          defined for a Person object; should return
                          a dictionary with the relative information.
 get_imdbMovieID(movieID) - must convert the given movieID to a string
                            representing the imdbID, as used by the IMDb web
                            server (e.g.: '0094226' for Brian De Palma's
                            "The Untouchables").
 get_imdbPersonID(personID) - must convert the given personID a string
                              representing the imdbID, as used by the IMDb web
                              server (e.g.: '0000154' for "Mel Gibson").
 _normalize_movieID(movieID) - must convert the provided movieID in a
                               format suitable for internal use (e.g.:
                               convert a string to a long int).
 _normalize_personID(personID) - idem.
 _get_real_movieID(movieID) - return the true movieID; useful to handle
                              title aliases.
 _get_real_personID(personID) - idem.

The class should raise the appropriate exceptions, when needed;
IMDbDataAccessError must be raised when you cannot access the resource
you need to retrieve movie info or you're unable to do a query (this is
_not_ the case when a query returns zero matches: in this situation an
empty list must be returned); IMDbParserError should be raised when an
error occurred parsing some data.  IMDbNotAvailable is raised when
the requested information is not available in the running data
access system.

Now you've to modify the imdb.IMDb function so that, when the right
data access system is selected with the "accessSystem" parameter, an
instance of your newly created class is returned.

E.g.: if you want to call your new data access system "mysql" (meaning
that the data are stored in a mysql database), you've to add to the imdb.IMDb
function something like:
  if accessSystem == 'mysql':
      from parser.mysql import IMDbMysqlAccessSystem
      return IMDbMysqlAccessSystem(*arguments, **keywords)

where "parser.mysql" is the package you've created to access the
local installation, and "IMDbMysqlAccessSystem" is the subclass of
imdb.IMDbBase.
Then it's possibile to use the new data access system like:
  from imdb import IMDb
  i = IMDb(accessSystem='mysql')
  results = i.search_movie('the matrix')
  print results

A specific data access system implementation can defines it's own
methods.
As an example, the IMDbHTTPAccessSystem that is in the parser.http package
defines the method set_proxy() to manage the use a web proxy; you
can use it this way:
      from imdb import IMDb
      i = IMDb(accessSystem='http') # the 'accessSystem' argument is not
                              # really needed, since "http" is the default.
      i.set_proxy('http://localhost:8080/')

A list of special methods provided by the imdb.IMDbBase subclass, along
with their description, is always available calling the get_special_methods()
of the IMDb class.
E.g.:
     i = IMDb(accessSystem='http')
     print i.get_special_methods()

will print a dictionary with the format:
  {'method_name': 'method_description', ...}


