PSPAW, an acronym for "Python StrawPoll API Wrapper", is a Python package that allows for simple access to StrawPoll's API. PSPAW aims to be as easy to use as possible and is developed based on official documentation found here. PSPAW does it's best to deal with deprecation, specifically relating to changes between the earlier polls and the newer ones.
- Python 2.7+ or Python 3.0+
- python-requests
A compatible version of python-requests
can be installed via $ pip install -r requirements.txt
.
PSPAW can be imported in a number of ways due to how the package is structued.
import pspaw
will allow PSPAW's main features to be accessed viapspaw.poll
from pspaw import poll
will allow PSPAW's main features to be accessed viapoll
For the sake of the usage guide we will be using import pspaw
.
In order to change the User-Agent that all requests are performed with, you must set the pspaw.poll.request.USERAGENT
variable to whatever you wish the User-Agent to be.
pspaw.poll.request.USERAGENT = "my app v1.0.0"
PSPAW's request
module handles all GET and POST requests performed to the API, and more specifically detects when an error is returned by the API. All errors the request
module detects will be raised as pspaw.errors.PSPAWBaseException
exceptions. The pspaw.errors.PSPAWBaseException
exception has two main important properties: code
and msg
. code
is the error-code returned by the API (if there is one), and msg
is the error string returned by the API.
>>> import pspaw
>>> try:
... p = pspaw.poll.get(-1)
... except pspaw.errors.PSPAWBaseException as e:
... print("Error #{}: {}".format(e.code, e.msg))
Error #41: Poll not found
Both getting and creating a poll will return a Poll
object. The Poll
object has the following properties:
- int
id
: ID of the poll. - str
title
: Title of the poll. - list
options
: Strings to represent the options for the poll. - list
votes
: Integers that correspond to the same indexed option which specify the current votes for that option. - dict
results
: A hashtable where the key is the poll's option and the value is the amount of votes for that option. - bool
multi
: Can the poll can accept multiple votes from one user? - bool
permissive
: Attempt to be more lenient in vote duplication checking? (DEPRECATED, used for detectingdupcheck
in earlier polls) - bool
captcha
: Does the poll require users to pass a CAPTCHA to vote? - str
dupcheck
: How to handle checking for duplicate votes {"normal", "permissive", "disabled"}
You can get percentage values of each vote using p.normalise()
, with an optional rounding
paramater which defaults to 2 decimal places.
You can fetch fresh voting values for the poll by using p.refresh()
.
>>> import pspaw
>>> p = pspaw.poll.get(1)
>>> p.id
1
>>> p.title
u'What movie should we watch'
>>> p.total_votes
64644
>>> p.results
{u'Witchhunter': 7928, u'Prison logic': 7008, u'Sucker punch ': 16425, u'Pirates of carribian ': 33283}
>>> p.normalise()
{u'Witchhunter': 12.26, u'Prison logic': 10.84, u'Sucker punch ': 25.41, u'Pirates of carribian ': 51.49}
>>> import pspaw
>>> p = pspaw.poll.create(title="Is PSPAW a cool project?", options=["Yes", "No"], multi=False, dupcheck="permissive", captcha=True)
>>> p.id
5941011