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

[Raymond Hettinger]

Raymond Hettinger <rhettinger at users.sourceforge.net> added the comment:

Xavier, I think these efforts are misguided in several ways:

* Many 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.
Most are not production quality and would have been done
much differently if that had been the intent.

* The standard library's primary purpose is to be a library
for use in user programs, not to serve as a suite of applications.
We do have a few applications such as pydoc that assist
development, but that is not what we want to do for most
modules.  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. 

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

* David Murray is correct is pointing-out that converting
to argparse risks changing the semantics and possibly
breaking someone's existing uses of the current interface.

* Though argparse is the shiny new kid on the block and
it should be used for new code, there is no imperative
to go change all existing command-line scripts.  We haven't
even done that same exercise for the new string formatting.

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

----------
assignee: docs at python -> rhettinger
nosy: +rhettinger
priority: normal -> low

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