On Jun 07, 2012, at 09:31 AM, Jessy Kate Schingler wrote:
>should the docs be updated perhaps? something either under "getting started
>with GNU Maiman" or even a specific page on "interacting with mailman
>through the python interpreter"? i am happy to add something or contribute
>to that; i think it would certainly facilitate others working with the
>software if that bit was a bit more clear.
Hi Jessy. Yes, I definitely think the docs should be updated, but perhaps not
the page you were reading.
What I've always thought is that overview, architectural, and other useful
higher level documentation should go in src/mailman/docs. Still using the
reST format, but they needn't necessarily be doctests. So I think an overview
page about "interacting with Mailman through the Python interpreter" would
make a great page for this directory, and if you want to do a branch/merge
proposal on that, I would gladly review it.
>in general, what is that the recommended way to script one's own
>interactions with mailman as part of a larger python program? would it be
>through mailman.client "official bindings"? i see there are a number of
>imports in bin/mailman and subsequently in
>src/mailman/commands/cli_withlist.py (which i gather is an alias for
>"shell"). should those be a sufficient set of imports and initializations?
Well, kind of the point is that there are multiple ways of doing it, depending
on what you're trying to do.
One of the principles I've tried to hold to (successfully or not ;) is that
the edges of the system, e.g. the shell scripts and the REST API, should have
very little logic outside of managing that edge. So for example, the cli_*.py
modules should do little more than parse command line options, massage data
into the right format, and then call into the core API, by using the
zope.interfaces. By organizing things this way, a Python program could
conceivably add the proper directory to its sys.path and just 'import mailman'
and various submodules to do exactly the same operations.
This wasn't the case with Mailman 2, because the CGIs, cli scripts, etc. had
way too much logic in them, so to reproduce their functionality on other
boundaries was just too difficult. I think that's a big reason why people
wrote shell scripts to use the MM2 cli rather than bin/withlist scripts or
importing the Mailman namespace.
So, I would say that if you're interacting with MM3 across process boundaries,
e.g. Django on one machine with the core on another, the REST API is the best
way to go. If you're interacting with MM3 on the same machine, within
process, then 'import mailman' could be a good way to go (but of course the
REST API still works), or you could use withlist scripts, or just script the
(Note that mailman.client, while official, isn't strictly necessary, since
the REST API can be used from anything that speaks HTTP.)
>in this particular case, i am building a django app so it seems i can rely
>on postorious and mailman.client, but that wouldn't necessarily be the case
>in general, and my curiosity is piqued about how the scaffolding process
>and imports work so i can do things The Right Way.
I hope the above explains things, if not just ask! Note that if you go the
'import mailman' route, you will need to initialize the system. A good model
for how that's done is src/mailman/bin/mailman.py which is what implements the
'bin/mailman' uber-command. Other than doing fancy things to get --help
looking decent, it's almost ridiculously simple.