Command line interface (elex.cli)

elex.cli.app

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

alias of ElexBaseController

exit_on_close = True
extensions = ['elex.cli.ext_csv', 'elex.cli.ext_json']
handler_override_options = {'output': (['-o'], {'help': 'output format (default: csv)'})}
hooks = [('post_setup', <function cachecontrol_logging_hook at 0x7ff664c52378>), ('post_argument_parsing', <function add_election_hook at 0x7ff664c522f0>)]
label = 'elex'
log_handler = <cement.ext.ext_logging.LoggingLogHandler object>
output_handler = 'csv'
class elex.cli.app.ElexBaseController(*args, **kw)
class Meta
arguments = [(['date'], {'action': 'store', 'nargs': '*', '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.0\n'}), (['--results-level'], {'action': 'store', 'default': 'ru', 'help': 'Specify reporting level for results'}), (['--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.'})]
description = 'Get and process AP elections data'
label = 'base'
ElexBaseController.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
...                
ElexBaseController.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

Example output:

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
2919-polid-1445-None 2919 Caucus E 2 6527   0 2016-03-26   Bernie False True False Sanders 2016-03-27T03:03:54Z   True P President Dem 1445 4262 0 0.0 0     False     Alaska AK False False 0 0.0 False
2919-polid-1746-None 2919 Caucus E 1 6526   0 2016-03-26   Hillary False True False Clinton 2016-03-27T03:03:54Z   True P President Dem 1746 4261 0 0.0 0     False     Alaska AK False False 0 0.0 False

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,
    ...
);
ElexBaseController.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
...              
ElexBaseController.clear_cache()

elex clear-cache

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

Command:

elex clear-cache

Example output:

2016-09-30 00:22:56,992 (INFO) cement:app:elex : Clearing cache (/var/folders/z2/plxshs7c43lm_bctxn/Y/elex-cache)
2016-09-30 00:22:56,993 (INFO) cement:app:elex : Cache cleared.

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

ElexBaseController.default()
ElexBaseController.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
ElexBaseController.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
...      
ElexBaseController.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
ElexBaseController.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
ElexBaseController.next_election()

elex next-election <date-after> Returns data about the next election with an optional date to start searching. Command: .. code:: bash

elex next-election

Example output: .. csv-table:

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.: .. code:: bash

elex next-election 2016-04-15

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

ElexBaseController.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
...                                    
ElexBaseController.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

Example output:

id reportingunitid reportingunitname description electiondate fipscode initialization_data lastupdated level national officeid officename precinctsreporting precinctsreportingpct precinctstotal raceid racetype racetypeid seatname seatnum statename statepostal test uncontested votecount
state-1 state-1     2016-03-26   False 2016-03-27T03:03:54Z state True P President 40 1.0 40 2919 Caucus E     Alaska AK False False 539
county-2003 county-2003 State House District 1   2016-03-26   False 2016-03-27T03:03:54Z county True P President 1 1.0 1 2919 Caucus E       AK False False 12
county-2004 county-2004 State House District 2   2016-03-26   False 2016-03-27T03:03:54Z county True P President 1 1.0 1 2919 Caucus E       AK False False 6
...                                                
ElexBaseController.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  
...                                                                            
ElexBaseController.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
elex.cli.app.main()

elex.cli.decorators

elex.cli.decorators.require_ap_api_key(fn)

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

elex.cli.decorators.require_date_argument(fn)

Decorator that checks for date argument.

elex.cli.ext_csv

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

A custom CSV output handler

class Meta
label = 'csv'
overridable = True
CSVOutputHandler.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
ElexJSONOutputHandler.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.