script.py
=========

* version : 1.4.1
* author : Iain Lamb <x+python@lamb.cc>
* url : http://lamb.cc/script
* license : Copyright (c) 2009 by Iain Lamb. Licensed to PSF under a Contributor Agreement. See http://www.python.org/2.6/license for details.

overview
--------

This module distills a collection of common shell script patterns into a few
terse definitions. Most of the objects and functions wrap lower-level calls to
modules in the standard Python library such as `optparse`, `os.path`, `shutil`,
and `subprocess`.

With just one `import` statement, you can provide your script with ready to go
command line parsing, convenient path operations, ala carte `--help`
documentation, quick writes to `stdout` / `stderr`, and easy invocation of shell
commands (including the ability to capture output).

requirements
------------

Python 3.0 or later.

usage
-----

	#!/usr/bin/env python
	from script import path, shell, err
	import script
	script.doc.purpose = \
		'How many flac files in ~/Music/flac belong to GENRE?'
	script.doc.args = 'GENRE'
	script.opts.preset('verbose')
	def main():
		if len(script.args) != 1:
			err('Please specify GENRE (or run with --help)')
			script.exit(1)
		genre = script.args[0].lower()
		count = 0
		root = path('~/Music/flac')
		err('scanning', root, when=script.opts.verbose)
		for parent, dirs, files in root.walk('*.flac'):
			for file in files:
				cmd = 'metaflac --show-tag=GENRE ' + path(parent/file).sh
				result = shell(cmd, stdout='PIPE').stdout
				if genre == result.lstrip('GENRE=').rstrip().lower():
					count += 1
		print('found {0} {1} files'.format(count, genre))
	
	if __name__ == '__main__': script.run(main)

This example could be run with `--help` or `--verbose`.

documentation
-------------

Vist http://lamb.cc/script or run `pydoc script.py`

installation
------------

There are two simple and quick options:

Install locally. Just drop the `script.py` file into the same directory as any
other Python files that intend to `import` it.

Install site-wide. This will let you import the `script` module from anywhere,
just like the other built in modules in the standard Python library. Run the
`setup.py` script from the command line:

	python ./setup.py install
	
Some systems require administrative privileges to do this, e.g.

 	sudo python ./setup.py install
