Package lamson :: Module args

Module args


Implements Lamson's command line argument parsing system.  It is honestly
infinitely better than optparse or argparse so it will be released later as a
separate library under the BSD license.

It's used very easily.  First, you write a module that is like lamson.commands.
Each function name BLAH_command implements a sub-command.  Then you use
lamson.args.parse_and_run_command to parse the command line and run the function
that matches.

Note that the _command suffix is optional and configurable, but it is there
to disambiguate your commands so you can use Python reserved words and base
types as your command names.  Without it, you can do a list_command or a
for_command.

You command then specifies its keyword arguments to indicate what has
reasonable defaults and what is required.  Give a value to the option
to indicate its default, and give a None setting to indicate it is required.
A good way to read this is it is your commands "default settings" and None
says "this option has no default setting".

Here's an example from lamson:


   def send_command(port=8825, host='127.0.0.1', debug=1, sender=None, to=None,
                 subject=None, body=None, file=False):

You can see this has subject, body, sender, and to as required options (they 
are None), and the rest have some default value.

With this the argument parser will parse the users given arguments, and then
call your command function with those as keyword arguments, but after it has
fixed them up with the defaults you gave.  In the event that a user does
not give a required option, lamson.args will abort with an error telling them.

Lamson's argument parser also accurately detects and parses integers, boolean
values, strings, emails, single word values, and can handle trailing arguments
after a -- argument.  This means you don't have to do conversion, it should be
the right type for what you expect.

Lamson.args does not care if you use one dash (-help), two dashes
(--help), three dashes (---help) or a billion.  In all honesty, who gives a
rat's ass, just get the user to type something like a dash followed by a word and
that's good enough.

If you just need argument parsing and no commands then you can just use
lamson.args.parse directly.

Finally, the help documentation for your commands is just the __doc__
string of the function.

Classes

[hide private]

ArgumentError
Thrown when lamson.args encounters a command line format error.

Functions

[hide private]

S_IP_ADDRESS(x, token)
ip_address

source code

S_WORD(x, token)
word

source code

S_EMAIL_ADDR(x, token)
email

source code

S_OPTION(x, token)
option

source code

S_INT(x, token)
int

source code

S_BOOL(x, token)
bool

source code

S_EMPTY(x, token)
empty

source code

S_STRING(x, token)
string

source code

S_TRAILING(x, token)
trailing

source code

match(tokens, of_type=None)
Responsible for taking a token off and processing it, ensuring it is of the correct type.

source code

peek(tokens, of_type)
Returns true if the next token is of the type, false if not.

source code

trailing_production(data, tokens)
Parsing production that handles trailing arguments after a -- is given.

source code

option_production(data, tokens)
The Option production, used for -- or - options.

source code

options_production(tokens)
List of options, optionally after the command has already been taken off.

source code

command_production(tokens)
The command production, just pulls off a word really.

source code

tokenize(argv)
Goes through the command line args and tokenizes each one, trying to match something in the scanner.

source code

parse(argv)
Tokenizes and then parses the command line as wither a command style or plain options style argument list.

source code

determine_kwargs(function)
Uses the inspect module to figure out what the keyword arguments are and what they're defaults should be, then creates a dict with that setup.

source code

ensure_defaults(options, reqs)
Goes through the given options and the required ones and does the work of making sure they match.

source code

command_module(mod, command, options, ending='_command')
Takes a module, uses the command to run that function. source code

available_help(mod, ending='_command')
Returns the dochelp from all functions in this module that have _command at the end. source code

help_for_command(mod, command, ending='_command')
Returns the help string for just this one command in the module. source code

available_commands(mod, ending='_command')
Just returns the available commands, rather than the whole long list. source code

invalid_command_message(mod, exit_on_error)
Called when you give an invalid command to print what you can use.

source code

parse_and_run_command(argv, mod, default_command=None, exit_on_error=True)
A one-shot function that parses the args, and then runs the command that the user specifies.

source code

Variables

[hide private]

