Command line interface (elex.cli)

elex.cli.app

class elex.cli.app.ElexBaseController(*args, **kw)
class Meta
label = 'base'
description = 'Get and process AP elections data'
arguments = [(['date'], {'nargs': '*', 'action': 'store', 'help': 'Election date (e.g. "2015-11-03"; most common date formats accepted).'}), (['-t', '--test'], {'action': 'store_true', 'help': 'Use testing API calls'}), (['-n', '--not-live'], {'action': 'store_true', 'help': 'Do not use live data API calls'}), (['-d', '--data-file'], {'action': 'store', 'help': 'Specify data file instead of making HTTP request when using election commands like `elex results` and `elex races`.'}), (['--delegate-sum-file'], {'action': 'store', 'help': 'Specify delegate sum report file instead of making HTTP request when using `elex delegates`'}), (['--delegate-super-file'], {'action': 'store', 'help': 'Specify delegate super report file instead of making HTTP request when using `elex delegates`'}), (['--trend-file'], {'action': 'store', 'help': 'Specify trend file instead of making HTTP request when when using `elex [gov/house/senate]-trends`'}), (['--format-json'], {'action': 'store_true', 'help': 'Pretty print JSON when using `-o json`.'}), (['-v', '--version'], {'action': 'version', 'version': '\nElex version 2.4.3\n'}), (['--results-level'], {'action': 'store', 'default': 'ru', 'help': 'Specify reporting level for results.'}), (['--officeids'], {'action': 'store', 'default': None, 'help': 'Specify officeids to parse.'}), (['--raceids'], {'action': 'store', 'default': [], 'help': 'Specify raceids to parse.'}), (['--set-zero-counts'], {'action': 'store_true', 'default': False, 'help': 'Override results with zeros; omits the winner indicator.Sets the vote, delegate, and reporting precinct counts to zero.'}), (['--national-only'], {'action': 'store_true', 'default': None, 'help': 'Limit results to national-level results only.'}), (['--local-only'], {'action': 'store_true', 'default': None, 'help': 'Limit results to local-level results only.'}), (['--with-timestamp'], {'action': 'store_true', 'help': 'Append a `timestamp` column to each row of data output with current system timestamp.'}), (['--batch-name'], {'action': 'store', 'help': 'Specify a value for a `batchname` column to append to each row.'})]
default()
races()

elex races <electiondate>

Returns race data for a given election date.

Command:

elex races 2016-03-26

Example output:

id raceid racetype racetypeid description electiondate initialization_data is_ballot_measure lastupdated national officeid officename party seatname seatnum statename statepostal test uncontested
2919 2919 Caucus E   2016-03-26 True False 2016-03-27T03:03:54Z True P President Dem       AK False False
12975 12975 Caucus E   2016-03-26 True False 2016-03-29T17:17:41Z True P President Dem       HI False False
                                   
reporting_units()

elex reporting-units <electiondate>

Returns reporting unit data for a given election date.

Reporting units represent geographic aggregation of voting data at the national, state, county, and district level.

Command:

elex reporting-units 2016-03-26
candidate_reporting_units()

elex candidate-reporting-units <electiondate>

Returns candidate reporting unit data for a given election date.

A candidate reporting unit is a container for the results of a voting in a specific reporting unit. This command is a close cousin of elex results <electiondate>.

This command does not return results.

Command:

elex candidate-reporting-units 2016-03-26

Notes:

This command can be used to quickly create schemas.

pip install csvkit
elex candidate-reporting-units 03-26-16 | csvsql -i mysql

Will output:

CREATE TABLE stdin (
    id VARCHAR(23) NOT NULL,
    raceid INTEGER NOT NULL,
    racetype VARCHAR(6) NOT NULL,
    racetypeid VARCHAR(1) NOT NULL,
    ...
);
candidates()

elex candidates <electiondate>

Returns candidate data for a given election date.

Command:

elex candidates 2016-03-26

Example output:

id candidateid ballotorder first last party polid polnum
polid-1445 6527 2 Bernie Sanders Dem 1445 4262
polid-1746 6526 1 Hillary Clinton Dem 1746 4261
             
ballot_measures()

elex ballot-measures <electiondate>

Returns ballot measure data for a given election date.

Command:

elex ballot-measures 2016-03-15

Example output:

id candidateid ballotorder description electiondate last polid polnum seatname
2016-03-15-43697 43697 1   2016-03-15 For   37229 Public Improvement Bonds
2016-03-15-43698 43698 2   2016-03-15 Against   37230 Public Improvement Bonds
               
results()

