[docs] [issue11260] smtpd-as-a-script feature should be documented and should use argparse

Xavier Morel report at bugs.python.org
Tue Feb 22 09:50:04 CET 2011

Xavier Morel <xavier.morel at masklinn.net> added the comment:

> Do tests currently exist for smtpd run as a script?

I have to confess I didn't think to check.

> If not, our experience with converting compileall to argparse indicates a thorough test suite is needed (and even so we missed some things we hadn't thought to test).

OK, so if there is no test suite currently I should create one, and if there is one I should ensure it's complete? I guess I should use compileall as an example of how to test modules-as-scripts if the former? Overall, smtpd-as-a-script is really pretty simple, it totals 28 lines apart from the argument parsing itself (which is a bit under 60 lines ignoring the help text/pattern and gets a bit under 50 including it post-patch), and as I mentioned the only part which actually needed changing is the arguments parsing, which was very well factored out.

> In other words, if the current code works, is "updating" it a sufficient reason to change it, considering the chances of introducing new bugs?

I'm not sure, but one of the ways I see standard libraries is not just as "ready to use" code, it's also as a repository of how to do things. And to that end, if argparse is now considered the canonical way to parse command-line arguments (which I would expect), there are very few examples of how to do things in the stdlib itself (though there are examples outside of it, due to the life argparse had pre-stdlib).

It also rose to the occasion as I was wondering about the numerous standard library modules-as-scripts which are either undocumented or under-documented: because it had a good command-line documentation and a clean separation between the configuration (options parsing) and the actual execution, but no module documentation (in Doc/) it seemed like a good starting point: if it's not feasible to correctly convert "best cases" (and smtpd is probably one, short of modules using optparse probably) then the whole idea is stillborn: I do not see how it would be possible to fare better on some of the fully undocumented modules using manual options parsing, yet it would have to be expected.


Python tracker <report at bugs.python.org>

More information about the docs mailing list