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

[Xavier Morel]

New submission from Xavier Morel <xavier.morel at masklinn.net>:

argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments.

Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse).

I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation.

smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers).

* The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden)

* The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs

* The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen

* Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different:
  - running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1
  - providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1)

----------
assignee: docs at python
components: Documentation, Library (Lib)
files: smtpd-to-argparse.diff
keywords: patch
messages: 128917
nosy: barry, docs at python, xmorel
priority: normal
severity: normal
status: open
title: smtpd-as-a-script feature should be documented and should use argparse
versions: Python 3.3
Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff

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