[Import-SIG] PEP 395 (Module aliasing) and the namespace PEPs

[Nick Coghlan]

On Thu, Nov 17, 2011 at 10:10 AM, PJ Eby <pje at telecommunity.com> wrote:
> So, I'm wondering a bit about the detailed use cases people have about using
> modules as scripts and vice versa.  Are they writing scripts, then turning
> them into modules?  Trying to run somebody else's modules?  Copying example
> code from somewhere?
> (The part that confuses me is, if you *know* there's a difference between a
> script and a module, then presumably you either know about __name__, OR you
> wouldn't have any reason to run your module as a script.  Conversely, if you
> don't know about __name__, then how would you conceive of making your script
> into a module?  ISTM that in order to even have this problem you have to at
> least be knowledgeable enough to realize there's *some* difference between
> moduleness and scriptness.)
> Anyway, understanding the *details* of this process (of how people end up
> making the sort of errors PEP 395 aims to address) seems important to me for
> pinning down precisely what problem to solve and how.

The module->script process comes from wanting to expose useful command
line functionality from a Python module in a cross-platform way
without any additional packaging effort (as exposing system-native
scripts is a decidedly *non* trivial task, and also doesn't work from
a source checkout).

The genesis was actually the timeit module - "python -m timeit" is now
the easiest way to run short benchmarking snippets.

A variety of other standard library modules also offer useful "-m"
functionality - "-m site" will dump diagnostic info regarding your
path setup, "-m smptd" will run up a local SMTP server, "-m unittest"
and "-m doctest" can be used to run tests, "-m pdb" can be used to
invoke the debugger, "-m pydoc" will run pydoc as usual. (A more
comprehensive list is below, but it's also worth caveating this list
with Raymond's comments on http://bugs.python.org/issue11260)

Third party wise, I've mostly seen "-m" support used for "scripts that
run scripts" - tools like pychecker, coverage and so forth are
naturally Python version specific, and running them via -m rather than
directly automatically deals with those scoping issues.

It's also fairly common for test definition modules to support
execution via "-m" (by invoking unittest.main() from an "if __name__"
guarded suite).

Cheers,
Nick.

====================
Top level stdlib modules with meaningful "if __name__ == '__main__':" blocks:

base64.py - CLI for base64 encoding/decoding
calendar.py - CLI to display text calendars
cgi.py - displays some example CGI output
code.py - code-based interactive interpreter
compileall.py - CLI for bytecode file generation
cProfile.py - profile a script with cProfile
dis.py - CLI for file disassembly
doctest.py - CLI for doctest execution
filecmp.py - CLI to compare directory contents
fileinput.py - line numbered file display
formatter.py - reformats text and prints to stdout
ftplib.py - very basic CLI for FTP
gzip.py - basic CLI for creation of gzip files
imaplib.py - basic IMAP client (localhost only)
imghdr.py - scan a directory looking for valid image headers
mailcap.py - display system mailcap config info
mimetypes.py - CLI for querying mimetypes (but appears broken)
modulefinder.py - dump list of all modules referenced (directly or
indirectly) from a Python file
netrc.py - dump netrc config (I think)
nntplib.py - basic CLI for nntp
pdb.py - debug a script
pickle.py - dumps the content of a pickle file
pickletools.py - prettier dump of pickle file contents
platform.py - display platform info (e.g.
Linux-3.1.1-1.fc16.x86_64-x86_64-with-fedora-16-Verne)
profile.py - profile a script with profile
pstats.py - CLI to browse profile stats
pydoc.py - same as the installed pydoc script
quopri.py - CLI for quoted printable encoding/decoding
runpy.py - Essentially an indirect way to do what -m itself already does
shlex.py - runs the lexer over the specified file
site.py - dumps path config information
smtpd.py - local SMTP server
sndhdr.py - scan a directory looking for valid audio headers
sysconfig.py - dumps system configuration details
tabnanny.py - CLI to scan files
telnetlib.py - very basic telnet CLI
timeit.py - CLI to time snippets of code
tokenize.py - CLI to tokenize files
turtle.py - runs turtle demo (appears to be broken in trunk, though)
uu.py - CLI for UUencode encoding/decoding
webbrowser.py - CLI to launch a web browser
zipfile.py - basic CLI for zipfile creation and inspection

Not sure (no help text, no clear purpose without looking at the code):
aifc.py - dump info about AIFF files?
codecs.py
decimal.py
difflib.py
getopt.py - manual sanity check?
heapq.py
inspect.py
keyword.py - only valid in source checkout
macurl2path.py - manual sanity check?
poplib.py - simple POP3 client?
pprint.py
pyclbr.py - dump classes defined in files?
py_compile.py
random.py - manual sanity check?
smtplib.py
sre_constants.py - broken on Py3k!
symbol.py - only valid in source checkout, broken on Py3k
symtable.py - manual sanity check?
textwrap.py - manual sanity check?
token.py - only valid in source checkout

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