Improve README with example usage about python-deb-pkg-tools HOT 2 CLOSED

def build_package(directory, repository=None, check_package=True, copy_files=True):
    """
    Create a Debian package using the ``dpkg-deb --build`` command.

    :param directory: The pathname of a directory tree suitable for packaging
                      with ``dpkg-deb --build``.
    :param repository: The pathname of the directory where the generated
                       ``*.deb`` archive should be stored.

                       By default a temporary directory is created to store the
                       generated archive, in this case the caller is
                       responsible for cleaning up the directory.

                       Before deb-pkg-tools 2.0 this defaulted to the system
                       wide temporary directory which could result in corrupted
                       archives during concurrent builds.
    :param check_package: If :data:`True` (the default) Lintian_ is run to check
                          the resulting package archive for possible issues.
    :param copy_files: If :data:`True` (the default) the package's files are copied
                       to a temporary directory before being modified. You can
                       set this to :data:`False` if you're already working on a
                       copy and don't want yet another copy to be made.
    :returns: The pathname of the generated ``*.deb`` archive.
    :raises: :exc:`executor.ExternalCommandFailed` if any of the external
             commands invoked by this function fail.

    The ``dpkg-deb --build`` command requires a certain directory tree layout
    and specific files; for more information about this topic please refer to
    the `Debian Binary Package Building HOWTO`_. The :func:`build_package()`
    function performs the following steps to build a package:

    1. Copies the files in the source directory to a temporary build directory.
    2. Updates the Installed-Size_ field in the ``DEBIAN/control`` file
       based on the size of the given directory (using
       :func:`update_installed_size()`).
    3. Sets the owner and group of all files to ``root`` because this is the
       only user account guaranteed to always be available. This uses the
       ``fakeroot`` command so you don't actually need ``root`` access to use
       :func:`build_package()`.
    4. Runs the command ``fakeroot dpkg-deb --build`` to generate a Debian
       package from the files in the build directory.
    5. Runs Lintian_ to check the resulting package archive for possible
       issues. The result of Lintian is purely informational: If 'errors' are
       reported and Lintian exits with a nonzero status code, this is ignored
       by :func:`build_package()`.

    .. _Debian Binary Package Building HOWTO: http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/
    .. _Installed-Size: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Installed-Size
    .. _Lintian: http://lintian.debian.org/
    """