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

[Dan Colish]

On 2/22/12 4:27 PM, Nick Coghlan wrote:
> 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.
This makes perfect sense. If they are going to be documented then they
need to work well. Just going over a few of the ones listed on the
reddit list, I ran into a number of issues with their behavior. Dis was
one example of a very useful module with a cli interface that could use
some improvement.

>
> 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.
That sounds like a good guide to getting started. I like the idea of
only supporting modules which help with python development. I am also
wondering if libraries which are not going to be supported should have
their cli removed? I've come around to see difflib is probably not that
critical for that since we're all using hg these days.

Finally, I tried a number of searches in the bug tracker to see if a
ticket for something like this existed and I found nothing. Nick had
mentioned that a ticket might already exist?


--Dan