[Mailman-Developers] Intern

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On May 2, 2008, at 10:59 AM, Ian Eiloart wrote:

> I have an intern coming to work for a couple of months in the  
> summer. Neither of us will be python experts, but part of the point  
> is to learn, right?

Absolutely!

> I'd like him to work on some aspects of Mailman 3.
>
> I plan to get LMTP working to my taste, by (a) rejecting messages  
> for non-existent lists at RCTP time, and (b) rejecting messages from  
> unwanted sender addresses at RCPT time. I Think (a) will be easy to  
> achieve, and (b) only slightly more challenging.

This sounds great.  With (b) there could be multiple list-specific  
policies, so we should make this pluggable.

> So, I'm after ideas for what to do next. I'm vaguely thinking about  
> (c) integration (which will probably begin from working up a  
> specification for exactly what that means), and possibly (d) user  
> interface design for end users and list admins.
>
> Any suggestions for (c) and (d) or alternative areas that need some  
> focus would be useful.

By user interface design do you mean the web u/i?  None of that really  
works in MM3 right now.  Some of the other work happening in the REST  
interface may allow us to separate the web u/i too.

> Also, can you give me pointers to a good place to learn about  
> doctest, please?
>
> Finally, is there any overview documentation for developers new to  
> the Mailman architecture?

Actually these two subjects go hand-in-hand, although there should be  
better overview documentation.

I'm a big fan of separate file doctests (as opposed to docstring  
doctests which I'm not a fan of at all).  The important thing to  
remember is that doctests are documentation first and tests second.   
Or another way of saying it is that doctests are testable documentation.

This is important because you really want to take care to write the  
narrative of a doctest in a clear and concise way.  I'm experimenting  
with this idea that all tests can be done using doctest, with two  
different audiences in mind.  First is the developer (or user) who  
wants to understand a piece of the system, and the second is maybe a  
maintainer who wants to write comprehensive unit tests with total  
coverage.  I don't know if I can achieve "all tests are doctests", but  
I'm trying.

Although it's a bit centered on docstring doctests (which I don't  
like), the Python doctest module has some good background: http://www.python.org/doc/current/lib/module-doctest.html

 From there, search the Mailman 3 tree for 'doc/' subdirectories.    
All .txt files in those directories are doctests.  There's a little  
bit of harness hooking in mailman/tests/test_documentation.py,  
including the doctest flags that I think are the most useful.  A good  
(well, recent ;) example of a doctest that I like is mailman/doc/ 
chains.txt.

I think it's better to have fewer magical globs in the doctest harness  
and do most of the work, including imports in the doctest.  It's just  
a better way to explain how a particular subsystem works or how you  
would use it.

Use ellipsis liberally but judiciously to improve readability.  Always  
be as explicit as possible in showing return values.  E.g. it's better  
to have something like this:

     >>> chain.name
     'reject'

than this:

     >>> chain.name == 'reject'
     True

because when the latter fails, it's more difficult to figure the  
problem out.  The one common exception is in printing the value None  
because None doesn't show up in the interactive prompt.  E.g. instead of

     >>> chain.foobar = None
     >>> chain.foobar
     >>> chain.baz = 7

do this:

     >>> chain.foobar = None
     >>> print chain.foobar
     None
     >>> chain.baz = 7

I'm beginning to think that its better to print strings than return  
them because ascii strs and unicodes print with the same value, but  
have different reprs, and the u-prefixes are annoying.

Does any of that help?  You should definitely look at the Mailman 3  
code and I'll be happy to answer any more questions you might have.

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (Darwin)

iEYEARECAAYFAkggojkACgkQ2YZpQepbvXHOSACgnUcbW7CMi9mvLXfWgVAxzimv
BhEAnj439jpogZTMm+h25uzq7pDE5HWq
=evuZ
-----END PGP SIGNATURE-----