lesscode.org

Buildutils Command Reference

Editors:Ryan Tomayko <rtomayko@lesscode.org>
Revision: $Rev$
Date: 2005-03-09 15:26:45 -0500 (Wed, 09 Mar 2005)
Copyright: Copyright © 2005
License:GNU Free Documentation License

The Buildutils Command Reference provides usage information for the commands available in the buildutils project.

The Commands

announce -- Send project announcement email

Sends a release announcement to python-announce-list@python.org or a user specified list of email addresses.

This command uses various pieces of project metadata to piece together an announcement message. The default message is:

${name} ${version} is available:

<${download_url}>
  
${long_description}
  
For more information, visit the ${name} project site:
<${url}>

${contact}
<${contact_email}>

You can change the message in the project's setup.cfg using the message= option.

Synopsis

Send an announcement to announce@example.com:

pbu announce --recipients=announce@example.com

Common setup.cfg options:

[announce]
recipients=announce@example.com, another@example.com
reply-to=moe@stooges.com

Options

edit (--edit, -e)

Bring up an editor on the message before sending. This lets you preview the message and make changes before sending. If you don't want to send the message, you can delete all text before exiting the editor and the command will bail.

The editor used is based on the EDITOR environment variable. If no EDITOR environment variable is found, vi is attempted.

message (--message=, -m)

This option has varying usage depending on whether it is specified on the command line or in a config file. When the --message or -m argument is given, it is assumed to be a filename containing the message text. You can also pass "-" here to read from stdin.

When the message= option is pulled from a config file, it is the actual message.

The default value is described in the command overview.

recipients (--recipients=, -t)

A comma or space seperated list of email addresses to send the announcement email to.

Default: python-announce-list@python.org

reply-to (--reply-to=, -f)

The email address where replies should be sent.

Default: ${contact_name}

subject (--subject, -s)

The announcement email's subject.

Default: ANN: ${fullname} - ${description}

The following options support variable expansion: message, reply-to, subject, recipients.

Notes

The announce command will attempt to use sendmail if found and fallback to an SMTP server on localhost. Future versions of the command will include support for specifying the sending method, SMTP host/auth, etc.

checksum -- Build SHA-1/MD5 Checksum Files

The checksum command generates SHA-1 and/or MD5 checksum files containing hashes for all distributables under the dist directory. It can generate a single checksum file for all distributables or one checksum file per distributable. Checksum files may optionally be signed using GPG.

Synopsis

Build a source distribution and create a single SHA-1 checksum file containing the hashes for all distributable files under the dist directory:

pbu sdist checksum --sha

Common setup.cfg options:

[checksum]
per-file=1
md5=0
sha=1
sign=1

Options

dist-dist (--dist-dir=, -d)
The directory containing distributables that should be signed. This directory is also where .sha and/or .md5 files are generated.
force (--force, -f)
Force generation of checksum files even if they exist and are up to date.
md5 (--md5, -m)
Generate MD5 checksums.
per-file (--per-file, -p)

When specified, multiple checksum files are generated - one for each distributable in dist-dir. The checksum file names will be equivelant to the original distribution with an additional sha or md5 extension.

When this option is not specified, checksums for all distributables are placed in a single file named name-version.sha or name-version.md5, where name and version correspond to the values specified in setup.py.

sha (--sha)
Generate SHA-1 checksums. This is the default. The --no-sha or -s options can be used to turn of SHA-1 checksums.
sign (--sign)
Sign all checksum files using GnuPG. Note that this requires gpg and a secret key.

etags -- Generate Emacs TAGS file

Generates an Emacs TAGS file for all packages and modules in the current project.

Emacs Tags provide an indexing mechanism for various types source files that allows Emacs to provide such cool features as auto-complete and go-to-definition.

Once the TAGS file is generated, you can bring it into Emacs by invoking M-x visit-tags-table and then entering the path to the TAGS file (the project root directory).

Some of the useful Tags functions are:

Keystroke Description
M-. Find first definition of a tag.
M-x tags-search Search for a specified regular expression through the files in the selected tag table.
M-, Find next definition of previous tag, next occurrence of specified regular expression.

More information on Emacs Tags can be found under the Tags Node of the GNU Emacs Manual.

Synopsis

Running the etags command:

pbu etags

Options

command (--command=, -c)
Specify the location of the etags executable. The default is to search along the $PATH looking for a command named etags.
tags-file (--tags-file=, -t)
Where to write the TAGS file. Default is a file named TAGS in the project's directory (i.e. right next to setup.py).
force (--force, -f)
For creation of the TAGS file even if a TAGS file exists that is newer than all of the source files.

flakes -- Find Lint

From the pyflakes project page:

