-----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-----