Issue #218 resolved

Documentation on package data is misleading, unhelpful

David Wolever
created an issue

Currently the documentation0 suggests that the include_package_data and package_data directives should be used to include package data.

However, for the average project, these options are almost certainly unhelpful, as:

Very few projects use CVS or Subversion and,

The package data specified with package_data are not included in sdists

I believe the documentation should be updated so that is the recommended method for including package data (as it's the method most likely to be helpful for average projects) and the documentation for package_data (and friends) should be updated to compare it with (specifically, explaining where it should be used along side/instead of

Alternately (or at very least) it should be made clear in the documentation that data specified with package_data will not be included in an sdist.

Comments (7)

  1. Chris Jerdonek

    I would like to echo this comment.

    Specifically, the documentation gives the impression that the package_data argument can be used to add additional files to a source distribution. For example, it says, "package_data: Specify additional patterns to match files and directories that may or may not be matched by or found in source control."

    But through trial and error, I found that package_data did not result in additional files being included in a source distribution (via the `sdist` command). I needed to use to add additional files. The package_data argument wasn't providing anything extra.

    I would recommend that the documentation be modified to say that data files must be included in (for example) to be included in a source distribution, and that the package_data argument will not help in that regard. I think that small clarification will help much to head off potential user frustration.

  2. Chris Jerdonek

    Also, another potential source of confusion is that, unlike Distribute, the original distutils does include package_data in the source distribution -- whether or not those files appear in (or at least the documentation says so):

    "If you don’t supply an explicit list of files (or instructions on how to generate one), the sdist command puts a minimal default set into the source distribution: .... * all files that matches the package_data metadata. .... Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a manifest template, called by default."

  3. Log in to comment