Distutils2 provides a set of commands that are not present in distutils itself. You might recognize some of them from other projects, like Distribute or Setuptools.
When doing test-driven development, or running automated builds that need testing before they are deployed for downloading or use, it’s often useful to be able to run a project’s unit tests without actually deploying the project anywhere. The test command runs project’s unit tests without actually deploying it, by temporarily putting the project’s source on sys.path, after first running build_ext -i to ensure that any C extensions are built.
You can use this command in one of two ways: either by specifying a unittest-compatible test suite for your project (or any callable that returns it) or by passing a test runner function that will run your tests and display results in the console. Both options: suite and runner accept dotted names that will be resolved into actual objects.
If none of these options are specified, distutils2 will try to perform test discovery using either unittest2 (if installed) or unittest (if running on recent Python version).
[test] suite = my_package.tests.all_tests
The Python Package Index (PyPI) not only stores the package info, but also the package data if the author of the package wishes to. The distutils command upload pushes the distribution files to PyPI.
The command is invoked immediately after building one or more distribution files. For example, the command
python setup.py sdist bdist_wininst upload
will cause the source distribution and the Windows installer to be uploaded to PyPI. Note that these will be uploaded even if they are built using an earlier invocation of setup.py, but that only distributions named on the command line for the invocation including the upload command are uploaded.
The upload command uses the username, password, and repository URL from the $HOME/.pypirc file . If a register command was previously called in the same command, and if the password was entered in the prompt, upload will reuse the entered password. This is useful if you do not want to store a clear text password in the $HOME/.pypirc file.
The upload command has a few options worth noting:
PyPI now supports uploading project documentation to the dedicated URL http://packages.python.org/<project>/.
The upload_docs command will create the necessary zip file out of a documentation directory and will post to the repository.
Note that to upload the documentation of a project, the corresponding version must already be registered with PyPI, using the distutils register command – just like the upload command.
Assuming there is an Example project with documentation in the subdirectory docs, for example:
Example/ |-- example.py |-- setup.cfg |-- setup.py |-- docs | |-- build | | `-- html | | | |-- index.html | | | `-- tips_tricks.html | |-- conf.py | |-- index.txt | `-- tips_tricks.txt
You can simply pass the documentation directory path to the upload_docs command:
python setup.py upload_docs --upload-dir=docs/build/html
As with any other command, you can define useful defaults in the setup.cfg of your Python project, for example:
[upload_docs] upload-dir = docs/build/html
The upload_docs command has the following options: