Skip to main content

A Python library for voting algorithms.

Project description

Introduction

About ballotbox

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

Dependencies

The current implementation depends upon the following additional software and/or libraries:

  • Python

  • zope.interface

  • sphinx

  • repoze.sphinx.autointerface

Additional Information

For information on the following, please see the sections (or, if reading this file in a working directory, the ./docs subdir):

  • Installation

  • Usage

Installation

Development

If 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 install

Easy Install

You can use the setuptools easy_install script to get ballotbox on your system:

$ sudo easy_install ballotbox

Manual Download

You can manually download the source tarball from the Python Package Index by visiting the following URL:

http://pypi.python.org/pypi/ballotbox

You’ll need to untar and gunzip the source, cd into the source directory, and then you can do the usual:

$ sudo python setup.py install

Checking the Source

Once 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 ballotbox

That will run the test suite and report on the success and failure of any unit tests.

Usage

Below 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()
[]

TODO

Implementation

[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 preferences

  • then taking the square root of the sum of the squares, getting the n-dimensional distance

Testing

[IN PROGRESS] Add doctests for each voting method.

Add a make target that tests the source dist:

  • create a temp dir

  • untar the dist there

  • run the unit tests and doctests against that directory

Documentation

  • Change 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.meta

  • Add sidebar links in the generated docs

  • Autogenerate ReST files for API docs

    • the logic that drives this should go in ballotbox.util.docs

    • add a make target that imports and calls the appropriate functions to generate the API docs

Changes

Version 0.1

  • Initial release of ballotbox.

Project details


Release history Release notifications | RSS feed

This version

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ballotbox-0.1.tar.gz (42.5 kB view details)

Uploaded Source

File details

Details for the file ballotbox-0.1.tar.gz.

File metadata

  • Download URL: ballotbox-0.1.tar.gz
  • Upload date:
  • Size: 42.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for ballotbox-0.1.tar.gz
Algorithm Hash digest
SHA256 6efa54b7b6d67dea9b2637d34a145ef164777524edac21b3aa6f509087586e3f
MD5 99fb47891f0e64dd0f5336ef0c742b2b
BLAKE2b-256 e31a430831f2c991f26d76eb4d4780eb23a82735cce4a6572d96db52ec8979db

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page