elex results <electiondate>

Returns result data.

Each row in the output represents a fully flattened and denormalized version of a result for specific candidate in a specific race.

Command:

elex results 2016-03-01

Example output:

id unique_id raceid racetype racetypeid ballotorder candidateid description delegatecount electiondate fipscode first incumbent initialization_data is_ballot_measure last lastupdated level national officeid officename party polid polnum precinctsreporting precinctsreportingpct precinctstotal reportingunitid reportingunitname runoff seatname seatnum statename statepostal test uncontested votecount votepct winner
3021-polid-61815-state-1 3021 Caucus S 2 6528   0 2016-03-01   Ted False False False Cruz 2016-03-02T17:05:46Z state True P President GOP 61815 4263 72 1.0 72 state-1   False     Alaska AK False False 7973 0.363566 True  
3021-polid-8639-state-1 3021 Caucus S 5 6548   0 2016-03-01   Donald False False False Trump 2016-03-02T17:05:46Z state True P President GOP 8639 4273 72 1.0 72 state-1   False     Alaska AK False False 7346 0.334975 False  
                                                                           
elections()

elex elections

Returns all elections known to the API.

Command:

elex elections

Example output:

2016-02-09 2016-02-09 True False
2016-02-16 2016-02-16 True False
     
delegates()

elex delegates

Returns delegate report data.

Command:

elex delegates

Example output:

level party_total superdelegates_count last state candidateid party_need party delegates_count id d1 d7 d30
state 2472 0 Bush MN 1239 1237 GOP 0 MN-1239 0 0 0
state 2472 0 Bush OR 1239 1237 GOP 0 OR-1239 0 0 0
governor_trends()

elex governor-trends

Governor balance of power/trend report.

Command:

elex governor-trends

Example output:

party office won leading holdovers winning_trend current insufficient_vote net_winners net_leaders
Dem Governor 7 7 12 19 20 0 -1 0
house_trends()

elex house-trends

House balance of power/trend report.

Command:

elex house-trends

Example output:

party office won leading holdovers winning_trend current insufficient_vote net_winners net_leaders
Dem U.S. House 201 201 0 201 193 0 +8 0
senate_trends()

elex senate-trends

Senate balance of power/trend report.

Command:

elex senate-trends

Example output:

party office won leading holdovers winning_trend current insufficient_vote net_winners net_leaders
Dem U.S. Senate 23 23 30 53 51 0 +2 0
next_election()

elex next-election <date-after>

Returns data about the next election with an optional date to start searching.

Command:

elex next-election

Example output:

id electiondate liveresults testresults
2016-04-19 2016-04-19 False True

You can also specify the date to find the next election after, e.g.:

elex next-election 2016-04-15

This will find the first election after April 15, 2016.

clear_cache()

elex clear-cache

Returns data about the next election with an optional date to start searching.

Command:

elex clear-cache

If no cache entries exist, elex will close with exit code 65.

class elex.cli.app.ElexApp(label=None, **kw)
class Meta
label = 'elex'
base_controller

alias of ElexBaseController

exit_on_close = True
hooks = [('post_setup', <function cachecontrol_logging_hook>), ('post_argument_parsing', <function add_election_hook>)]
extensions = ['elex.cli.ext_csv', 'elex.cli.ext_json']
output_handler = 'csv'
handler_override_options = {'output': (['-o'], {'help': 'output format (default: csv)'})}
log_handler = <cement.ext.ext_logging.LoggingLogHandler object>
elex.cli.app.main()

elex.cli.decorators

elex.cli.decorators.require_date_argument(fn)

Decorator that checks for date argument.

elex.cli.decorators.require_ap_api_key(fn)

Decorator that checks for Associated Press API key or data-file argument.

elex.cli.ext_csv

class elex.cli.ext_csv.CSVOutputHandler(*args, **kw)

A custom CSV output handler

class Meta
label = 'csv'
overridable = True
render(data, template=None)
elex.cli.ext_csv.load(app)

elex.cli.ext_json

class elex.cli.ext_json.ElexJSONOutputHandler(*args, **kw)

A custom JSON output handler

class Meta
label = 'json'
overridable = True
render(data, template=None)
elex.cli.ext_json.load(app)

elex.cli.hooks

elex.cli.hooks.add_election_hook(app)

Cache election API object reference after parsing args.

elex.cli.hooks.cachecontrol_logging_hook(app)

Reroute cachecontrol logger to use cement log handlers.

elex.cli.utils

elex.cli.utils.parse_date(datestring)

Parse many date formats into an AP friendly format.