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

[Xavier Morel]

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

> any of the undocumented command-line interfaces are intentionally undocumented -- they were there for the convenience of the developer for exercising the module as it was being developed and are not part of the official API.

I can understand that, but it's not clear from the source code which is which, and for several of them third-parties have taken up the convenience. Maybe a more formal process of defining which tools are to be considered "official" and which are easter-eggs is needed? In any case, even for "easter eggs" surely a good command-line documentation is a good idea (even if the module documentation side is not added due to the "easter egg" status) isn't it?

> The standard library's primary purpose is to be a library for use in user programs, not to serve as a suite of applications.

Sure, and I don't think most of the module-as-scripts have what it takes to be seen as applications, but many are useful and/or interesting helpers/shortcuts for day to day tasks. http.server and smtpd are good examples of useful modules-as-scripts (http.server being the exact opposite of smtpd in that it has a module-as-script documentation but no documentation whatsoever on the command-line)

> Real apps need more features than we usually offer and they need much faster development cycles than supported by our 18-24 month release cycle. 

I think my suggestion has been misunderstood: I don't want to turn these into real apps, they're fine as basic scripts/helpers to spend 5mn on a task instead of half an hour. I think they deserve better than to be documented and known through StackOverflow or Reddit "what are the -m stdlib features" lists.

> To the extent the standard library serves as a set of examples, that is just side benefit.  There are other ways to make code specifically for examples (we include tons of examples in the documentation; we had a Demos directory; there is the wiki; and there is the ASPN Cookbook site; etc)

Sure, but I think it's still an important driver of how things "are done" in that they're *concrete* examples, not abstract (of course the Cookbook is generally concrete as well). I'm not discounting the importance or quality of the rest of the documentation at all, or at least that was not my intention.

> All that being said, there are some exceptions and it make may sense to document the interface in some where we really do want a command-line app.  I'll look at any patches you want to submit, but try to not go wild turning the library into a suite of applications.  For the most part, that is not what the standard library is about.

As I said, my only intention here is be to document (and argparsify/formalize) what is already there. I considered doing more (e.g. for the specific case of smtpd-as-a-script making ports optional even when hosts are specified, that kind of things) but decided against this distraction, I really just want to make existing module-as-script features simpler to discover and use.

That said, do you have guidelines of which areas this idea would be most interestingly/efficiently applied? Maybe a list of modules-as-scripts you know are used regularly and could benefit from some improvements in their interface or documentation?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11260>
_______________________________________