Install the Python library:
pip install elex
Set your AP API key:
On Windows machines, use
Setx sets a permanent user level environment variable. To set a machine level variable use
- MongoDB (for recording raw results during tests and elections)
Install walkthrough with virtualenv¶
If you’ve set up and run Python projects before, you may have your own process, and the Quick Install instructions can get you going. But if you’re fairly new to Python development, or if you’re not familiar with the benefits of using a virtual environment, these tips are for you.
Set up some base tools¶
The NPR Visuals Team’s guide to setting up a development environment is wonderful. Walking through the entire guide is highly recommended; your machine will be much happier for it, and you’ll feel prepared for a lot of things beyond just Elex.
For now, though, the most important piece is “Chapter 2: Install Virtualenv.” At the very least, step through that section and install
virtualenvwrapper, two tools that help you use virtual environments for your Python projects.
Virtual environments let you compartmentalize projects and the Python tools you install to work on them. You can create as many virtual environments as you like. When you “activate” one of them, you can feel comfortable installing new libraries, because if things break, no problem. Delete that environment and start again; your global settings haven’t been touched. When you have things working just right, you can “freeze” the environment to create a list of installed packages so someone else can replicate it. Learning to love virtual environments makes you more efficient _and_ less stressed.
Once you’ve installed
virtualenvwrapper, then added the appropriate trigger to your
.bash_profile as described in the NPR Visuals guide, you’re ready to set up a pristine Elex environment.
virtualenvwrapper tool gives you access to several commands for creating and managing virtual environments. To create a fresh environment for Elex, run this from your command line:
Your new environment won’t know about or have access to any Python tools you’ve installed elsewhere, which is exactly what you want. The
mkvirtualenv command will automatically activate your new environment for you, and your command prompt should reflect it. You should see something like:
(elex) username@host: ~/your/path $
For reference, to turn off an active environment, run the
And to enable an environment, run
workon followed by the environment’s name:
With your new “elex” environment activated, installing the Elex library itself is easy:
pip install elex
That will download Elex and add it to your virtual environment, along with all the libraries it depends on. Just for fun, you can print to screen everything that was installed:
Now the Elex code will be available to you any time you activate your “elex” environment. You’ll still need a project API key to actually run commands, so with “elex” active, add the key you should have received from AP:
And with that in place, Elex should work as expected. You can test with any of the tutorial commands, like:
elex races 11-03-2015 -o json
Some extra tricks¶
Automatically set your API key¶
If you’ve followed the instructions above, you should already have your
AP_API_KEY set. When you
export a variable, however, it’s only available until your session ends. It’s tedious to set something like that manually every time you start a new project session, though. Thankfully
virtualenvwrapper provides an easy way to automatically load variables each time you activate an environment.
Open a new tab in your terminal, and:
workon elex cdvirtualenv open bin/postactivate
This will activate your “elex” environment, navigate to its internal directory on your machine, then use your text editor to open a file called
postactivate. Any code you put in this file will be run immediately after you activate that environment. So just add:
export AP_API_KEY=your_api_key_string echo "AP_API_KEY set"
Then save and close. From now on, every time you activate a new session of your “elex” environment, your API key will automatically be available (and you’ll get a little “AP_API_KEY set” reminder printed to screen).
Make human-readable JSON¶
You might notice that generating JSON with an Elex command like
elex races 11-03-2015 -o json will put all the results on one line. This is great for keeping file sizes smaller, and it’s perfectly readable by other machines. But if you’re trying to see what properties are available in the JSON generated by different Elex commands, it’s not particularly human-friendly. Fortunately, Elex provides a shortcut to display human-formatted json, the
elex races 11-03-2015 -o json --format-json
Or to save to a flat file you can inspect later:
elex races 11-03-2015 -o json --format-json > races.json