[theora] python bindings update

[Ondrej Certik]

Hi,

here is a webpage for the Python bindings:

http://certik.github.com/python-theora/

Changes since the last time:

* tests added, e.g. there is a script that downloads some theora tests
videos and then I test the python wrappers on them
* every single method has a docstring with a doctested example
* sphinx documentation added, see the link above
* couple minor changes, like better control what arrays go to the encoder

I suggest you browse the theora module docs:

http://certik.github.com/python-theora/module_theora.html

and go over the examples. This should give you an idea what is
possible with the bindings already. There is also a nice index:

http://certik.github.com/python-theora/genindex.html

Btw, all of this was done automatically by the sphinx documentation
tool. Here is for example the source code to the theora module page
(just click "Show Source" in the left bar at the bottom):

http://certik.github.com/python-theora/sources/module_theora.txt

So all the documentation is equivalent to what you get for example in ipython:

$ ipython
In [1]: import theora

In [2]: theora.Theora?<ENTER>
Base Class:       <type 'type'>
String Form:   <type 'theora.Theora'>
Namespace:        Interactive
File:             /home/ondrej/repos/python-theora/theora.so
Docstring:
    Provides a nice high level Python interface to a theora video stream.

    It can read frames as numpy arrays or PIL images.

    Example of usage::

        >>> from theora import Theora, test_files, VIDEO_DIR
        >>> t = Theora(test_files[2])
        >>> print t
        <Ogg logical stream 11f68f2c is Theora 720x576 25.00 fps
video, encoded frame
        content is 720x576 with 0x0 offset, aspect is 16:15>
        >>> t.read_frame()
        True
[...]

and so on. Then you can literally copy & paste any example from the
documentation/docstrings and it will work.

This is just to show that Python allows this kind of interactive
exploration of the api and it makes it easy to play with theora.

I am interested in all feedback.

Another unrelated thing is that I never used the github pages before,
so I wanted to try it and it works just great --- all I had to do was
to create a new branch "gh-pages" in the repository, push it to github
and it shows it as a page. This is really nice, because if you
download the repository, you automatically get the documentation too
and also it doesn't require any setup on my side to push the docs to
the web. Next time I change something, all I have to do is to update
the gh-pages branch on my laptop, and then just push it to github. And
also, if I decided that I don't like github for some reason, it's
pretty easy to setup something similar on my own server, since all the
information is in the git repository itself. Pretty slick.


So I think after I implement audio and then after more testing to get
rid of some basic bugs, I think it will be quite usable. If you'd like
to use it as official python wrappers, I'll be happy to fix/improve
anything you think is needed for that purpose.

Ondrej