[Distutils] The "dist" command

[Fred L. Drake, Jr.]

Greg Ward writes:
 > I realized last night that I can't honestly release Distutils 0.1 until
 > it can distribute itself, i.e. until there's a "dist" command to create
 > a source distribution.  So I sat down and did a brain dump on what's

 >   - allow an explict manifest, but automatically augment it at runtime
 >     with the source files mentioned in 'packages', 'py_modules', and
 >     'ext_modules' (and any other such things that might come along)

  Another possibility:  If a manifest exists, it must be complete; a
file MANIFEST should be considered an explicit manifest if present at
the root of the package and default behavior is used.  If there is no
manifest file, the default should be something like (using your
syntax, or trying to):

         *  !*~ !*.bak !RCS !CVS

(Presuming, of course, that a directory that matches an exclusion rule 
will not be recursed into.)

 > I'm liking the third way.  Possible gotchas:
 >   - redundant specification: 'packages' includes 'foo' and manifest
 >     includes 'foo/*.py'

  Duplicate inclusions are not a problem as long as the file is only
included once in the resulting file list.

 >   - obvious conflict: 'packages' includes 'foo' and manifest
 >     includes '! foo/*.py' (can't imagine why you'd want this)

  Perhaps a warning should be issued, but there's no real need to
protect against operator error.  The resulting dist would be broken
because it was package improperly.  The warning should be enough to
get the operator to fix the file selection.

 >   - subtle conflict:  'packages' includes 'foo' and manifest
 >     includes '! foo/bar.py' (this could well be desired: eg. exclude
 >     an experimental module from distribution)

  No conflict here unless the manifest says "! foo/__init__.py"; in
that case, use a warning as discussed above.

 > Other things we need to look for in creating a source distribution:
 >   - make sure there's a README

  Warnings would be sufficient if anything at all is needed; things
like README and INSTALL are largely policy rather than requirements at
this level; do you want to have to consider each possible name for
README?  I'd certainly consider calling it README.txt if it were
reasonable to distribute the package to non-Unix systems.  Some people
call it READ.ME, and others README.1st; how many flavors have to be
automatically detected?  Let's shoot for as few special cases as
possible.

 >   - make sure the distribution meta-info is supplied and non-empty
 >     (*must* have name, version, ((author and author_email) or
 >     (maintainer and maintainer_email)), url

  Issue warnings, not errors; these are social engineering issues,
which are better handled by warnings.

 > Frills:
 >   - make sure the setup script is called "setup.py"
 >   - make sure the README refers to "setup.py" (ie. has a line matching
 >     /^\s*python\s+setup\.py/)

  The line:

Run 'python setup.py build install' to install this package.

would be reasonable; perhaps just /python\s+setup.py/?  Hmm, no,
because then wordwrap would cause the match to fail.  Might have to
enable . to match \n in that case (yes, I know there's a flag for that 
in re).

 > A crazy idea that conflicts with having/requiring 'version' in setup.py:

  Version should be explicitly specified somewhere.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives