Right now there are several ways to build the MANIFEST file that comes with a source distribution, besides the scripts.

People tend to use:

Moreover, Distutils will include some elements by default, like README.txt and so one.

There's no consensus on what is the good practice yet, but;

The problem is that a packager that wants to work with a package might be unable to get the list of files of this package if he doesn't work exactly like the author.


Result :


This proposal does not solve the problem, because it's unsolvable. Unless everyone use the same way to list the files, people have to work around. This proposal make Distutils simpler to use, no matter how people build their file list.

Let's add in Distutils:

plugin system

The plugin system is inspired from Setuptools entry points.

Maybe setuptools entry_points code could be added in Distutils, but this section describes the need nevertheless.

Some functions are added in Distutils, in a module called plugins:

The filelist module implements a default plugin, in the distutils:filelist group, that contains the current Distutils algorithm that builds the MANIFEST file:

    >>> register_plugin('distutils:filelist', 'default',
    ...                 distutils.filelist.FileList)

Distutils is refactored in order to use this plugin. For instance the default plugin is the FileList class. It's used by the sdist command for example.

The default plugin uses another plugin called template, that uses the templating system:

    >>> register_plugin('distutils:filelist', 'template',
    ...                 distutils.filelist.ManifestTemplate)

Another plugin is also provided, called static:

    >>> register_plugin('distutils:filelist', 'static',

This plugin allows to provide a path to a simple file that contains the list of file (like a MANIFEST file).

Last, list_plugins('distutils:filelist'), returns a list of all plugins names of a given group:

    >>> list_plugins('distutils:filelist')
    ['default', 'template', 'static']

An optional parameter can be use to get more information:

    >>> list_plugins('distutils:filelist', doc=True)
    [('default', 'Default plugin to get the file list of a package'),
     ('static', 'Returns a file list given a path of a file that contains the list')]

Without parameters, list_plugins() returns all objects.

How a plugin is called and used ?

A plugin is called with a in-out argument called filelist, an optional root_path argument and a list of keywords:

    >>> get_plugin('distutils:filelist', 'default')(filelist, root_path='/somewhere')

If root_path is None, the plugin might want to use the current working directory to start his scanning work.

In sdist, the plugin is called with the current working directory and all options passed to sdist.

How to choose one or several plugin

sdist will have a new option, called manifest, this option is a list of plugin names. If not given, ['default'] is used by default.

Someone that wants to use another plugin will simply add it in the list:

    >>> setup(name='foo', manifest=['hg'])

He might also want to use several plugins. For instance, build a file list with the hg plugin, then exclude some files with the template plugin:

    >>> setup(name='foo', manifest=['hg', 'template'])

The sdist command will loop over all plugins to build the file list using this simple code::

    >>> def get_filelist():
    ...    filelist = []
    ...    for name in list_plugins('distutils:filelist'):
    ...        plugin = get_plugin(name)
    ...        plugin(filelist)
    ...    return filelist

Each plugin is able to add or remove a file from the file list.

the manifest metadata

The manifest metadata already exists in a sense. It's not in PKG-INFO itself, but lands into the .egg-info directory once it's built.

A new display option will allow people to get it without having to call sdist or egg_info, exactly like --long-description provides:

    $ python --manifest

This will call the get_filelist() function and display its result in the standard output.

Distutils/ManifestPluginSystem (last edited 2009-04-07 18:13:04 by tarek)

Unable to edit the page? See the FrontPage for instructions.