Differences between revisions 12 and 14 (spanning 2 versions)
Revision 12 as of 2009-06-04 15:26:44
Size: 7571
Editor: pD9EB7E53
Revision 14 as of 2009-06-29 17:30:03
Size: 7432
Editor: pD9EB75B2
Deletions are marked like this. Additions are marked like this.
Line 112: Line 112:
The existing functionality in distutils should be proposed upstream and ideally merged into standard distutils gradually. The existing functionality in distutils should be proposed upstream as a PEP and ideally merged into standard distutils gradually.
Line 191: Line 191:
   * `./` should grew a new command to list requirements; these can be specified explicitly with the `requires` keyword; if not given, an implicit default is computed from grepping the source code for import statements    * `./` can also specify them explicitly with the `requires` keyword


In this blueprint we propose extending python-distutils-extra by a "do what I mean" mode where it automatically chooses the right destination path and action for various known file types such as Python modules, exectuable scripts, icons, desktop files, etc. The goal is that the typical only has to contain meta information like description, version, and author.

We also discuss Debian packaging generation.

Release Note

TODO when status is "beta available".


Python's native and very popular build systems is "distutils" which comes shipped with Python itself. It is fairly limited, though, and requires the user to learn a lot about build systems. python-distutils-extra adds some functionality for i18n, but there are still some standard use cases missing.

With our goal of supporting the opportunistic programmer and our pre-selection of technologies, a lot of the build system design can be made implicit ("convention over configuration"), which will greatly reduce the amount of learning necessary for installing a project and building a package.

User stories


The current Jockey project needs a very large and redundant, setup.cfg, and, and

With the improved distutils-extras, setup.cfg,, and can be dropped completely, and can be dropped to the metadata:

from import setup

    description='UI for managing third-party and non-free drivers',
    license='GPL v2 or later',
    author='Martin Pitt',


  • Uses standard PyGTK and Python libraries and technologies.
  • Automatically generated Debian package produces single binary only. No library/public package building.


This project is by and large an upstream build system extension. It does not deal in any way with distribution, code hosting, revision control, Launchpad, etc. These need to be handled in a higher level in the stack.


Project structure

  • All directories with are Python packages which are used and shipped.

  • Most files are identified by extension and/or contents, not by location.
  • Use conventions for locations of files where it is ambiguous whether to install them, and where (such as executable scripts).

For a standard project which uses well-known file types and a standard directory layout, should only contain metadata about the project which cannot be inferred from the source code.

Required fields:

  • name
  • version
  • license
  • description
  • author

Optional fields:

  • author_email
  • url (homepage)

sdist already knows which files in the source tree are "source" and which ones merely build products/noise. This can be turned into a reasonable implicit default An existing file supersedes the automatic implicit one.

Debian packaging

  • fully automatically generated from scratch, working, Policy compliant


distutils-extra extensions

Current python-distutils-extra needs to learn about compiling PyKDE .ui files to .py files with pykdeuic4.

The existing functionality in distutils should be proposed upstream as a PEP and ideally merged into standard distutils gradually.

distutils-extra automatic will support the following file types and automatically determine the default values in

  • Python packages (directory with

  • D-Bus configuration (*.conf with magic string)

  • D-Bus service (*.service with magic string)

    • If it has an User= line → system service, otherwise session service




  • *.po, build *.pot: already provided by distutils-extras

  • Icons in data/icons/size/category/*.{png,svg}: already provided by distutils-extras

  • po/

  • cmdclass (default to distutils-extra classes)

  • supplementary data files: data/foo/usr/share/project/foo

  • scripts: all in ./bin/* and ./projectname which are executable's goals of "convention over configuration" conflicts with the upstream paradigm of "explicit is better than implicit", and thus will most likely not be considered upstream. We will maintain this project in Debian/Ubuntu for now.

Debian packaging

Based on the information in and the source code, we can also generate a working Debian packaging.

The van.pydeb project (packages, svn) [already provides a lot of the necessary mechanics, so this should be used by distutils-extra. will provide a new command ./ debian which generates a debian/ directory with the necessary files (see below)


  • project name, version, author, email from
  • description: "new release"
  • distro target: needs argument from environment; default to lsb_release -c?

  • If already exists, will just add a new changelog entry for a new version.


  • constant (6 for hardy support)
  • Do not change if already existing.


  • static,
  • Do not change if already existing.

  • Grep source for "([cC])" statements and add them.
  • Support some standard values of "license" and add GPL stub and author name.
  • Do not change if already existing.


  • no dh_install, upstream build system DTRT
  • Source, Package, Maintainer, Description: from
  • Section, Priority, Standards-Version, XS-Python-Version: constant
  • Build-Depends: static (no tests), or binary depends (if test cases available)
  • Depends: grep all *.py for import statements, check which package provides them
    • ./ can also specify them explicitly with the requires keyword

    • Debian specific code needs to find out which package ships it; this is a heuristic, but should get it right in 80% of the cases at least
    • The Debian Python Modules Team has a couple of scripts to do this

  • If already existing, update build/binary dependencies.

Test/Demo Plan

TODO when beta available.


DesktopTeam/Specs/Karmic/AutomagicPythonBuildSystem (last edited 2009-07-29 08:00:04 by pD9EB3788)