Pyflakes is a simple program which checks Python source files for errors. It is similar to PyChecker in scope, but differs in that it does not execute the modules to check them. This is both safer and faster, although it does not perform as many checks. Unlike PyLint, Pyflakes checks only for logical errors in programs; it does not perform any checks on style.

Synopsis

Running the flakes command on the buildutils project:

[ rtomayko@pips:~/devel/buildutils ]$ pbu flakes
warning: flakes: buildutils/__init__.py:23: 'compat' imported but unused
warning: flakes: buildutils/command/pudge.py:68: 'isdir' imported but unused
warning: flakes: buildutils/command/pudge.py:83: 'normpath' imported but unused
warning: flakes: buildutils/command/use.py:98: undefined name 'egg'

Options

There are no options for the flakes command.

info -- Dump Project Info

This is a simple command that dumps project information to standard output.

Synopsis

Running the info command on the buildutils project:

[ rtomayko@pips:~/devel/buildutils ]$ pbu info
buildutils - Distutils extensions for developing Python libraries and applications.

Name:       buildutils          Author:     Ryan Tomayko <rtomayko@lesscode.org>
Version:    0.1.0
License:    MIT
Platforms:  All (not specified)

Project URL:  <http://buildutils.lesscode.org/>
Download URL: <http://buildutils.lesscode.org/dist/0.1.0/>

Trove Classifiers:

    Development Status :: 4 - Beta
    Environment :: Console
    Intended Audience :: Developers
    Intended Audience :: System Administrators
    License :: OSI Approved :: MIT License
    Operating System :: OS Independent
    Programming Language :: Python
    Topic :: Software Development :: Build Tools
    Topic :: System :: Installation/Setup
    Topic :: System :: Software Distribution
    Topic :: Utilities

Description:

    The `buildutils` package contains extensions to Python's standard
    distribution utilities (`distutils`) that are often useful during the
    development of Python projects. `buildutils` was created to scratch an
    itch: removing ``make`` from the Python development process and partially

...

Options

The info command has no options.

publish -- Push distributables and documentation to remote site

The publish command can be used to transfer distributables and documentation files to a remote site using a variety of transport protocols.

Currently, only SSH/SCP or SFTP are supported and require external ssh, scp, and sftp system commands.

Synopsis

Publishing distributables after building and generating checksum files:

pbu sdist bdist_egg checksum publish --dist-dest=scp://stooges.com/project/

The setup.cfg file is an excellent place to put remote locations:

[publish]
dist-dest=scp://curly@stooges.com/projects/$name/
make-dirs=1

Options

dist-dir (--dist-dir=, -d)
Directory containing distributables to transfer. It should be rare that the default value needs overridden.
dist-dest (--dist-dest=, -t)
The destination URL where distributables should be transfered.
doc-dir (--doc-dir=)
Directory containing documentation.
doc-dest (--doc-dest=)
The destination URL where documentation files should be transfered.
make-dirs (--make-dirs=, -m)
Try to create the dest directories if they do not exist on the remote site.
protocol-list (--protocol-list)
Display a list of available protocols / URL schemes that can be used to transfer files.

pudge -- Generate Documentation

The pudge command is used to generate documentation in either HTML 4.01 or XHTML 1.0 format. pudge can extract documentation strings from python objects and has support for restructured text. It's also possible to generate documentation from restructured text documents.

Synopsis

Generate documentation for all modules and packages, include a GNU Free Documentation License, and open the documentation in a web browser after it has been generated:

pbu pudge --license=gnu -o

Common setup.cfg options:

[pudge]
docs=doc/index.rst doc/users-guide.rst
title=Some Package
license=cc
xhtml=1

Options

dest (--dest=, -d)
The directory where documentation should be generated. If this option isn't specified, build/doc is assumed.
docs (--docs=, -i)
List of restructured text documents to include in generated documentation.
license (--license=)
Include a standard license document. Current options are 'gnu' for the GNU Free Documentation License and 'cc' for a Creative Commands Attribution, NonCommercial, copyleft license.
modules (--modules=, -m)
List of module or package names that should be documented. This argument defaults to all modules and packages specified in the projects setup.py file using the py_modules and packages arguments to setup(). In most cases, this option should not need to be customized.
open (--open, -o)
Open generated documentation in a web browser. Handy when testing generated documentation.
pages (--pages=, -p)

Specify the list of pages that should be opened when the --open option is provided. Separate page file names by commas:

pbu pudge -o --pages=index.html,mydoc.html,module-foo.bar.html
stages (--stages=, -s)

A comma separated list of documentation generation stages that should be performed. This can speed the generation process during testing by omitting steps that are not needed. Available stages are as follows:

  • docs - generate documentation from restructured text documents specified by the --docs option.
  • index - generate the index document.
  • reference - generate module reference documentation.
  • copy - copy other files (CSS, images, etc.)
  • source - generate syntax colored source files.
