.. -*- coding: utf-8 -*-

Nosy
====


Introduction
------------

Run the nose_ test discovery and execution tool whenever a source file
is changed.

An elaborated version of Jeff Winkler's ``nosy`` tool that runs nose
whenever a source file is changed.  This version has a command line
parser added, and the capability to use a configuration file to
control what files are watched, and how nose runs.

.. _nose: http://www.somethingaboutorange.com/mrl/projects/nose/


Synopsis
--------

  $ nosy -h

  Usage: nosy [options]

  Automatically run nose whenever source files change.

  Options:
    -h, --help            show this help message and exit
    -c CONFIG_FILE, --config=CONFIG_FILE
                          configuration file path and name; defaults to
                          setup.cfg


Configuration File
------------------

Configuration file section contents example::

  [nosy]
  # Paths to check for changed files; changes cause nose to be run
  base_path = ./
  glob_patterns = *.py
  exclude_patterns = *_flymake.*
  extra_paths = sample.cfg
  # Command line options to pass to nose
  options = -x
  # Command line arguments to pass to nose; e.g. part of test suite to run
  tests = tests/unit_tests.py

Configuration file is read by a Python standard library ConfigParser
object, so:

  * Lines beginning with "#" or ";" are ignored and may be used to
    provide comments.
  * Entries can be in the form "name: value" or "name=value", with
    continuations in the style of RFC 822.
  * Leading whitespace is removed from values.
  * Format string substitution in values is supported.

Within the `[nosy]` section 6 options may be specified:

  * `base_path` - The directory in which to start walking the tree to
    check for changed files. Defaults to `.`.

  * `glob_patterns` - A whitespace separated list of shell glob
    patterns to check for changes. Defaults to `*.py`.

  * `exclude_patterns` - A whitespace separated list of shell glob
    patterns to exclude when checking for changes. Defaults to `''`.

  * `extra_paths` - A whitespace separated list of shell glob patterns
    to add to the paths that are checked for changes. Defaults to
    `''`.

  * `options` - A string of options to be passed through to nose when
    it is executed.

  * `tests` - A string of command line arguments to be passed through
    to nose when it is executed.  Useful for specifying part of the
    test suite to run.

Including the configuration file in the watched paths allows you to
change nose's behaviour on the fly.

The source code and bug tracker for this package is available on Bitbucket_.

.. _Bitbucket: https://bitbucket.org/douglatornell/nosy
