gerritssh.internal package

Submodules

gerritssh.internal.cmdoptions module

A set of cooperating classes which allow command implementations to specify and parse the various options which Gerrit supports.

In addition, every option can be assigned a semantic-version compatible specification which identifies the Gerrit versions on which the option is supported. Thus, a command implementation can not only parse its option list with ease, but also identify combinations which are not supported by the site they are being sent to.

Implementing a versioned command has the following requirements (see the ProjectList command for a full implementation).

• Create an OptionSet instance, specify all the supported options. This is best done as a class attribute, as the information is constant for all instances.
• Pass the OptionSet, and list of options to be parsed, to the constructor for the abstract SiteCommand class.
• When the execute_on method is invoked, call check_support_for() in the base class, which will verify all options (and the command itself) are supported in the Gerrit version for the given site.

A complete framework for a command implementation, supported on Gerrit versions 2.7 and above, might look like:

class SomeCommand(SiteCommand):

    __options = OptionSet(
                    Option.flag(...),
                    Option.choice(...),
                    Option.valued(...),
                    Option.flag('needed'))

    def __init__(self, options_string):
        super(SomeCommand,self).__init__('>=2.7',
                                         SomeCommand.__options,
                                         options_string)

    def execute_on(self, site):
        # We always need to specify --needed for some reason
        self.__parsed.needed = True

        # Check the support *after* overriding options
        self.check_support_for(site)

        return site.execute(' '.join(['some-command',
                                    self.__parsed]).strip())

class gerritssh.internal.cmdoptions.OptionSet(*args)

Bases: object

A set of options supported by a command.

Basically this is currently a wrapper around a tuple that allows for a natural form of creation. It also allows the representation to be changed later without producing widespread changes.

All arguments to the constructor need to be created by calls to the static methods of the Option class:

options = OptionSet(Option.flag(...),
                    Option.choice(...),
                    Option.valud(...),
                    ...)

Raises:TypeError if other types of arguments are created.

options_supported_in(version)

Return a subset of the OptionSet containing only those options supported by the provided version.

Parameters:version – A Version object from the semantic_version package. Returns:A filtered OptionSet Raises:TypeError if version is not a semantic_version.Version object

class gerritssh.internal.cmdoptions.Option

Bases: object

This class provides a namespace for static methods that create Option objects for inclusion in an Optionset.

Typically, these are used in initializing an OptionSet as follows:

OptionSet(Option.flag(...),
          Option.choices(...),
          Option.values(...))

flags, choices, and valued option definitions each take the following parameters:

Parameters:

• long_name – A string providing the long name for the option (without the leading ‘–’)
• short – A string providing the short name for the option (withoutthe leading ‘-‘). This defaults to None.
• repeatable – A boolean keyword argument, defaulting to False. If True, the option can be specified more than once (for example, ‘-vv’ to increase the level of verbosity twice)
• spec – A semantic_version compatible specification, defining which versions support this option. Defaults to ‘all versions’

The specific behavior of each is documented in the option creation methods.

static choice(long_name, short='', choices=, []**kwargs)

Define an option which requires a seleciton from a list of values.

Parameters:choices – A keyword argument providing the list of acceptable values.

The selected value is stored as an array if repeatable is True.

Example:

Option.choice('format', 'f', choices=['json', 'text', 'html'])

static flag(long_name, short='', **kwargs)

Create a simple flag option.

Flag options are either boolean, or repeatable.

If repeatable is True, the flags value will represent a count of how often it was found.

Examples:

# An option, '--long' or '-l', which is only supported in version
# 2.0.0 or better.
Option.flag('long', 'l', spec='>=2.0.0')

# An option '--verbose'or '-v' which can specified many times
Option.flag('--verbose','-v', repeatable=True)

static valued(long_name, short='', **kwargs)

Define an option which takes a value.

The value is stored as an array if repeatable is True.

Example:

Option.valued('project', 'p', repeatable=True, spec='>=1.2.3')

class gerritssh.internal.cmdoptions.CmdOptionParser(option_set)

Bases: object

A parser configured for a given OptionSet

Parameters:option_set – An initialized OptionSet instance Raises:TypeError if option_set is not an OptionSet

parse(opt_str)

Parse the provided option string.

Parameters:opt_str – A string containing the list of options to be parsed against the OptionSet the instiance was initialized with. Returns:A ParsedOptions object with the results of parsing the string

results

The ParsedOptions object from the last call to parse

Module contents