[Python-ideas] Make Difflib example callable as module __main__

[Nick Coghlan]

On Thu, Feb 23, 2012 at 8:24 AM, Masklinn <masklinn at masklinn.net> wrote:
> Last time this popped up, Raymond Hettinger noted undocumented
> command-line interfaces to stdlib modules are mostly intentional:
> http://mail.python.org/pipermail/docs/2011-February/003171.html

In my view, the most important points in Raymond's email are the first
and the last:

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

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

What I'm envisioning is a dedicated section along the lines of

X. Command Line Functionality in the Standard Library
X.1 Supported Command Line Interfaces
This section would list modules that provide a command line interface
as detailed in the module documentation. A brief description would be
given here, along with a link to the relevant section of the module
docs. It would mainly consist of Python specific utilities for dumping
diagnostic information about the interpreter's own state or analysing
Python programs. Any CLIs in this section should also have associated
unittests in their regression test suites.

Interpreter Diagnostics
- site
- platform
- locale

Execution and Analysis of Python Code
- runpy
- unittest
- doctest
- pydoc
- timeit
- dis
- tokenize
- pdb
- profile
- pstats
- modulefinder

X.2 Unsupported Command Line Interfaces

This section would list modules that offer command line functionality
that is *not* designed to be production quality, but rather exists
primarily as an interactive testing tool for sanity checking when
working on the modules themselves. The only documentation of the
functionality would be the brief descriptions here and the module's
own interactive help (if any). It should be made clear that these
interfaces are *not* covered by the regression test suite and they may
break without warning.

All the simple cross-platform file processing, networking and protocol
handling utilities would be listed here.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia