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

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

overview
--------

This module is mostly for folks who need to write a python script
that will be run from the command line. You know, something that can
parse command line arguments and run other external programs via the
shell. The kind of script you can call with --help. Something that
perhaps reads, copies, deletes, or otherwise manipulates files by
their pathname.

If any of these apply, perhaps this module is for you!

A simple `import script` statement can provide your code with
convenient command line parsing, à la carte `--help` documentation,
useful path operations, shell command invocation with optional pipe
redirection, and early run-time termination with exit status
control. Read on for more. Cheers!

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

Python 3.0 or later.

usage
-----

Here’s a script that could tell you which files in your music collection belong to a certain genre, e.g. classical, rock, jazz, etc.

	#!/usr/bin/env python
	from script import path, shell, opts
	import script
	
	script.doc.purpose = \
		'How many flac files in ~/Music/flac belong to GENRE?'
	script.doc.args = 'GENRE'
	opts.add('verbose')
	
	def main():
		if len(script.args) != 1:
			script.exit(1, 'Please specify GENRE (or run with --help)')
		genre = script.args[0].lower()
		count = 0
		root = path('~/Music/flac')
		if opts.verbose: print('scanning', root)
		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 {} {} 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
