Clarify
=======
[](https://travis-ci.org/openelections/clarify)
[](https://codecov.io/gh/openelections/clarify)
A Python library to discover and parse results for jurisdictions that use election results reporting systems from [SOE Software](http://www.soesoftware.com/product/clarity-election-night-reporting/), a Florida-based company that offers its products under the "Clarity" name. Web sites using Clarity are recognizable by URLs that begin with "http://results.enr.clarityelections.com" and have zip files containing structured data in XML, CSV and XLS format.
Clarify offers an interface for discovering the locations of those zip files and another for parsing the XML versions of the data contained within them. Currently it does not handle downloading and unzipping those files, leaving that to the user.
Clarify is tested using Python 2.7, 3.4, 3.5, and 3.6.
Installation
-------------
Clarify can be installed using pip:
```
pip install clarify
```
Usage
-----
Election results sites running Clarity software offer detailed election results at the level of the political jurisdiction (for example, a state or county) and, optionally, sub-jurisdictions beneath that (counties and/or precincts). Clarify provides methods for discovering the URLs of structured data files and for parsing the XML versions of those files into Python objects.
### Jurisdiction
Clarify's `Jurisdiction` class provides details about the jurisdiction represented by a Clarity URL and the data available from that jurisdiction. To create an instance, pass in a Clarity results URL and the level of the jurisdiction ('state', 'county', or 'city'). The object then provides access to the detailed XML results for that jurisdiction:
```
>>> import clarify
>>> j = clarify.Jurisdiction(url='http://results.enr.clarityelections.com/GA/63991/184321/en/summary.html', level='state')
>>> j.report_url('xml')
'https://results.enr.clarityelections.com/GA/63991/184321/reports/detailxml.zip'
```
The `Jurisdiction` object also provides access to any sub-jurisdiction details, including the URL of the detailed XML results, by scraping the web pages listing them:
```
>>> subs = j.get_subjurisdictions()
>>> subs[0].name
'Baldwin'
>>> subs[0].report_url('xml')
'https://results.enr.clarityelections.com/GA/Baldwin/63997/183266/reports/detailxml.zip'
```
### Parser
Clarify's `Parser` class accepts a file or file-like object representing the unzipped election results file in XML format and parses it into Python objects containing details about specific elections (which are called contests in the schema) and results. The parser only handles the parsing of the XML into objects which make the election data easy to access. the user needs to handle the downloading and un-zipping portion of the workflow.
Create a new parser object and parser a results XML file:
```
>>> p = clarify.Parser()
>>> p.parse("path/to/detail.xml")
```
Once the ``parse()`` method has been called, the `Parser` object has properties that provide information about the election and jurisdiction of the results file:
```
>>> p.election_name
'2012 General Election'
>>> p.region
'Arkansas'
```
The parser object also has properties that provide lists of all contests, result jurisdictions and results.
A list of all contests:
```
>>> p.contests
[Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), Contest(key='0104', text='U.S. Congress District 1', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None)...]
```
A list of all sub-jurisdictions that have results:
```
>>> p.result_jurisdictions
[ResultJurisdiction(name='Gillett Ward 1', total_voters=121, ballots_cast=74, voter_turnout=61.16, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), ResultJurisdiction(name='Gillett Ward 2', total_voters=139, ballots_cast=111, voter_turnout=79.86, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'),...]
```
A list of all results, from all contests, from all sub-jurisdictions. This is useful if you want to transform all the results into another format:
```
>>> p.results[0:3]
[Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=None, votes=0, choice=None), Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=ResultJurisdiction(name='Gillett Ward 1', total_voters=121, ballots_cast=74, voter_turnout=61.16, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=0, choice=None), Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=ResultJurisdiction(name='Gillett Ward 2', total_voters=139, ballots_cast=111, voter_turnout=79.86, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=0, choice=None)]
```
`Parser` objects also have convenience methods for retrieving specific contests (`get_contest()`) and jurisdictions (`get_result_jurisdiction()`).
Get a `Contest` object for the presidential contest:
```
>>> contest = p.get_contest("U.S. President and Vice President")
>>> contest
Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None)
```
`Contest` objects provide access to both summary and detailed data about contests, including the vote 'choices' which can represent candidates or Yes/No types of questions.
```
>>> for c in contest.choices:
... print(c.text)
...
Gary Johnson / James P. Gray
Jill Stein / Cheri Honkala
Mitt Romney / Paul Ryan
Barack Obama / Joe Biden
Peta Lindsay / Yari Osorio
```
`Contest` objects also provide access to all the ``Result`` objects for the contest. A single `Result` object includes summary level information about the `ResultJurisdiction` (the precinct here), the contest and the choice. Clarify's object models attempt to match the original XML schema as closely as possible.
Get a single result for the contest:
```
>>> result = contest.results[450]
>>> result
Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='Election Day', jurisdiction=ResultJurisdiction(name='LaGrue', total_voters=531, ballots_cast=381, voter_turnout=71.75, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=32, choice=Choice(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), key='004', text='Barack Obama / Joe Biden', total_votes='2455'))
```
This result shows election day votes for Barack Obama in the 2012 presidential election in the LaGrue precinct in Arkansas County, Arkansas. These pieces of information are available as properties of the `Result` object.
Get the candidate name for the result:
```
>>> result.choice.text
'Barack Obama / Joe Biden'
```
Get the type of votes for this result:
```
>>> result.vote_type
'Election Day'
```
Get the name of the jurisdiction of this result:
```
>>> result.jurisdiction.name
'LaGrue'
```
Get the number of votes:
```
>>> result.votes
32
```
Running tests
-------------
```
python setup.py test
```
Issues
------
To report an bug or request a feature, please [create a new issue](https://github.com/openelections/clarify/issues) describing the situation, providing as much detail as possible. Bear in mind that we are using Clarify to load election results data as part of OpenElections and thus supporting states that use it likely will be the highest priority. We welcome contributions: feel free to fork the code and submit pull requests.
License
-------
Clarify is released under the MIT License.
Raw data
{
"_id": null,
"home_page": "http://openelections.net",
"name": "Clarify",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "elections,Clarity,results,parser,scraper",
"author": "OpenElections",
"author_email": "openelections@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9f/0e/59be2666c30b7905324adda276e7ec35b296d60211b706f16378d51bfccd/Clarify-0.5.1.tar.gz",
"platform": null,
"description": "Clarify\n=======\n\n[](https://travis-ci.org/openelections/clarify)\n[](https://codecov.io/gh/openelections/clarify)\n\nA Python library to discover and parse results for jurisdictions that use election results reporting systems from [SOE Software](http://www.soesoftware.com/product/clarity-election-night-reporting/), a Florida-based company that offers its products under the \"Clarity\" name. Web sites using Clarity are recognizable by URLs that begin with \"http://results.enr.clarityelections.com\" and have zip files containing structured data in XML, CSV and XLS format.\n\nClarify offers an interface for discovering the locations of those zip files and another for parsing the XML versions of the data contained within them. Currently it does not handle downloading and unzipping those files, leaving that to the user.\n\nClarify is tested using Python 2.7, 3.4, 3.5, and 3.6.\n\nInstallation\n-------------\n\nClarify can be installed using pip:\n\n```\npip install clarify\n```\n\nUsage\n-----\n\nElection results sites running Clarity software offer detailed election results at the level of the political jurisdiction (for example, a state or county) and, optionally, sub-jurisdictions beneath that (counties and/or precincts). Clarify provides methods for discovering the URLs of structured data files and for parsing the XML versions of those files into Python objects.\n\n### Jurisdiction\n\nClarify's `Jurisdiction` class provides details about the jurisdiction represented by a Clarity URL and the data available from that jurisdiction. To create an instance, pass in a Clarity results URL and the level of the jurisdiction ('state', 'county', or 'city'). The object then provides access to the detailed XML results for that jurisdiction:\n\n```\n>>> import clarify\n>>> j = clarify.Jurisdiction(url='http://results.enr.clarityelections.com/GA/63991/184321/en/summary.html', level='state')\n>>> j.report_url('xml')\n'https://results.enr.clarityelections.com/GA/63991/184321/reports/detailxml.zip'\n```\n\nThe `Jurisdiction` object also provides access to any sub-jurisdiction details, including the URL of the detailed XML results, by scraping the web pages listing them:\n\n```\n>>> subs = j.get_subjurisdictions()\n>>> subs[0].name\n'Baldwin'\n>>> subs[0].report_url('xml')\n'https://results.enr.clarityelections.com/GA/Baldwin/63997/183266/reports/detailxml.zip'\n```\n\n### Parser\n\nClarify's `Parser` class accepts a file or file-like object representing the unzipped election results file in XML format and parses it into Python objects containing details about specific elections (which are called contests in the schema) and results. The parser only handles the parsing of the XML into objects which make the election data easy to access. the user needs to handle the downloading and un-zipping portion of the workflow.\n\nCreate a new parser object and parser a results XML file:\n\n```\n>>> p = clarify.Parser()\n>>> p.parse(\"path/to/detail.xml\")\n```\n\nOnce the ``parse()`` method has been called, the `Parser` object has properties that provide information about the election and jurisdiction of the results file:\n\n```\n>>> p.election_name\n'2012 General Election'\n>>> p.region\n'Arkansas'\n```\n\nThe parser object also has properties that provide lists of all contests, result jurisdictions and results.\n\nA list of all contests:\n\n\n```\n>>> p.contests\n[Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), Contest(key='0104', text='U.S. Congress District 1', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None)...]\n```\n\nA list of all sub-jurisdictions that have results:\n\n```\n>>> p.result_jurisdictions\n[ResultJurisdiction(name='Gillett Ward 1', total_voters=121, ballots_cast=74, voter_turnout=61.16, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), ResultJurisdiction(name='Gillett Ward 2', total_voters=139, ballots_cast=111, voter_turnout=79.86, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'),...]\n```\n\nA list of all results, from all contests, from all sub-jurisdictions. This is useful if you want to transform all the results into another format:\n\n```\n>>> p.results[0:3]\n[Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=None, votes=0, choice=None), Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=ResultJurisdiction(name='Gillett Ward 1', total_voters=121, ballots_cast=74, voter_turnout=61.16, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=0, choice=None), Result(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='overVotes', jurisdiction=ResultJurisdiction(name='Gillett Ward 2', total_voters=139, ballots_cast=111, voter_turnout=79.86, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=0, choice=None)]\n```\n\n`Parser` objects also have convenience methods for retrieving specific contests (`get_contest()`) and jurisdictions (`get_result_jurisdiction()`).\n\nGet a `Contest` object for the presidential contest:\n\n```\n>>> contest = p.get_contest(\"U.S. President and Vice President\")\n>>> contest\nContest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None)\n```\n\n`Contest` objects provide access to both summary and detailed data about contests, including the vote 'choices' which can represent candidates or Yes/No types of questions.\n\n```\n>>> for c in contest.choices:\n... print(c.text)\n...\nGary Johnson / James P. Gray\nJill Stein / Cheri Honkala\nMitt Romney / Paul Ryan\nBarack Obama / Joe Biden\nPeta Lindsay / Yari Osorio\n```\n\n`Contest` objects also provide access to all the ``Result`` objects for the contest. A single `Result` object includes summary level information about the `ResultJurisdiction` (the precinct here), the contest and the choice. Clarify's object models attempt to match the original XML schema as closely as possible.\n\nGet a single result for the contest:\n\n```\n>>> result = contest.results[450]\n>>> result\nResult(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), vote_type='Election Day', jurisdiction=ResultJurisdiction(name='LaGrue', total_voters=531, ballots_cast=381, voter_turnout=71.75, percent_reporting=4.0, precincts_participating=None, precincts_reported=None, precincts_reporting_percent=None, level='precinct'), votes=32, choice=Choice(contest=Contest(key='0103', text='U.S. President and Vice President', vote_for=1, is_question=False, precincts_reporting=30, precincts_participating=None, precincts_reported=30, counties_participating=None, counties_reported=None), key='004', text='Barack Obama / Joe Biden', total_votes='2455'))\n```\n\nThis result shows election day votes for Barack Obama in the 2012 presidential election in the LaGrue precinct in Arkansas County, Arkansas. These pieces of information are available as properties of the `Result` object.\n\nGet the candidate name for the result:\n\n```\n>>> result.choice.text\n'Barack Obama / Joe Biden'\n```\n\nGet the type of votes for this result:\n\n```\n>>> result.vote_type\n'Election Day'\n```\n\nGet the name of the jurisdiction of this result:\n\n```\n>>> result.jurisdiction.name\n'LaGrue'\n```\n\nGet the number of votes:\n\n```\n>>> result.votes\n32\n```\n\nRunning tests\n-------------\n\n```\npython setup.py test\n```\n\nIssues\n------\n\nTo report an bug or request a feature, please [create a new issue](https://github.com/openelections/clarify/issues) describing the situation, providing as much detail as possible. Bear in mind that we are using Clarify to load election results data as part of OpenElections and thus supporting states that use it likely will be the highest priority. We welcome contributions: feel free to fork the code and submit pull requests.\n\nLicense\n-------\n\nClarify is released under the MIT License.\n",
"bugtrack_url": null,
"license": "",
"summary": "A library for scraping and parsing election results from jurisdictions using Clarity elections systems.",
"version": "0.5.1",
"split_keywords": [
"elections",
"clarity",
"results",
"parser",
"scraper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "677fdffbf3bca23f6c48618c627f1eacfb51d3b5aa288180b6b781d300229c3e",
"md5": "e4e0dc326befba960edc17290103970a",
"sha256": "bd84f2309e967ca5d5034d5a0193163e93256f3bc2223473edcef08b83b4bbc5"
},
"downloads": -1,
"filename": "Clarify-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4e0dc326befba960edc17290103970a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13380,
"upload_time": "2023-01-05T01:10:10",
"upload_time_iso_8601": "2023-01-05T01:10:10.494449Z",
"url": "https://files.pythonhosted.org/packages/67/7f/dffbf3bca23f6c48618c627f1eacfb51d3b5aa288180b6b781d300229c3e/Clarify-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f0e59be2666c30b7905324adda276e7ec35b296d60211b706f16378d51bfccd",
"md5": "df80b924a745918bb1190aff9a3f224d",
"sha256": "745a09a65c2c4b75280ad2d70194e8762fc3d947806a3a7d26dfedbc971e91d8"
},
"downloads": -1,
"filename": "Clarify-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "df80b924a745918bb1190aff9a3f224d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13788,
"upload_time": "2023-01-05T01:10:15",
"upload_time_iso_8601": "2023-01-05T01:10:15.315465Z",
"url": "https://files.pythonhosted.org/packages/9f/0e/59be2666c30b7905324adda276e7ec35b296d60211b706f16378d51bfccd/Clarify-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-05 01:10:15",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "clarify"
}
JSON