#!/usr/bin/python
"""
=====================================================================
PyLotto: select students of a class at random to receive copies
of a book, working around various security constraints. I use
this to give away free copies of my Python books in some of the
classes I teach.
In order to work around the security restrictions at some sites,
this script tries to be general. It can run the lottery in 3
different modes, selected by command-line arguments in local
console mode, or by URL query parameters in remote web mode:
1) to select from emails,
2) to select from names in a file created by web page submits,
3) to select from names typed into a local text file manually.
Accordingly, students enter the lottery in 1 of 3 specific ways,
depending on security at a given site; by:
(1) Sending an email message to "PP4E@learning-python.com" with
subject "PYLOTTO" and their From address.
(2) Submitting the form at "http://learning-python.com/pylotto.html"
with their name, which adds them to a file on a remote web server
(an equivalent GET-style URL described ahead does the same work).
(3) Appearing in a manually-created text file of names on the script's
own machine named "pylotto-players.txt" (physically, the script
and file may be local, or remote via SSH).
Winners are then picked at random from all players, by either scanning
the email inbox and parsing emails, or reading the names file created
manually or by the web page submits. Results can be displayed in
console text or CGI web reply page format.
In a bit more detail, the lottery script itself may be pysically run:
--in a local console to select from emails, if POP access is supported
at the site;
--remotely on the web as a CGI script to select from emails or a file,
if only HTTP web access is available;
--in a local console to select from a local file if neither web
nor email are allowed.
These contexts translate to selection and display modes configured by
command-line options:
"pylotto.py -show console -find email" --runs locally from emails
"pylotto.py -show cgi -find email" --runs remotely from emails
"pylotto.py -show cgi -find file" --runs remotely from a file
"pylotto.py -show console -find file" --runs locally from a file
"pylotto.py -form player" --adds player name to file
As described ahead, in remote CGI web mode, equivalent query parameters
in GET-style URLs are simply translated to command-lines:
"http://learning-python.com/cgi/pylotto.py?-show=console&-find=email"
"http://learning-python.com/cgi/pylotto.py?-show=cgi&-find=file"
"http://learning-python.com/cgi/pylotto.py?-form=player"
To enable CGI usage modes, set the script's "RunAsCGI" variable to True
when installing. A variety of admin and test modes are also available;
see this script's __main__ logic for more details.
See Chapter 13 for more on email tools, Chapter 15 for more on CGI
concepts, and Part 2 for hints on adding a tkinter GUI for sign-up
or reporting (I've already worked on this more than I intended to!).
---------------------------------------------------------------------
NEW: CGI and local file modes
Because the original email sign-up scheme requires email access
which is not always available at client sites, I've completely
rewritten this script to also select from a flat file of names,
which may be created by either web form submits or by manual edits.
This script can now be run locally or remotely, and as both a
command-line script or a CGI script via a web URL.
In fact, it can now run locally on a local file as a last resort:
some pathologically secure sites may disallow instructor email
access, but also student email sends, and even student web form
submits. In the worst case, names are typed into and selected
from a simple text file. Command-line arguments configure the
script to select from either a file or emails, and to display
its results in either console or CGI web reply format.
In CGI mode, this script can be run both to sign-up players, and
to run its lottery logic. In both roles, its URL may be run from
a web page form's action, manually typed in a web browser, sent
with Python's urllib in a script, and so on. For instance, to
run the lottery in CGI mode, a URL of the following form is
submitted by the instructor (only! -- this would work if run
by students, but the results it reports to them are not used):
http://learning-python.com/cgi/pylotto.py?-show=cgi&-find=file
and submitting the "pylotto.html" form to sign up players is
equivalent to sending a GET-style URL like the following:
http://learning-python.com/cgi/pylotto.py?-form=playername
These URL invocation forms also have command-line equivalents when
run in a local console (as discussed ahead, queries map to these,
which can also be run from a console window to test):
pylotto.py -show cgi -find file
pylotto.py -form playername
A simple flat file is used to record sign-ups, with locks to
handle possibly concurrent updates to the players file.
---------------------------------------------------------------------
NEW: 2.X/3.X portability:
The original CGI option assumed your web server ran Python 3.X
and a separate 2.X version was coded. I've also now updated this
single script to run under either 3.X, or 2.X for older installs
(search for "OnPython3" to see the mods). My ISP account is still
running Python 2.4 for default accounts (!). Portability impacted
print operations, Unicode decoding of email text for 3.1 parsing,
encoding to bytes for os.write, shiny new tools like sys.version_info
field names that aren't backward compatible, and some library module
imports (e.g., 3.X's email.*, io.*).
---------------------------------------------------------------------
NEW: use cgi.escape() for player names in CGI mode:
Crucially, the script also now runs player names through the
cgi.escape() call when in CGI display mode, else the "<..>"
brackets in emails can throw its results diplay off: player
email address could be truncated in the reply page.
---------------------------------------------------------------------
NEW: translating query parameters to command-lines in CGI mode
When run in CGI mode, the script now translates query parameters
to command-line arguments, for compatibility with console usage
mode. For instance, the invocation URLs:
http://www.learning-python.com/cgi/pylotto.py?-show=cgi&-find=file
http://www.learning-python.com/cgi/pylotto.py?-show=console&-find=email
http://www.learning-python.com/cgi/pylotto.py?-form=playername
http://www.learning-python.com/cgi/pylotto.py?-reset=1
are translated into the following equivalent command-lines when
they reach the web server and CGI script:
pylotto.py -show cgi -find file # pick from file, show HTML
pylotto.py -show console -find email # pick emails, show text [1]
pylotto.py -form playername # sign-up a player
pylotto.py -reset 1 # '1' is ignored here
Per the CGI spec, some web servers might pass through command-line
arguments automatically when the query sting (after the "?") does
not contain an "=" character (e.g, "pylotto.py?-reset"), but the
server at my ISP does not: it simply adds all text after "?" to
the query-string value. Run calls to cgi.print_arguments() and
cgi.print_environ() to see how your server fares; on mine, all
text after '?' always appears in QUERY_STRING, not on sys.argv.
Could instead have two top-level __main__ scripts for console/web
with a common module, but that seems prone to redundancy problems.
[1] Footnote: as implied by these URLs, you can show results in either
cgi (HTML text) or console (plain text) form when running in remote
CGI mode with script variable RunAsCGI == True; this mode prints the
required CGI header lines and performs query-string -> command-line
translation. However, player names are CGI-escaped only in -show cgi
mode, not for -show console, so cgi is essentially required to display
email addresses when running in remote CGI mode to display in a web
browser (though -show console plain text makes more sense if you
wish to grab the reply with urllib for display in a tkinter GUI...).
=====================================================================
"""
import poplib, email, random, getpass, pprint, sys, time, cgi, os
RunAsCGI = False # True: urlparms->sys.argv, cgi hdr
Drawings = 1 # how many players to select
Signup = 'PP4E@learning-python.com' # pick-from-email mode parameters
Subject = 'PYLOTTO'
Server = 'pop.secureserver.net'
Filename = 'pylotto-players.txt' # pick-from-file mode parameter
OnPython3 = sys.version_info[0] == 3 # some py 2.X can't use .major == 3!
def printN(*args):
"""
needed only if > 1 arg to print, else print(x) works
same in 2.X and 3.X; ignores 3.X keyword-only print options:
see Learning Python 4E for a version that handles these too;
can't use from __future__ for 3.X print until Python 2.6;
"""
if OnPython3:
eval('print(*args)') # invalid syntax in 2.X
else:
text = ' '.join([str(x) for x in args]) # "print()" is empty tuple in 2.X
print(text)
class FindEmails:
"""
find and remove signup emails, mixed with a shower class;
py3.1 email requires decoding mail text to str (3.2 may not);
messsage_from_string(s) == email.parser.Parser().parsestr(s);
later removes duplicate email addresses, but may not be enough;
"""
hastop = True
def findPlayers(self, signup=Signup, subject=Subject, server=Server):
password = self.popPassword()
players = []
server = poplib.POP3(server)
server.user(signup)
server.pass_(password)
self.trace(server.getwelcome())
self.trace(server.list())
try:
msgcount, msgbytes = server.stat()
for i in range(msgcount):
self.trace('message %s of %s...' % (i+1, msgcount))
if not self.hastop:
hdr, msgbytes, octets = server.retr(i+1) # get full text
else:
hdr, msgbytes, octets = server.top(i+1, 0) # headers only
if OnPython3:
msglines = [line.decode('utf-8') for line in msgbytes] # 3.1: to str
else: # 3.2: optional
msglines = msgbytes # 2.X: just str
msgtext = '\n'.join(msglines)
msgobj = email.message_from_string(msgtext) # parse text
if msgobj['Subject'].upper() == subject:
players.append(msgobj['From'])
server.dele(i+1) # del on quit
finally:
server.quit() # be sure to unlock mailbox on exit
return players
class FindFile:
"""
select from a local file of names, mixed with a shower class;
may be run on local client or remote server, in console or CGI modes;
run as CGI on server to select from file created by web form or manual;
run on local machine if no email access, and CGI web form page unusable;
"""
def findPlayers(self, filename=Filename):
players = []
for line in open(filename):
players.append(line.rstrip())
return players
# or: return [line.rstrip() for line in open(filename)]
class ShowConsole:
"""
display in a console window, running locally or remotely
mix with finder that may select from a names file or emails
"""
def run(self):
print('Running in console...')
players = self.findPlayers()
print('\n%s\nPlayers:\n' % ('=' * 80))
for player in players:
print(player)
time.sleep(0.5)
winners = self.pickWinners(players)
print('\n%s\nWinners:\n' % ('=' * 80))
#pprint.pprint(winners)
for winner in winners: print(winner)
def popPassword(self):
return getpass.getpass('pop email password?')
def trace(self, *args, **kargs):
printN(*args)
class ShowCGI:
"""
display as CCI web page result, in browser, urllib, console
mix with finder that may select from a names file or emails
done: run pprint.pprint() output through cgi.escape() -- this
is crucial when emails are used, due to their <..> brackets;
original naive display:
pprint.pprint(players)
intermediate - but no io module in python 2.X:
buffer = io.StringIO()
pprint.pprint(players, buffer)
print(cgi.escape(buffer.getvalue()))
"""
def run(self):
#print('Content-type: text/html\n') # header already printed
print('')
print('PyLotto')
print('PyLotto Results
')
print('Players:
')
print('')
players = self.findPlayers()
for player in players:
print(cgi.escape(player))
print('Winners:
')
print('')
winners = self.pickWinners(players)
for winner in winners:
print(cgi.escape(winner))
print('')
def popPassword(self): # assume file
return open('pylotto.pswd').readline().rstrip() # secure me!
def trace(*args, **kargs): pass
class Picker:
"""
choose winners at random, mixed in with shower and finder
note: set.pop() is defined to remove an arbitrary set item
too, but I'd rather rely on the random module explicitly here
to be sure that this is fair ("arbitrary" may be arbitrary);
"""
def pickWinners(self, players, drawings=Drawings):
players = list(set(players)) # remove duplicates, probably
winners = []
for i in range(drawings):
if not players:
break
else:
drawn = random.choice(players)
players.remove(drawn)
winners.append(drawn)
return winners
def sendTestPlayers(ccplayer=False):
"""
send a few test emails, run local or remote via URL
callable with -test and during interactive testing
adds to the names file on the script's machine too;
"""
players = ['"Book support" ', # new: try various formats
'lutz@learning-python.com',
'the book ']
try:
import smtplib, email.utils, email.message # email.* fails in Py 2.4
sendserver = 'smtpout.secureserver.net'
for player in players:
msgobj = email.message.Message()
msgobj['From'] = player
msgobj['To'] = Signup
msgobj['Subject'] = Subject
msgobj['Date'] = email.utils.formatdate()
msgobj.set_payload('Signing up for lotto...\n')
print('Connecting...')
rcpts = [Signup]
if ccplayer: rcpts.append(player)
server = smtplib.SMTP(sendserver)
failed = server.sendmail(player, rcpts, str(msgobj))
server.quit()
assert not failed
print(str(msgobj))
except:
pass # smpt not supported here? older 2.X email lib?
# also add to names file for testing
file = open(Filename, 'a')
for player in players:
file.write(player + '\n')
file.close()
def resetFile(filename=Filename):
open(filename, 'w').close() # empty the players names file
print('Players file cleared. ')
def resetEmails():
print('Run main logic to clear emails, with [-find email -show S].')
def testLotto():
"""
test all 4 main lotto show/find combos: console|cgi * email|file
mixes methods from classes per modes just like runLotto() below;
this is essentially a class factory: makes new classes in loop;
"""
for shower in ShowConsole, ShowCGI:
for finder in FindFile, FindEmails:
printN('*' * 80, shower, finder)
sendTestPlayers()
time.sleep(10) # a guess
class PyLotto(shower, finder, Picker): pass
PyLotto().run()
resetFile()
def runLotto():
"""
main logic: run the lottery in the show/find modes given
in script's cmdline args (default modes = email/console),
mixing together selectable run mode classes plus Picker;
"""
showModes = dict(console=ShowConsole, cgi=ShowCGI)
findModes = dict(email=FindEmails, file=FindFile)
config = dict(show='console', find='email') # [-show S] [-find F]
for arg in config:
try:
config[arg] = sys.argv[sys.argv.index('-' + arg) + 1]
except:
pass
shower, finder = showModes[config['show']], findModes[config['find']]
class PyLotto(shower, finder, Picker):
pass
PyLotto().run()
def handleFormSubmit(filename=Filename):
"""
the input form or URL's query parameters have already
been parsed here, so we can treat CGI inoputs as simple
command-line arguments: see RunAsCGI logic in __main__;
opens file for appending, with exclusive access lock to
support concurrent updates in web mode (close unlocks);
"""
if not os.path.exists(filename):
open(filename, 'w').close()
try:
player = sys.argv[sys.argv.index('-form') + 1]
fd = os.open(filename, os.O_EXCL | os.O_APPEND | os.O_WRONLY)
line = (player + '\n').encode()
os.write(fd, line) # 3.X: encode to bytes, no-op on 2.X
os.close(fd)
except:
player = '...Error!\n%s\n%s' % sys.exc_info()[:2]
if RunAsCGI:
# assume run as a web server: html reply
print('')
print('PyLotto')
print('PyLotto Sign-up
')
print('')
print('Signed up: %s' % cgi.escape(player)) # oct11: escape this too!
print('
')
else:
# may be run from console with -form cmdline arg
print('Signed up: %s' % player)
def initAsCGI():
"""
in CGI mode: translate URL query parameters to command-line arguments;
cmdline args not passed through on my ISP when run remotely via URL;
includes both switches as well as form input field for sign-ups;
emit CGI reply hdr now too: may wrap console or html result display;
"""
print('Content-type: text/html\n') # emit reply header now
sys.stderr = sys.stdout # display any Python errors
urlparams = cgi.FieldStorage() # parse, xlate params
for key in urlparams.keys():
sys.argv.extend([key, urlparams[key].value])
#cgi.print_environ()
#cgi.print_arguments()
if __name__ == '__main__':
usage1 = 'pylotto.py [-send | -reset | -test | -form player | [-show S] [-find F] ]'
usage2 = '(S = console | cgi, F = email | file, defaults: console, email)'
# web: translate URL params, emit header
if RunAsCGI:
initAsCGI() # changes sys.argv
# run admin modes
if '-send' in sys.argv:
sendTestPlayers() # send test emails/file lines
elif '-reset' in sys.argv:
resetFile() # clear state (as possible)
resetEmails()
elif '-test' in sys.argv:
testLotto() # test all lotto mode combinations
elif '-form' in sys.argv:
handleFormSubmit() # save submitted player in CGI mode
# run main logic
elif '-show' in sys.argv or '-find' in sys.argv:
runLotto() # run lotto with selected modes
else:
print('Usage:\n%s\n\t%s' % (usage1, usage2))