SCANNER = re.Scanner([(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-...

__package__ = 'lamson'

Function Details

[hide private]

S_IP_ADDRESS(x, token)

source code

ip_address

S_WORD(x, token)

source code

word

S_EMAIL_ADDR(x, token)

source code

S_OPTION(x, token)

source code

option

S_INT(x, token)

source code

int

S_BOOL(x, token)

source code

bool

S_EMPTY(x, token)

source code

empty

S_STRING(x, token)

source code

string

S_TRAILING(x, token)

source code

trailing

match(tokens, of_type=None)

source code

Responsible for taking a token off and processing it, ensuring it is of the correct type. If of_type is None (the default) then you are asking for anything.

peek(tokens, of_type)

source code

Returns true if the next token is of the type, false if not. It does not modify the token stream the way match does.

trailing_production(data, tokens)

source code

Parsing production that handles trailing arguments after a -- is given.

option_production(data, tokens)

source code

The Option production, used for -- or - options. The number of - aren't important. It will handle either individual options, or paired options.

options_production(tokens)

source code

List of options, optionally after the command has already been taken off.

command_production(tokens)

source code

The command production, just pulls off a word really.

tokenize(argv)

source code

Goes through the command line args and tokenizes each one, trying to match something in the scanner. If any argument doesn't completely parse then it is considered a 'string' and returned raw.

parse(argv)

source code


Tokenizes and then parses the command line as wither a command style or
plain options style argument list.  It determines this by simply if the
first argument is a 'word' then it's a command.  If not then it still
returns the first element of the tuple as None.  This means you can do:

    command, options = args.parse(sys.argv[1:])

and if command==None then it was an option style, if not then it's a command 
to deal with.

determine_kwargs(function)

source code

Uses the inspect module to figure out what the keyword arguments are and what they're defaults should be, then creates a dict with that setup. The results of determine_kwargs() is typically handed to ensure_defaults().

ensure_defaults(options, reqs)

source code

Goes through the given options and the required ones and does the work of making sure they match. It will raise an ArgumentError if any option is required. It will also detect that required TRAILING arguments were not given and raise a separate error for that.

command_module(mod, command, options, ending=`'_command'`)

source code

Takes a module, uses the command to run that function.

available_help(mod, ending=`'_command'`)

source code

Returns the dochelp from all functions in this module that have _command at the end.

help_for_command(mod, command, ending=`'_command'`)

source code

Returns the help string for just this one command in the module. If that command doesn't exist then it will return None so you can print an error message.

available_commands(mod, ending=`'_command'`)

source code

Just returns the available commands, rather than the whole long list.

invalid_command_message(mod, exit_on_error)

source code

Called when you give an invalid command to print what you can use.

parse_and_run_command(argv, mod, default_command=None, exit_on_error=True)

source code

A one-shot function that parses the args, and then runs the command that the user specifies. If you set a default_command, and they don't give one then it runs that command. If you don't specify a command, and they fail to give one then it prints an error.

On this error (failure to give a command) it will call sys.exit(1). Set exit_on_error=False if you don't want this behavior, like if you're doing a unit test.

Variables Details

[hide private]

SCANNER

Value:

re.Scanner([(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}", S_EMA
IL_ADDR), (r"[0-9]+\.[0-9]+\.[0-9]+\.[0-9]", S_IP_ADDRESS), (r"-+[a-zA
-Z0-9]+", S_OPTION), (r"True", S_BOOL), (r"[0-9]+", S_INT), (r"--", S_
TRAILING), (r"[a-z\-]+", S_WORD), (r"\s", S_EMPTY), (r".+", S_STRING),
])

package

Value:

'lamson'

Module args

S_IP_ADDRESS(x, token)

S_WORD(x, token)

S_EMAIL_ADDR(x, token)

S_OPTION(x, token)

S_INT(x, token)

S_BOOL(x, token)

S_EMPTY(x, token)

S_STRING(x, token)

S_TRAILING(x, token)

match(tokens, of_type=None)

peek(tokens, of_type)

trailing_production(data, tokens)

option_production(data, tokens)

options_production(tokens)

command_production(tokens)

tokenize(argv)

parse(argv)

determine_kwargs(function)

ensure_defaults(options, reqs)

command_module(mod, command, options, ending='_command')

available_help(mod, ending='_command')

help_for_command(mod, command, ending='_command')

available_commands(mod, ending='_command')

invalid_command_message(mod, exit_on_error)

parse_and_run_command(argv, mod, default_command=None, exit_on_error=True)

SCANNER

__package__

command_module(mod, command, options, ending=`'_command'`)

available_help(mod, ending=`'_command'`)

help_for_command(mod, command, ending=`'_command'`)

available_commands(mod, ending=`'_command'`)

package