title (--title=)
The title of the documentation set.
xhtml (--xhtml=, -x)
Output documentation as XHTML 1.0 instead of HTML 4.01. HTML 4.01 is recommended due to browser compatibility issues with XHTML 1.0.

pytest -- Run py.test unit tests

Runs py.test based unit tests for the current project.

For more information on writing py.test based unit tests, see The py.test tool and library. Grig Gheoghiu provides a nice comparison of py.test to other unit testing frameworks in Python unit testing part 3 - py.test.

Synopsis

Test

Options

Options for the pytest buildutils command mirror those of the py.test command line utility with some minor differences.

tests (--tests=, -t)
A comma separated list of test files or directories to search for test files. Directories are searched recursively for files named either test_*.py or *_test.py.
collectonly (--collectonly)
Collect but do not execute tests. This is useful in determining what tests are available and to check that collection is working properly.
exitfirst (--exitfirst, -x)
Exit after the first unit test error or failure. This option is recommended when developing.
fulltrace (--fulltrace)
Don't cut any traceback entries. The default is to remove commonly useless entries.
nocapture (--no-capture, -s)
Don't capture sys.stdin, sys.stdout for each tests. When this option is enabled, printed messages are displayed immediately. With the option off, messages are displayed only when tests fail.
nomagic (--no-magic)
Refrain from using magic as much as possible. Enable this option if your tests seem to be failing for odd reasons.
pdb (--pdb)
Start pdb (The Python Debugger) when a test fails.
showlocals (--showlocals, -l)
Show the name/values of locals() in traceback dumps. This is useful for quick debugging but requires more resources.
looponfailing (--looponfailing, -f)
When tests fail, watch for file modifications and automatically re-run the test until all tests pass. This option is golden when used with -x.
tkinter (--tkinter)
Use the tkinter GUI interface for tests.

Notes

py.test has not yet been packaged into a distutils package or released on PYPI and cannot be automatically installed by the dependency resolution feature.

You will need to follow the instructions from Getting Started with py lib to install and configure the py distribution before this command will work properly.

The basic process is to checkout the latest sources from subversion and then to bring the configuration into your shell. For example, to bring the library into a python directory off of your home directory on POSIX systems, you might run:

$ cd ~/python
$ svn co http://codespeak.net/svn/py/dist py-dist

You will need to setup your environment before invoking the pytest command, as follows:

$ eval `python ~/path/to/py-dist/py/env.py`

stats -- Dump Code Statistics

The stats command shows high level source code statistics about a project including the number of files, modules, packages, and lines.

The following line statistics are provided for each file and in aggregate:

lines
The total number of lines in the file.
code
The number of lines that contain python code (excludes comments, doc strings, and blank lines)
doc
The number of doc string lines.
comment
The number of comment lines.
blank
The number of blank lines.

Synopsis

Dump stats for the buildutils project:

[ rtomayko@pips:~/devel/buildutils ]$ pbu stats
running stats
   lines    code     doc comment   blank  file
 ------- ------- ------- ------- -------  -----------------------------------
      38      12      18       3       5  buildutils/__init__.py
      73      55      10       0       8  buildutils/cmd.py
      28      16      10       0       2  buildutils/command_utils.py
     390     196     100      37      57  buildutils/pycount.py
      23      16       2       1       4  buildutils/pysetup.py
       6       2       3       0       1  buildutils/command/__init__.py
     195     165       4       4      22  buildutils/command/announce.py
     129     109       3       2      15  buildutils/command/checksum.py
      48      29       7       4       8  buildutils/command/etags.py
      61      33      15       1      12  buildutils/command/flakes.py
     107      90       0       6      11  buildutils/command/info.py
     109      92       0       4      13  buildutils/command/publish.py
      92      81       0       4       7  buildutils/command/pudge.py
     122     111       0       3       8  buildutils/command/pytest.py
      68      59       0       3       6  buildutils/command/stats.py
     106      87       3       4      12  buildutils/command/use.py
      25      18       1       3       3  buildutils/compat/__init__.py
     125      96       7       8      14  buildutils/compat/string_template.py
       1       0       0       0       1  buildutils/test/__init__.py
       6       5       0       0       1  buildutils/test/test_compat.py
    1752    1272     183      87     210  [total]

1272 lines of code, 20 modules, 4 packages.

Options

exclude-tests (--exclude-tests, -t)
Exclude any modules whose name begins with "test_", ends with "_test", or resides in a directory named "test".

Notes

The stats command is based on pycount.py, by Dinu C. Gherman, which is included in the buildutils distribution.

Additional Command Dependencies

Certain commands require additional packages.

Command Dependencies
checksum GnuPG
etags The etags command (included with Emacs)
pudge Pudge Documentation Utility, Kid Template, ElementTree
flakes pyflakes
pytest py.test
publish The scp or sftp commands (included with OpenSSH).