Add data files to configuration data_files.

Parameters :

files: sequence :

Argument(s) can be either

  • 2-sequence (<datadir prefix>,<path to data file(s)>)
  • paths to data files where python datadir prefix defaults to package dir.


The form of each element of the files sequence is very flexible allowing many combinations of where to get the files from the package and where they should ultimately be installed on the system. The most basic usage is for an element of the files argument sequence to be a simple filename. This will cause that file from the local path to be installed to the installation path of the package (package path). The file argument can also be a relative path in which case the entire relative path will be installed into the package directory. Finally, the file can be an absolute path name in which case the file will be found at the absolute path name but installed to the package path.

This basic behavior can be augmented by passing a 2-tuple in as the file argument. The first element of the tuple should specify the relative path (under the package install directory) where the remaining sequence of files should be installed to (it has nothing to do with the file-names in the source distribution). The second element of the tuple is the sequence of files that should be installed. The files in this sequence can be filenames, relative paths, or absolute paths. For absolute paths the file will be installed in the top-level package installation directory (regardless of the first argument). Filenames and relative path names will be installed in the package install directory under the path name given as the first element of the tuple.

Rules for installation paths:

  1. file.txt -> (., file.txt)-> parent/file.txt
  2. foo/file.txt -> (foo, foo/file.txt) -> parent/foo/file.txt
  3. /foo/bar/file.txt -> (., /foo/bar/file.txt) -> parent/file.txt
  4. *.txt -> parent/a.txt, parent/b.txt
  5. foo/*.txt -> parent/foo/a.txt, parent/foo/b.txt
  6. /.txt -> (, */.txt) -> parent/c/a.txt, parent/d/b.txt
  7. (sun, file.txt) -> parent/sun/file.txt
  8. (sun, bar/file.txt) -> parent/sun/file.txt
  9. (sun, /foo/bar/file.txt) -> parent/sun/file.txt
  10. (sun, *.txt) -> parent/sun/a.txt, parent/sun/b.txt
  11. (sun, bar/*.txt) -> parent/sun/a.txt, parent/sun/b.txt
  12. (sun/, */.txt) -> parent/sun/c/a.txt, parent/d/b.txt

An additional feature is that the path to a data-file can actually be a function that takes no arguments and returns the actual path(s) to the data-files. This is useful when the data files are generated while building the package.


Add files to the list of data_files to be included with the package.

>>> self.add_data_files('foo.dat',
...     ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']),
...     'bar/cat.dat',
...     '/full/path/to/can.dat')                   

will install these data files to:

<package install directory>/

where <package install directory> is the package (or sub-package) directory such as ‘/usr/lib/python2.4/site-packages/mypackage’ (‘C: Python2.4 Lib site-packages mypackage’) or ‘/usr/lib/python2.4/site- packages/mypackage/mysubpackage’ (‘C: Python2.4 Lib site-packages mypackage mysubpackage’).

This Page