Package: ballotbox
ContentsIntroductionInstallationUsageTODOChangesIntroductionAbout ballotboxballotbox is a Python library that attempts to implement useful voting
methodologies.This project started as a result of conversations and experimentation that took
place on the ULS-SIG when discussing self-organizing object meshes.DependenciesThe current implementation depends upon the following additional software
and/or libraries:Pythonzope.interfacesphinxrepoze.sphinx.autointerfaceAdditional InformationFor information on the following, please see the sections (or, if reading
this file in a working directory, the ./docs subdir):InstallationUsageInstallationDevelopmentIf you want to develop for ballotbox or use the latest code we’re working on,
you can install from the sources. You’ll need bzr installed, and then just do
the following:$ bzr branch lp:ballotbox
$ cd ballotbox
$ sudo python setup.py installEasy InstallYou can use the setuptools easy_install script to get ballotbox on your
system:$ sudo easy_install ballotboxManual DownloadYou can manually download the source tarball from the Python Package Index by
visiting the following URL:http://pypi.python.org/pypi/ballotboxYou’ll need to untar and gunzip the source, cd into the source directory, and
then you can do the usual:$ sudo python setup.py installChecking the SourceOnce installed, as long as you have Twisted installed on your system and the
trial script in your PATH, you can test the source code by executing this
anywhere:$ trial ballotboxThat will run the test suite and report on the success and failure of any unit
tests.UsageBelow is a quick introduction to the usage of the API. The voting method used
in this example is simple majority.  Simple majority rule voting is mostly
useful for binary decisions. Here are some examples involving just two
choices:>>> from ballotbox.ballot import BallotBox
>>> from ballotbox.singlewinner.simple import MajorityRuleVoting

>>> bb = BallotBox(method=MajorityRuleVoting)
>>> bb.batch_votes([("alice", 10000), ("bob", 5000)])
>>> bb.get_winner()
[(10000, 'alice')]

>>> bb = BallotBox(method=MajorityRuleVoting)
>>> bb.batch_votes([("bob", 5000), ("carol", 5001)])
>>> bb.get_winner()
[(5001, 'carol')]This method breaks down with ties and is not guaranteed to work with more than
two choices:>>> bb = BallotBox(method=MajorityRuleVoting)
>>> bb.batch_votes([("alice", 8000), ("carol", 8000)])
>>> bb.get_winner()
[]No result is returned. Likewise for edge cases with more than two candidates:>>> bb = BallotBox(method=MajorityRuleVoting)
>>> bb.batch_votes([("alice", 5000), ("bob", 4000), ("carol", 3000)])
>>> bb.get_winner()
[]TODOImplementation[DONE] Convert the criteria classes to use interfaces. Then, instead of
subclassing these in the voting methods, they would implement them. This will
make zope.interface a dependency.[DONE] Copy multi-doctest file test suite code from txULS/soom to here.[DONE] Add a new docs/methods directory and a file for each voting method.[IN PROGRESS] Finish implementing the single-winner voting methods.Implement the Multi-winner voting methods.Implement the proxy and random voting methods.Do research on distance-based voting:in particular, defining a metric space for candidates based on a set of
preferencesthen taking the square root of the sum of the squares, getting the
n-dimensional distanceTesting[IN PROGRESS] Add doctests for each voting method.Add a make target that tests the source dist:create a temp diruntar the dist thererun the unit tests and doctests against that directoryDocumentationChange uppercase doc files to lower case (with the exceptions of the
standard ones like README, TODO, etc.)Updated the sphinx configuration file to use ballotbox.metaAdd sidebar links in the generated docsAutogenerate ReST files for API docsthe logic that drives this should go in ballotbox.util.docsadd a make target that imports and calls the appropriate functions to
generate the API docsChangesVersion 0.1Initial release of ballotbox.