A manifest file is also important if you need to package files that aren't automatically included in the source distribution. By default, the following files are included in the package when generated (known as the standard include set):
- All Python source files implied by the py_modules and packages options
- All C source files listed in ext_modules or libraries options
- Any scripts identified with the scripts option
- Any test scripts, for instance, anything that looks like test*.py
- Setup and readme files: setup.py, setup.cfg, and README.txt
- All files that match the package_data and data_files metadata
Any files that don't meet these criteria, such as a license file, need to be included in a MANIFEST.ini template file. The manifest template is a list of instructions on how to generate the actual manifest file that lists the exact files to include in the source distribution.
The manifest template can include or exclude any desired files; wildcards are available as well. For example, manifest_template.py from the distutils package shows one way to list files:
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
This example indicates that all .txt files in the root directory should be included, as well as all .txt and .py files in the examples/ subdirectory. In addition, all directories that match examples/sample?/build will be excluded from the package.
The manifest file is processed after the defaults above are considered, so if you want to exclude files from the standard include set, you can explicitly list them in the manifest. If, however, you want to completely ignore all defaults in the standard set, you can use the --no-defaults option to completely disable the standard set.
The order of commands in the manifest template is important. After the standard include set is processed, the template commands are processed in order. Once that is done, the final resulting command set is processed; all files to be pruned are removed. The resulting list of files is written to the manifest file for future reference; the manifest file is then used to build the source distribution archive.
It is important to note that the manifest template does not affect binary distributions, such as wheels. It is only for use in source-file packaging.
As mentioned previously, setup.py is a key file for the packaging process, and the setup() function is what enables the details of the project to be defined.
There are a number of arguments that can be provided to the setup() function, some of which will be covered in the following list. A good example of this is shown is the Listing Packages section:
- name: The name of the project, as it will be listed on PyPI. Only ASCII alphanumeric characters, underscores, hyphens, and periods are acceptable. Must also start and end with an ASCII character. This is a required field.
Project names are case-insensitive when pulled via pip, that is, My.Project = My-project = my-PROJECT, so make sure the name itself is unique, not just a different capitalization compared to another project.
- version: The current version of your project. This is used to tell users whether they have the latest version installed, as well as indicating which specific versions they've tested their software against. This is a required field.
There is actually a document on PEP 440 (https://www.python.org/dev/peps/pep-0440/) that indicates how to write your version numbers. versioning.py is an example of versioning a project:
2.1.0.dev1 # Development release
2.1.0a1 # Alpha Release
2.1.0b1 # Beta Release
2.1.0rc1 # Release Candidate
2.1.0 # Final Release
2.1.0.post1 # Post Release
2018.04 # Date based release
19 # Serial release
- description: A short and long description of your project. These will be displayed on PyPI when the project is published. The short description is required but the long description is optional.
- url: The homepage URL for your project. This is an optional field.
- author: The developer name(s) or organization name. This is an optional field.
- author_email: The email address for the author listed above. Obfuscating the email address by spelling out the special characters, for example, your_name at your_organization dot com, is discouraged as this is a computer-readable field; use your_name@your_organization.com. This is an optional field.
- classifiers: These categorize your project to help users find it on PyPI. There is a list of classifiers (https://pypi.python.org/pypi?%3Aaction=list_classifiers) that can be used, but they are optional. Some possible classifiers include: development status, framework used, intended use case, license, and so on.
- keywords: List of keywords that describe your project. It is suggested you to use keywords that might be used by a user searching for your project. This is an optional field.
- packages: List of packages used in your project. The list can be manually entered, but setuptools.find_packages() can be used to locate them automatically. A list of excluded packages can also be included to ignore packages that are not intended for release. This is a required field.
An optional method for listing packages is to distribute a single Python file, which to change the packages argument to py_modules, which then expects my_module.py to exist in the project.
- install_requires: Specifies the minimum dependencies for the project to run. pip uses this argument to automatically identify dependencies, so these packages must be valid, existing projects. This is an optional field.
- python_requires: Specifies the Python versions the project will run on. This will prevent pip from installing the project on invalid versions. This is an optional field.
This is a relatively recent feature; setuptools version 24.2.0 is the minimum version required for creating source distributions and wheels to ensure pip properly recognizes this field. In addition, pip version 9.0.0 or newer is required; earlier versions will ignore this field and install the package regardless of Python version.
- package_data: This is used to indicate additional files to be installed in the package, such as other data files or documentation. This argument is a dictionary mapping the package name to a list of relative path names. This is an optional field.
- data_fields: While package_data is the preferred method for identifying additional files, and is normally sufficient for the purpose, there are times when data files need to be placed outside your project package, for example, configuration files that need to be stored in a particular location in the file system. This is an optional field.
- py_modules: List of names for single-file modules that are included in the project. This is a required field.
- entry_points: Dictionary of executable scripts, such as plugins, that are defined within your project or that your project depends upon. Entry points provide cross-platform support and allow pip to create the appropriate executable form for the target platform. Because of these capabilities, entry points should be used in lieu of the scripts argument. This is an optional field.
