[rfc] bzrlib.doc.api doctests as txt files

[James Henstridge]

On 5/9/06, Alexander Belchenko <bialix at ukr.net> wrote:
> This subpackage (bzrlib.doc.api) wrote Robert Collins so probably this
> question mostly addressed to him.
>
> I make bzr.exe for win32 with py2exe. All python packages py2exe store
> into one library.zip file and during executing of program this modules
> imported via zipimport. All stuff works. Only txt files inside
> bzrlib/doc/api break normal behaviour (break selftest command).
>
> Now I simply disable this tests when directory
> os.getcwd()/bzrlib/doc/api does not exists. Therefore this tests will
> never be executed on win32 in bzr.exe form. Is this important part of
> test suite? I see in comments that it mostly used as examples of using
> api. So I think it can be omitted in case when we provide bzr.exe with
> bzrlib bundled inside.
>
> If there is important to run this tests even in bzr.exe form then this
> files probably should be converted to usual python source for normal
> importing and bundling into library.zip.

Assuming that the text files are inside the zip file, there is an API
to access them.  Assume that we are in bzrlib/doc/api/__init__.py:

1. if we've been loaded from a zip file, there will be a __loader__
object in the module's globals.

2. We can access the contents of bzrlib/doc/api/branch.txt with:
    data = __loader__.get_data('bzrlib/doc/api/branch.txt')

3. There isn't a documented way of listing a directory, but there is
an undocumented "_files" attribute on the loader object.  The keys of
this dictionary are the paths in the zip file.

So it would be possible to make doctests work with the zip importer.

It might not be worth doing all this for a test case, but might be
worth it if other data gets stored in the bzrlib directory in the
future.

James.