[python] documentation & TODO list

[python] documentation & TODO list

[Patrick Totzke]

Hi!

This is mainly directed towards Sebastian, but a broader audience can't hurt.

These are the things I noticed when going through the code today:
1) in filenames.py,  __str__ of Filenames: should the return value be
   '\n'.join(self._files)? alternatively, define __iter__ to make this object
   behave as iterator.
2) in message.py:  tags_to_maildir_flags and maildir_flags_to_tags never return a
   :class:`STATUS` as advertised.
3) unicode stuff alredy patched..

I would like to see up-to-date API docs online, even if only the
version string changed.
Sebastian suggested using readthedocs.org for building and hosting APIdocs.
I tested this recently for alot and it looks quite promising.
A simple http get and their build-host checks out the new sources from git and builds
them. This could be easily integrated into notmuch the release process.
Comments on this?

Lastly, does anyone have an opinion on how to share a TODO list/issue tracker
for the bindings? I'm OK with github, we could move all this to the list
and use David's nmbug..

Cheers,
/Patrick

Re: [python] documentation & TODO list

[Sebastian Spaeth]

[-- Attachment #1: Type: text/plain, Size: 2047 bytes --]

On Mon, 05 Dec 2011 22:36:06 +0000, Patrick Totzke wrote:
> These are the things I noticed when going through the code today:
> 1) in filenames.py,  __str__ of Filenames: should the return value be
>    '\n'.join(self._files)? alternatively, define __iter__ to make this object
>    behave as iterator.

To be honest, I don't remember why the code looks the way it looks, but
it certainly is not right like this. Defining __iter__ sounds like a
correct thing to me, but it could be that there was some reason why I
don't have it...
Feel free to implement a working __iter__ and provide a patch :-).

> 2) in message.py:  tags_to_maildir_flags and maildir_flags_to_tags never return a
>    :class:`STATUS` as advertised.

But it has been doing that for, ...., 1 minute :-)
[master ecf8da3] python: Return a STATUS value in tags_to_flags and flags_to_tags

(thanks)

> I would like to see up-to-date API docs online, even if only the
> version string changed.
> Sebastian suggested using readthedocs.org for building and hosting APIdocs.

I currently manually upload a generated API doc to the
packages.python.org website. I kind of like that address because it
sounds official ;-), but it is manual work. I am currently not looking
into expending the efforts I have to do on python notmuch. So setting

> I tested this recently for alot and it looks quite promising.
> A simple http get and their build-host checks out the new sources from git and builds
> them. This could be easily integrated into notmuch the release process.
> Comments on this?

I think that it would be cool to have that automatically been done on
notmuchmail.org. But given that it takes some work to set that up and
readthedocs.org is already there, I am all for using that for now.
 
> Lastly, does anyone have an opinion on how to share a TODO list/issue tracker
> for the bindings? I'm OK with github, we could move all this to the list
> and use David's nmbug..

Ohh, there is already notmuch::python in nmbug :-)

Sebastian

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]