350 lines
8.9 KiB
ReStructuredText
350 lines
8.9 KiB
ReStructuredText
|
.. _packaging-command-reference:
|
||
|
|
|
||
|
|
*****************
|
||
|
|
Command Reference
|
||
|
|
*****************
|
||
|
|
|
||
|
|
This reference briefly documents all standard Packaging commands and some of
|
||
|
|
their options.
|
||
|
|
|
||
|
|
.. FIXME does not work: Use pysetup run --help-commands to list all
|
||
|
|
standard and extra commands availavble on your system, with their
|
||
|
|
description. Use pysetup run <command> --help to get help about the options
|
||
|
|
of one command.
|
||
|
|
|
||
|
|
|
||
|
|
Preparing distributions
|
||
|
|
=======================
|
||
|
|
|
||
|
|
:command:`check`
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Perform some tests on the metadata of a distribution.
|
||
|
|
|
||
|
|
For example, it verifies that all required metadata fields are provided in the
|
||
|
|
:file:`setup.cfg` file.
|
||
|
|
|
||
|
|
.. TODO document reST checks
|
||
|
|
|
||
|
|
|
||
|
|
:command:`test`
|
||
|
|
---------------
|
||
|
|
|
||
|
|
Run a test suite.
|
||
|
|
|
||
|
|
When doing test-driven development, or running automated builds that need
|
||
|
|
testing before they are installed for downloading or use, it's often useful to
|
||
|
|
be able to run a project's unit tests without actually installing the project
|
||
|
|
anywhere. The :command:`test` command runs project's unit tests without
|
||
|
|
actually installing it, by temporarily putting the project's source on
|
||
|
|
:data:`sys.path`, after first running :command:`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 take a Python dotted name in the form
|
||
|
|
``package.module.callable`` to specify the object to use.
|
||
|
|
|
||
|
|
If none of these options are specified, Packaging will try to perform test
|
||
|
|
discovery using either unittest (for Python 3.2 and higher) or unittest2 (for
|
||
|
|
older versions, if installed).
|
||
|
|
|
||
|
|
.. this is a pseudo-command name used to disambiguate the options in indexes and
|
||
|
|
links
|
||
|
|
.. program:: packaging test
|
||
|
|
|
||
|
|
.. cmdoption:: --suite=NAME, -s NAME
|
||
|
|
|
||
|
|
Specify the test suite (or module, class, or method) to be run. The default
|
||
|
|
for this option can be set by in the project's :file:`setup.cfg` file::
|
||
|
|
|
||
|
|
.. code-block:: cfg
|
||
|
|
|
||
|
|
[test]
|
||
|
|
suite = mypackage.tests.get_all_tests
|
||
|
|
|
||
|
|
.. cmdoption:: --runner=NAME, -r NAME
|
||
|
|
|
||
|
|
Specify the test runner to be called.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`config`
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
Perform distribution configuration.
|
||
|
|
|
||
|
|
|
||
|
|
The build step
|
||
|
|
==============
|
||
|
|
|
||
|
|
This step is mainly useful to compile C/C++ libraries or extension modules. The
|
||
|
|
build commands can be run manually to check for syntax errors or packaging
|
||
|
|
issues (for example if the addition of a new source file was forgotten in the
|
||
|
|
:file:`setup.cfg` file), and is also run automatically by commands which need
|
||
|
|
it. Packaging checks the mtime of source and built files to avoid re-building
|
||
|
|
if it's not necessary.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`build`
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Build all files of a distribution, delegating to the other :command:`build_*`
|
||
|
|
commands to do the work.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`build_clib`
|
||
|
|
---------------------
|
||
|
|
|
||
|
|
Build C libraries.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`build_ext`
|
||
|
|
--------------------
|
||
|
|
|
||
|
|
Build C/C++ extension modules.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`build_py`
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
Build the Python modules (just copy them to the build directory) and
|
||
|
|
byte-compile them to .pyc files.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`build_scripts`
|
||
|
|
------------------------
|
||
|
|
Build the scripts (just copy them to the build directory and adjust their
|
||
|
|
shebang if they're Python scripts).
|
||
|
|
|
||
|
|
|
||
|
|
:command:`clean`
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Clean the build tree of the release.
|
||
|
|
|
||
|
|
.. program:: packaging clean
|
||
|
|
|
||
|
|
.. cmdoption:: --all, -a
|
||
|
|
|
||
|
|
Remove build directories for modules, scripts, etc., not only temporary build
|
||
|
|
by-products.
|
||
|
|
|
||
|
|
|
||
|
|
Creating source and built distributions
|
||
|
|
=======================================
|
||
|
|
|
||
|
|
:command:`sdist`
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Build a source distribution for a release.
|
||
|
|
|
||
|
|
It is recommended that you always build and upload a source distribution. Users
|
||
|
|
of OSes with easy access to compilers and users of advanced packaging tools will
|
||
|
|
prefer to compile from source rather than using pre-built distributions. For
|
||
|
|
Windows users, providing a binary installer is also recommended practice.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`bdist`
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Build a binary distribution for a release.
|
||
|
|
|
||
|
|
This command will call other :command:`bdist_*` commands to create one or more
|
||
|
|
distributions depending on the options given. The default is to create a
|
||
|
|
.tar.gz archive on Unix and a zip archive on Windows or OS/2.
|
||
|
|
|
||
|
|
.. program:: packaging bdist
|
||
|
|
|
||
|
|
.. cmdoption:: --formats
|
||
|
|
|
||
|
|
Binary formats to build (comma-separated list).
|
||
|
|
|
||
|
|
.. cmdoption:: --show-formats
|
||
|
|
|
||
|
|
Dump list of available formats.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`bdist_dumb`
|
||
|
|
---------------------
|
||
|
|
|
||
|
|
Build a "dumb" installer, a simple archive of files that could be unpacked under
|
||
|
|
``$prefix`` or ``$exec_prefix``.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`bdist_wininst`
|
||
|
|
------------------------
|
||
|
|
|
||
|
|
Build a Windows installer.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`bdist_msi`
|
||
|
|
--------------------
|
||
|
|
|
||
|
|
Build a `Microsoft Installer`_ (.msi) file.
|
||
|
|
|
||
|
|
.. _Microsoft Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
|
||
|
|
|
||
|
|
In most cases, the :command:`bdist_msi` installer is a better choice than the
|
||
|
|
:command:`bdist_wininst` installer, because it provides better support for Win64
|
||
|
|
platforms, allows administrators to perform non-interactive installations, and
|
||
|
|
allows installation through group policies.
|
||
|
|
|
||
|
|
|
||
|
|
Publishing distributions
|
||
|
|
========================
|
||
|
|
|
||
|
|
:command:`register`
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
This command registers the current release with the Python Package Index. This
|
||
|
|
is described in more detail in :PEP:`301`.
|
||
|
|
|
||
|
|
.. TODO explain user and project registration with the web UI
|
||
|
|
|
||
|
|
|
||
|
|
:command:`upload`
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
Upload source and/or binary distributions to PyPI.
|
||
|
|
|
||
|
|
The distributions have to be built on the same command line as the
|
||
|
|
:command:`upload` command; see :ref:`packaging-package-upload` for more info.
|
||
|
|
|
||
|
|
.. program:: packaging upload
|
||
|
|
|
||
|
|
.. cmdoption:: --sign, -s
|
||
|
|
|
||
|
|
Sign each uploaded file using GPG (GNU Privacy Guard). The ``gpg`` program
|
||
|
|
must be available for execution on the system ``PATH``.
|
||
|
|
|
||
|
|
.. cmdoption:: --identity=NAME, -i NAME
|
||
|
|
|
||
|
|
Specify the identity or key name for GPG to use when signing. The value of
|
||
|
|
this option will be passed through the ``--local-user`` option of the
|
||
|
|
``gpg`` program.
|
||
|
|
|
||
|
|
.. cmdoption:: --show-response
|
||
|
|
|
||
|
|
Display the full response text from server; this is useful for debugging
|
||
|
|
PyPI problems.
|
||
|
|
|
||
|
|
.. cmdoption:: --repository=URL, -r URL
|
||
|
|
|
||
|
|
The URL of the repository to upload to. Defaults to
|
||
|
|
http://pypi.python.org/pypi (i.e., the main PyPI installation).
|
||
|
|
|
||
|
|
.. cmdoption:: --upload-docs
|
||
|
|
|
||
|
|
Also run :command:`upload_docs`. Mainly useful as a default value in
|
||
|
|
:file:`setup.cfg` (on the command line, it's shorter to just type both
|
||
|
|
commands).
|
||
|
|
|
||
|
|
|
||
|
|
:command:`upload_docs`
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Upload HTML documentation to PyPI.
|
||
|
|
|
||
|
|
PyPI now supports publishing project documentation at a URI of the form
|
||
|
|
``http://packages.python.org/<project>``. :command:`upload_docs` 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 :command:`register` command ---
|
||
|
|
just like with :command:`upload`.
|
||
|
|
|
||
|
|
Assuming there is an ``Example`` project with documentation in the subdirectory
|
||
|
|
:file:`docs`, for example::
|
||
|
|
|
||
|
|
Example/
|
||
|
|
example.py
|
||
|
|
setup.cfg
|
||
|
|
docs/
|
||
|
|
build/
|
||
|
|
html/
|
||
|
|
index.html
|
||
|
|
tips_tricks.html
|
||
|
|
conf.py
|
||
|
|
index.txt
|
||
|
|
tips_tricks.txt
|
||
|
|
|
||
|
|
You can simply specify the directory with the HTML files in your
|
||
|
|
:file:`setup.cfg` file:
|
||
|
|
|
||
|
|
.. code-block:: cfg
|
||
|
|
|
||
|
|
[upload_docs]
|
||
|
|
upload-dir = docs/build/html
|
||
|
|
|
||
|
|
|
||
|
|
.. program:: packaging upload_docs
|
||
|
|
|
||
|
|
.. cmdoption:: --upload-dir
|
||
|
|
|
||
|
|
The directory to be uploaded to the repository. By default documentation
|
||
|
|
is searched for in ``docs`` (or ``doc``) directory in project root.
|
||
|
|
|
||
|
|
.. cmdoption:: --show-response
|
||
|
|
|
||
|
|
Display the full response text from server; this is useful for debugging
|
||
|
|
PyPI problems.
|
||
|
|
|
||
|
|
.. cmdoption:: --repository=URL, -r URL
|
||
|
|
|
||
|
|
The URL of the repository to upload to. Defaults to
|
||
|
|
http://pypi.python.org/pypi (i.e., the main PyPI installation).
|
||
|
|
|
||
|
|
|
||
|
|
The install step
|
||
|
|
================
|
||
|
|
|
||
|
|
These commands are used by end-users of a project using :program:`pysetup` or
|
||
|
|
another compatible installer. Each command will run the corresponding
|
||
|
|
:command:`build_*` command and then move the built files to their destination on
|
||
|
|
the target system.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_dist`
|
||
|
|
-----------------------
|
||
|
|
|
||
|
|
Install a distribution, delegating to the other :command:`install_*` commands to
|
||
|
|
do the work.
|
||
|
|
|
||
|
|
.. program:: packaging install_dist
|
||
|
|
|
||
|
|
.. cmdoption:: --user
|
||
|
|
|
||
|
|
Install in user site-packages directory (see :PEP:`370`).
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_data`
|
||
|
|
-----------------------
|
||
|
|
|
||
|
|
Install data files.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_distinfo`
|
||
|
|
---------------------------
|
||
|
|
|
||
|
|
Install files recording details of the installation as specified in :PEP:`376`.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_headers`
|
||
|
|
--------------------------
|
||
|
|
|
||
|
|
Install C/C++ header files.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_lib`
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Install C library files.
|
||
|
|
|
||
|
|
|
||
|
|
:command:`install_scripts`
|
||
|
|
--------------------------
|
||
|
|
|
||
|
|
Install scripts.
|