What are the use cases for a Python distribution?

Question

I am developing a distribution for the Python package that I am writing to publish this on PyPI. This is my first work with distutils, setuptools, distribution, pip, setup.py and all that, and I'm struggling with the learning curve a bit cooler than I expected :)

I had a slight problem getting some of my test data files included in the tarball by specifying them in the data_files parameter in setup.py until I came across another message here that pointed me to the MANIFEST.in file. It was then that I noticed that what you include in tarball / zip (using MANIFEST.in) and what is installed in the Python user environment when they do easy_install or something else (based on what you specify in setup.py ) are two different things; overall a lot more in tarball than actually installed.

This immediately gave me the smell of code and the realization that there should be more than one use case; I was attached to only one on which I really participated, using easy_install or pip to install the library. And then I realized that I was developing a working product where I had only a partial understanding of the end users for whom I was developing.

So my question is: "What are the use cases for the Python distribution besides installing it in the same Python environment? Who else do I serve with this distribution and what do they care most about?"

Here are some of the working issues that I haven't figured out yet, Answer:

• Is it wise to include everything under source control? (git) in the source distribution? In the github era, did anyone download a distribution source to access the full source of a project? Or should I just send a link to my github report? Won't it include all the fanning of the spread and take more time to download for people who just want to install it?

• I am going to post documentation on readthedocs.org. Does this make any sense for me to include HTML versions of documents in source distribution code?

• Does anyone use python setup.py test to run tests on source distribution? If so, what is their role and in what situation are they? I don’t know if I should do this work, and if so, who does it work.

Answer 1

Some things that you might want to include in the source distribution, but may not install:

• package license
• test suite
• documentation (possibly a processed form, such as HTML in addition to the source)
• possibly any additional scripts used to create the source distribution

Quite often, this will be the majority or all of what you control in version control and, possibly, several generated files.

The main reason you do this when these files are available online or through version control is because people know that they have a version of documents or tests that match the code in which they work.

If you only post the latest version of documents on the Internet, they may not be suitable for those who, for some reason, should use the older version. And the set of tests at the tip in version control may not be compatible with the version of the code in the source distribution (for example, if it checks the functions added since then). To get the correct version of documents or tests, they will need to comb the version control element, looking for a tag that matches the source distribution (provided that the developers have bothered to mark the tree). Having the files available in the source distribution avoids this problem.

As for people who want to run a test suite, I have a number of my Python modules packaged in various Linux distributions, and sometimes I get error messages related to testing errors in their environment. I also used other people's test suites when I came across an error, and I want to check if the external code runs as the author expects in my environment.