CedarBackup2.tools.amazons3.Options

Package CedarBackup2 :: Package tools :: Module amazons3 :: Class Options |
[hide private]
[frames] | no frames]

# Class Options

source code

    object --+
             |
            Options

Class representing command-line options for the cback-amazons3-sync 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.

Instance Methods | [hide private]
__init__(self, argumentList=None, argumentString=None, validate=True) Initializes an options object. | source code
__repr__(self) Official string representation for class instance. | source code
__str__(self) Informal string representation for class instance. | source code
__cmp__(self, other) Definition of equals operator for this class. | source code
_setHelp(self, value) Property target used to set the help flag. | source code
_getHelp(self) Property target used to get the help flag. | source code
_setVersion(self, value) Property target used to set the version flag. | source code
_getVersion(self) Property target used to get the version flag. | source code
_setVerbose(self, value) Property target used to set the verbose flag. | source code
_getVerbose(self) Property target used to get the verbose flag. | source code
_setQuiet(self, value) Property target used to set the quiet flag. | source code
_getQuiet(self) Property target used to get the quiet flag. | source code
_setLogfile(self, value) Property target used to set the logfile parameter. | source code
_getLogfile(self) Property target used to get the logfile parameter. | source code
_setOwner(self, value) Property target used to set the owner parameter. | source code
_getOwner(self) Property target used to get the owner parameter. | source code
_setMode(self, value) Property target used to set the mode parameter. | source code
_getMode(self) Property target used to get the mode parameter. | source code
_setOutput(self, value) Property target used to set the output flag. | source code
_getOutput(self) Property target used to get the output flag. | source code
_setDebug(self, value) Property target used to set the debug flag. | source code
_getDebug(self) Property target used to get the debug flag. | source code
_setStacktrace(self, value) Property target used to set the stacktrace flag. | source code
_getStacktrace(self) Property target used to get the stacktrace flag. | source code
_setDiagnostics(self, value) Property target used to set the diagnostics flag. | source code
_getDiagnostics(self) Property target used to get the diagnostics flag. | source code
_setVerifyOnly(self, value) Property target used to set the verifyOnly flag. | source code
_getVerifyOnly(self) Property target used to get the verifyOnly flag. | source code
_setIgnoreWarnings(self, value) Property target used to set the ignoreWarnings flag. | source code
_getIgnoreWarnings(self) Property target used to get the ignoreWarnings flag. | source code
_setSourceDir(self, value) Property target used to set the sourceDir parameter. | source code
_getSourceDir(self) Property target used to get the sourceDir parameter. | source code
_setS3BucketUrl(self, value) Property target used to set the s3BucketUrl parameter. | source code
_getS3BucketUrl(self) Property target used to get the s3BucketUrl parameter. | source code
validate(self) Validates command-line options represented by the object. | source code
buildArgumentList(self, validate=True) Extracts options into a list of command line arguments. | source code
buildArgumentString(self, validate=True) Extracts options into a string of command-line arguments. | source code
_parseArgumentList(self, argumentList) Internal method to parse a list of command-line arguments. | source code
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties | [hide private]
| help Command-line help (`-h,--help`) flag.
| version Command-line version (`-V,--version`) flag.
| verbose Command-line verbose (`-b,--verbose`) flag.
| quiet Command-line quiet (`-q,--quiet`) flag.
| logfile Command-line logfile (`-l,--logfile`) parameter.
| owner Command-line owner (`-o,--owner`) parameter, as tuple `(user,group)`.
| mode Command-line mode (`-m,--mode`) parameter.
| output Command-line output (`-O,--output`) flag.
| debug Command-line debug (`-d,--debug`) flag.
| stacktrace Command-line stacktrace (`-s,--stack`) flag.
| diagnostics Command-line diagnostics (`-D,--diagnostics`) flag.
| verifyOnly Command-line verifyOnly (`-v,--verifyOnly`) flag.
| ignoreWarnings Command-line ignoreWarnings (`-w,--ignoreWarnings`) flag.
| sourceDir Command-line sourceDir, source of sync.
| s3BucketUrl Command-line s3BucketUrl, target of sync.
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, argumentList=None, argumentString=None, validate=True) (Constructor) | source code
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` (List of arguments, i.e. `sys.argv`) - Command line for a program. `argumentString` (String, i.e. "cback --verbose stage store") - Command line for a program. `validate` (Boolean true/false.) - Validate the command line after parsing it. Raises: `getopt.GetoptError` - If the command-line arguments could not be parsed. `ValueError` - If the command-line arguments are invalid. Overrides: 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) | source code
Official string representation for class instance. Overrides: object.__repr__

### __str__(self) (Informal representation operator) | source code
Informal string representation for class instance. Overrides: object.__str__

### __cmp__(self, other) (Comparison operator) | source code
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.

### _setHelp(self, value) | source code
Property target used to set the help flag. No validations, but we normalize the value to `True` or `False`.

### _setVersion(self, value) | source code
Property target used to set the version flag. No validations, but we normalize the value to `True` or `False`.

### _setVerbose(self, value) | source code
Property target used to set the verbose flag. No validations, but we normalize the value to `True` or `False`.

### _setQuiet(self, value) | source code
Property target used to set the quiet flag. No validations, but we normalize the value to `True` or `False`.

### _setLogfile(self, value) | source code
Property target used to set the logfile parameter. Raises: `ValueError` - If the value cannot be encoded properly.

### _setOwner(self, value) | source code
Property target used to set the owner parameter. If not `None`, the owner must be a `(user,group)` tuple or list. Strings (and inherited children of strings) are explicitly disallowed. The value will be normalized to a tuple. Raises: `ValueError` - If the value is not valid.

### _getOwner(self) | source code
Property target used to get the owner parameter. The parameter is a tuple of `(user, group)`.

### _setOutput(self, value) | source code
Property target used to set the output flag. No validations, but we normalize the value to `True` or `False`.

### _setDebug(self, value) | source code
Property target used to set the debug flag. No validations, but we normalize the value to `True` or `False`.

### _setStacktrace(self, value) | source code
Property target used to set the stacktrace flag. No validations, but we normalize the value to `True` or `False`.

### _setDiagnostics(self, value) | source code
Property target used to set the diagnostics flag. No validations, but we normalize the value to `True` or `False`.

### _setVerifyOnly(self, value) | source code
Property target used to set the verifyOnly flag. No validations, but we normalize the value to `True` or `False`.

### _setIgnoreWarnings(self, value) | source code
Property target used to set the ignoreWarnings flag. No validations, but we normalize the value to `True` or `False`.

### validate(self) | source code
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.

### buildArgumentList(self, validate=True) | source code
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` (Boolean true/false.) - Validate the options before extracting the command line. 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) | source code
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` (Boolean true/false.) - Validate the options before extracting the command line. 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.

### _parseArgumentList(self, argumentList) | source code
Internal method to parse a list of command-line arguments. Most of the validation we do here has to do with whether the arguments can be parsed and whether any values which exist are valid. We don't do any validation as to whether required elements exist or whether elements exist in the proper combination (instead, that's the job of the validate method). For any of the options which supply parameters, if the option is duplicated with long and short switches (i.e. `-l` and a `--logfile`) then the long switch is used. If the same option is duplicated with the same switch (long or short), then the last entry on the command line is used. Parameters: `argumentList` (List of arguments to a command, i.e. `sys.argv[1:]`) - List of arguments to a command. Raises: `ValueError` - If the argument list cannot be successfully parsed.

Property Details | [hide private]

### help Command-line help (`-h,--help`) flag. Get Method: _getHelp(self) - Property target used to get the help flag. Set Method: _setHelp(self, value) - Property target used to set the help flag.

### version Command-line version (`-V,--version`) flag. Get Method: _getVersion(self) - Property target used to get the version flag. Set Method: _setVersion(self, value) - Property target used to set the version flag.

### verbose Command-line verbose (`-b,--verbose`) flag. Get Method: _getVerbose(self) - Property target used to get the verbose flag. Set Method: _setVerbose(self, value) - Property target used to set the verbose flag.

### quiet Command-line quiet (`-q,--quiet`) flag. Get Method: _getQuiet(self) - Property target used to get the quiet flag. Set Method: _setQuiet(self, value) - Property target used to set the quiet flag.

### logfile Command-line logfile (`-l,--logfile`) parameter. Get Method: _getLogfile(self) - Property target used to get the logfile parameter. Set Method: _setLogfile(self, value) - Property target used to set the logfile parameter.

### owner Command-line owner (`-o,--owner`) parameter, as tuple `(user,group)`. Get Method: _getOwner(self) - Property target used to get the owner parameter. Set Method: _setOwner(self, value) - Property target used to set the owner parameter.

### mode Command-line mode (`-m,--mode`) parameter. Get Method: _getMode(self) - Property target used to get the mode parameter. Set Method: _setMode(self, value) - Property target used to set the mode parameter.

### output Command-line output (`-O,--output`) flag. Get Method: _getOutput(self) - Property target used to get the output flag. Set Method: _setOutput(self, value) - Property target used to set the output flag.

### debug Command-line debug (`-d,--debug`) flag. Get Method: _getDebug(self) - Property target used to get the debug flag. Set Method: _setDebug(self, value) - Property target used to set the debug flag.

### stacktrace Command-line stacktrace (`-s,--stack`) flag. Get Method: _getStacktrace(self) - Property target used to get the stacktrace flag. Set Method: _setStacktrace(self, value) - Property target used to set the stacktrace flag.

### diagnostics Command-line diagnostics (`-D,--diagnostics`) flag. Get Method: _getDiagnostics(self) - Property target used to get the diagnostics flag. Set Method: _setDiagnostics(self, value) - Property target used to set the diagnostics flag.

### verifyOnly Command-line verifyOnly (`-v,--verifyOnly`) flag. Get Method: _getVerifyOnly(self) - Property target used to get the verifyOnly flag. Set Method: _setVerifyOnly(self, value) - Property target used to set the verifyOnly flag.

### ignoreWarnings Command-line ignoreWarnings (`-w,--ignoreWarnings`) flag. Get Method: _getIgnoreWarnings(self) - Property target used to get the ignoreWarnings flag. Set Method: _setIgnoreWarnings(self, value) - Property target used to set the ignoreWarnings flag.

### sourceDir Command-line sourceDir, source of sync. Get Method: _getSourceDir(self) - Property target used to get the sourceDir parameter. Set Method: _setSourceDir(self, value) - Property target used to set the sourceDir parameter.

### s3BucketUrl Command-line s3BucketUrl, target of sync. Get Method: _getS3BucketUrl(self) - Property target used to get the s3BucketUrl parameter. Set Method: _setS3BucketUrl(self, value) - Property target used to set the s3BucketUrl parameter.