`r2b2.cli`¶

R2B2’s command line interface offers significant out-of-the-box functionality with respect to executing audits and generating audit data without requiring the user to write a single line of Python.

Note

Why does this file exist, and why not put this in __main__?

You might be tempted to import things from __main__ later, but that will cause problems: the code will get executed twice:

When you run python -m r2b2 python will execute __main__.py as a script. That means there won’t be any r2b2.__main__ in sys.modules.

When you import __main__ it will get executed again (as a module) because there’s no r2b2.__main__ in sys.modules.

Also see (1) from http://click.pocoo.org/5/setuptools/#setuptools-integration

Module Contents¶

class r2b2.cli.IntList[source]¶

Bases: click.ParamType

Represents the type of a parameter. Validates and converts values from the command line or Python into the correct type.

To implement a custom type, subclass and implement at least the following:

The name class attribute must be set.
Calling an instance of the type with None must return None. This is already implemented by default.
convert() must convert string values to the correct type.
convert() must accept values that are already the correct type.
It must be able to convert a value if the ctx and param arguments are None. This can occur when converting prompt input.

convert(self, value, param, ctx)[source]¶

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

to_info_dict(self) → Dict[str, Any]¶

Gather information that could be useful for a tool generating user-facing documentation.

Use click.Context.to_info_dict() to traverse the entire CLI structure.

New in version 8.0.

get_metavar(self, param: click.core.Parameter) → Optional[str]¶: Returns the metavar default for this param if it provides one.

get_missing_message(self, param: click.core.Parameter) → Optional[str]¶: Optionally might return extra information about a missing parameter.

New in version 2.0.

split_envvar_value(self, rv: str) → Sequence[str]¶

Given a value from an environment variable this splits it up into small chunks depending on the defined envvar list splitter.

If the splitter is set to None, which means that whitespace splits, then leading and trailing whitespace is ignored. Otherwise, leading and trailing splitters usually lead to empty items being included.

fail(self, message: str, param: Optional[click.core.Parameter] = None, ctx: Optional[click.core.Context] = None) → NoReturn¶: Helper method to fail with an invalid value message.

shell_complete(self, ctx: click.core.Context, param: click.core.Parameter, incomplete: str) → List[click.shell_completion.CompletionItem]¶

Return a list of CompletionItem objects for the incomplete value. Most types do not provide completions, but some do, and this allows custom types to provide custom completions as well.

Parameters

ctx – Invocation context for this command.
param – The parameter that is requesting completion.
incomplete – Value being completed. May be empty.

New in version 8.0.

r2b2.cli.interactive(election_mode, election_file, contest_file, audit_type, risk_limit, max_fraction_to_draw, verbose)¶

Executes an audit round by round.

Depending on what options are passed to the interactive command, users may be prompted for contest results, audit type, risk limit, and/or maximum fraction of contest ballots to draw when initializing the contest and audit to run.

During execution, users will enter each round size and results of the round’s sample and subsequently receive information about the current state of the audit. The process continues until either the stopping conditions are met or the audit reaches the maximum sample size.

For information on each option run

$ r2b2 interactive --help

Example

Contest results can be passed as a JSON file rather than entering the data through the prompt:

$ r2b2 interactive --contest-file example_contest.json

Tip

To generate a template contest JSON file run:

$ r2b2 template contest

Example

Audit parameters can be passed in as options rather than entering through the prompt:

$ r2b2 interactive --audit-type brla --risk-limit 0.1 --max-fraction-to-draw 0.2
$ r2b2 interactive -a brla -r 0.1 -m 0.2    // Shortened equivalent

Example

Election mode allows users to enter all the results from an election then select a contest from the election to audit:

$ r2b2 interactive -e
$ r2b2 interactive -e --election-file // pass election results as JSON file.

Warning

Election mode simply allows you to enter an entire election’s data, then select one one contest from that election to run. Auditing multiple contests from an election concurrently is not implemented.

r2b2.cli.bulk(audit_type, risk_limit, max_fraction_to_draw, contest_file, output, round_list, full_audit_limit, pair, verbose)¶

Bulk auditing mode generates stopping sizes for a given fixed round schedule.

Either provide a list of round sizes for which to generate stopping sizes or generate a ballot by ballot list of stopping sizes from the minimum valid sample size to the default maximum sample size or a specified maximum sample size.

Parameters

contest_file – Contest results as JSON file.
audit_type – Which audit type to use to generate stopping sizes.
risk_limit – Risk limit (alpha) of audit.
max_fraction_to_draw – Maximum fraction of contest ballots that could be drawm during the audit. Sets the default maximum size of the ballot by ballot output.

Tip

To generate a template contest JSON file, run:

$ r2b2 template contest

Returns: Formatted list of rounds and their associated stopping sizes. Default execution is ballot by ballot from minimum valid sample size to the maximum sample size of audit.

Example

To generate stopping sizes for a specific set of round sizes, provide the round sizes as a space separated list of integers enclosed by quotes using the round list option:

$ r2b2 bulk -l '100 200 300' contest.json brla 0.1 0.5

Example

To generate a ballot by ballot result from the minimum valid sample size to a specific maximum (i.e. not the maximum fraction to draw of the audit), run:

$ r2b2 bulk -f 221 contest.json brla 0.1 0.5

Example

To write the results to a file instead of to stdout, run:

$ r2b2 bulk -o output.txt contest.json brla 0.1 0.5

Tip

Generating large or compute heavy data sets can take some time. To estimate run times, use the verbose flag to display a progress bar:

$ r2b2 bulk -v contest.json brla 0.1 0.5

r2b2.cli.template(style, output)¶

Generate JSON templates for possible input formats.

Example

To create a contest results JSON file, first generate the template as a new JSON file:

$ r2b2 template -o my_contest.json contest

Now the file my_contest.json will be created and contain:

{
    "contest_ballots" : 100,
    "tally" : {
            "CandidateA" : 50,
            "CandidateB" : 50
    },
    "num_winners" : 1,
    "reported_winners" : ["CandidateA"],
    "contest_type" : "PLURALITY"
}

Simply repopulate the fields with your contest results.

r2b2.cli¶

Module Contents¶

`r2b2.cli`¶