Package CedarBackup2 :: Module cli :: Class Options
[show private | hide private]
[frames | no frames]

Type Options

object --+
         |
        Options


Class representing command-line options for the cback script.

The Options class is a Python object representation of the command-line options of the cback script.

The object representation is two-way: a command line string or a list of command line arguments can be used to create an Options object, and then changes to the object can be propogated back to a list of command-line arguments or to a command-line string. An Options object can even be created from scratch programmatically (if you have a need for that).

There are two main levels of validation in the Options class. The first is field-level validation. Field-level validation comes into play when a given field in an object is assigned to or updated. We use Python's property functionality to enforce specific validations on field values, and in some places we even use customized list classes to enforce validations on list members. You should expect to catch a ValueError exception when making assignments to fields if you are programmatically filling an object.

The second level of validation is post-completion validation. Certain validations don't make sense until an object representation of options is fully "complete". We don't want these validations to apply all of the time, because it would make building up a valid object from scratch a real pain. For instance, we might have to do things in the right order to keep from throwing exceptions, etc.

All of these post-completion validations are encapsulated in the Options.validate method. This method can be called at any time by a client, and will always be called immediately after creating a Options object from a command line and before exporting a Options object back to a command line. This way, we get acceptable ease-of-use but we also don't accept or emit invalid command lines.

Note: Lists within this class are "unordered" for equality comparisons.

Method Summary
  __init__(self, argumentList, argumentString, validate)
Initializes an options object.
  __repr__(self)
Official string representation for class instance.
  __str__(self)
Informal string representation for class instance.
  __cmp__(self, other)
Definition of equals operator for this class.
  buildArgumentList(self, validate)
Extracts options into a list of command line arguments.
  buildArgumentString(self, validate)
Extracts options into a string of command-line arguments.
  validate(self)
Validates command-line options represented by the object.
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value

Property Summary
  actions: Command-line actions list.
  config: Command-line configuration file (-c,--config) parameter.
  debug: Command-line debug (-d,--debug) flag.
  full: Command-line full-backup (-f,--full) flag.
  help: Command-line help (-h,--help) flag.
  logfile: Command-line logfile (-l,--logfile) parameter.
  mode: Command-line mode (-m,--mode) parameter.
  output: Command-line output (-O,--output) flag.
  owner: Command-line owner (-o,--owner) parameter, as tuple (user,group).
  quiet: Command-line quiet (-q,--quiet) flag.
  stacktrace: Command-line stacktrace (-s,--stack) flag.
  verbose: Command-line verbose (-b,--verbose) flag.
  version: Command-line version (-V,--version) flag.

Method Details

__init__(self, argumentList=None, argumentString=None, validate=True)
(Constructor)

Initializes an options object.

If you initialize the object without passing either argumentList or argumentString, the object will be empty and will be invalid until it is filled in properly.

No reference to the original arguments is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

The argument list is assumed to be a list of arguments, not including the name of the command, something like sys.argv[1:]. If you pass sys.argv instead, things are not going to work.

The argument string will be parsed into an argument list by the util.splitCommandLine function (see the documentation for that function for some important notes about its limitations). There is an assumption that the resulting list will be equivalent to sys.argv[1:], just like argumentList.

Unless the validate argument is False, the Options.validate method will be called (with its default arguments) after successfully parsing any passed-in command line. This validation ensures that appropriate actions, etc. have been specified. Keep in mind that even if validate is False, it might not be possible to parse the passed-in command line, so an exception might still be raised.
Parameters:
argumentList - Command line for a program.
           (type=List of arguments, i.e. sys.argv)
argumentString - Command line for a program.
           (type=String, i.e. "cback --verbose stage store")
validate - Validate the command line after parsing it.
           (type=Boolean true/false.)
Raises:
getopt.GetoptError - If the command-line arguments could not be parsed.
ValueError - If the command-line arguments are invalid.
Overrides:
__builtin__.object.__init__

Notes:

  • The command line format is specified by the _usage function. Call _usage to see a usage statement for the cback script.
  • It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to read in invalid command line arguments.

__repr__(self)
(Representation operator)

Official string representation for class instance.
Overrides:
__builtin__.object.__repr__

__str__(self)
(Informal representation operator)

Informal string representation for class instance.
Overrides:
__builtin__.object.__str__

__cmp__(self, other)
(Comparison operator)

Definition of equals operator for this class. Lists within this class are "unordered" for equality comparisons.
Parameters:
other - Other object to compare to.
Returns:
-1/0/1 depending on whether self is <, = or > other.

buildArgumentList(self, validate=True)

Extracts options into a list of command line arguments.

The original order of the various arguments (if, indeed, the object was initialized with a command-line) is not preserved in this generated argument list. Besides that, the argument list is normalized to use the long option names (i.e. --version rather than -V). The resulting list will be suitable for passing back to the constructor in the argumentList parameter. Unlike buildArgumentString, string arguments are not quoted here, because there is no need for it.

Unless the validate parameter is False, the Options.validate method will be called (with its default arguments) against the options before extracting the command line. If the options are not valid, then an argument list will not be extracted.
Parameters:
validate - Validate the options before extracting the command line.
           (type=Boolean true/false.)
Returns:
List representation of command-line arguments.
Raises:
ValueError - If options within the object are invalid.

Note: It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to extract an invalid command line.

buildArgumentString(self, validate=True)

Extracts options into a string of command-line arguments.

The original order of the various arguments (if, indeed, the object was initialized with a command-line) is not preserved in this generated argument string. Besides that, the argument string is normalized to use the long option names (i.e. --version rather than -V) and to quote all string arguments with double quotes ("). The resulting string will be suitable for passing back to the constructor in the argumentString parameter.

Unless the validate parameter is False, the Options.validate method will be called (with its default arguments) against the options before extracting the command line. If the options are not valid, then an argument string will not be extracted.
Parameters:
validate - Validate the options before extracting the command line.
           (type=Boolean true/false.)
Returns:
String representation of command-line arguments.
Raises:
ValueError - If options within the object are invalid.

Note: It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to extract an invalid command line.

validate(self)

Validates command-line options represented by the object.

Unless --help or --version are supplied, at least one action must be specified. Other validations (as for allowed values for particular options) will be taken care of at assignment time by the properties functionality.
Raises:
ValueError - If one of the validations fails.

Note: The command line format is specified by the _usage function. Call _usage to see a usage statement for the cback script.


Property Details

actions

Command-line actions list.

config

Command-line configuration file (-c,--config) parameter.

debug

Command-line debug (-d,--debug) flag.

full

Command-line full-backup (-f,--full) flag.

help

Command-line help (-h,--help) flag.

logfile

Command-line logfile (-l,--logfile) parameter.

mode

Command-line mode (-m,--mode) parameter.

output

Command-line output (-O,--output) flag.

owner

Command-line owner (-o,--owner) parameter, as tuple (user,group).

quiet

Command-line quiet (-q,--quiet) flag.

stacktrace

Command-line stacktrace (-s,--stack) flag.

verbose

Command-line verbose (-b,--verbose) flag.

version

Command-line version (-V,--version) flag.

Generated by Epydoc 2.1 on Mon Sep 4 13:49:33 2006 http://epydoc.sf.net