I believe that printing help and usage messages to stdout is a design error.

In stdout i expect to find the output of my program, not help or diagnostic messages.  It is strange to see nothing printed on the screen (where stderr usually goes), and then to find help, usage, or *error* messages in the file where stdout was sent.  (Yes, argparse prints even error messages to stdout by default).

This issue has been discussed before because the implementation did not agree with the documentation: http://bugs.python.org/issue10728
I believe that the conclusion to adjust the documentation to the implementation was a mistake.

P.S. Compare with the direction of the output of `grep -h` or `git -h`.

`grep --help` outputs to stdout. `grep -h` outputs to stderr, because this is error, there is no the `-h` flag. The same for git and most other command line tools.

argparse follows this behavior. There is no bug.

Thanks for the explanation, this makes sense.  I did not notice that argparse outputs to stderr if command line arguments are wrong, i was probably wrong when said it prints error messages to stdout.  I did not notice indeed that there were no `-h` option in git.

However, my grep version 2.5.1-FreeBSD outputs help to stderr even with `--help` option.

Does FreeBSD grep support the `--help` option? Long options is GNU extension, classical UNIX commands supported only short options.

My grep man page says

  --help  Print a brief help message.

but indeed there is no `--help` in usage message.  Maybe this is a bug of the man page.

Thanks for the explanation.