Created by: gwideman, Oct 30, 2013 3:26 pm
Revised by: gwideman, Nov 5, 2013 12:35 am (8 revisions)

Issues list for Python-related components and docs


Id
Date
Component
Title
Description
Followup






GWPY1100
2013-10-30
setuptools 1.1.7
find_package() doesn't find Python 3.3-style packages that lack a __init__.py file
In setup.py's
setup(...
packages=find_packages(..)
)
will fail to find packages lack a __init__.py file, as is allowed in Python 3.3. However, packages listed explicitly: packages=['mypkg'] do appear to get installed.
Note: When testing this, before each test be sure to delete all metadata, including that which setup may previously have placed in the original source directory, as it seems that setup may use metadata created on a previous run in order to include files.
bitbucket.org/pypa/setuptools/issue/97/find_package-doesnt-find-33-style-no
GWPY1101
2013-10-30
setuptools docs
Setuptools docs have many problems.
Main doc page: pythonhosted.org/setuptools/index.html
  • Building and Distributing Packages with Setuptools
    • No overview. Setuptools are introduced as an enhancement to Distutils, which is only useful if reader already understands Distutils. (And Distutils docs are outdated).
    • No overview of the setup.py... setup() convention, and the multiple sources of inputs to setup(): Command line, function args, config files, environment variables.
    • No overview of directory structures ("project layout") that setuptools expects to work with (except by inference from the args to setup() )
    • No overview of different distributables, and which tools can produce or consume them.
    • No details on what is actually produced in the distributable, which would help understanding what it is that setuptools want as input, and understanding the scope of what an installer might be able to do (or the scope of what PyPI can do too).
    • setup.py --help and its variants fail to document positional (non-keyword) command-line arguments. (To research, grep setuptools\command\*.py for command_consumes_arguments.)
    • Many instances of "now", "previously", "in the future" etc, but no date on the doc or these individual comments
    • Does not cover Python 3.3 packages. In a number of places says that packages require "__init__.py", implying that setuptools can't be used with Python 3.3 packages.
    • Many parts of the narrative are not clear what phase of package..install they are talking about.
      • Particular problem with "build"
        • Narrative needs to be clear if it's discussing a process on the dev machine, or on the user's machine
        • Not clear what "build" means for pure python projects.
    • There are some tie-ins between setuptools and version control tools, with CVS and Subversion being frequently mentioned. That seems not too useful these days. What about git and Mercurial?
    • Nomenclature issues
    • Distutils/setuptools objects are mentioned but not described: Distribution object; command object

GWPY1102
2013-10-30
setuptools help
setup.py --help and its variants fail to document positional (non-keyword) command-line arguments.
To research, grep setuptools\command\*.py for command_consumes_arguments.

GWPY1103
2013-10-30
PyPA Python Packaging User Guide
Quick Recommendations page:
python-packaging-user-guide .readthedocs.org/en/latest/current.html
The advice given doesn't seem to address the simple case of just getting a small project from one machine to another, without involving an external server (PyPI). Ie: doesn't provide the "on ramp" for users moving from just copying files around to using a distribution tool.