[chaos**]

(Part 1 to come eventually :( I really dont want to write that)
The Smogon API Part 2: Handling logins

As I have said at random times in #insidescoop, the new Smogon site has a very
comprehensive API to make programming as absolutely painless as possible. The
first of a long series of documents detailing this API is contained... within this post!
I'll try to do a new one every once in a while, as eventually when I'm done I'd like it
if other programmers helped me without the site :-) This documentation is available
via Python help system as well, but I figure it'd be even better to provide a
bonafide tutorial on this shit.

** The user database currently comes from vBulletin. While this API may change slightly
in '08 when I write our own forum system that integrates with the whole of the site,
the function names and fundamental concepts within shouldn't change. For the most part,
this is a finalized API. At least... I hope. No guarantees!***

A quick, and dirty example to start things off!

from smogon.helpers.user import cond_login

def index(req):
    login = cond_login(req)
    print login.user_username

A surprising amount of functionality for 4 lines of code! What this sample does
is print the logged in user's username. For the more attentive, you may be wondering...
"what if they aren't logged in?" "what if they are banned?" and other questions.
That's the beauty of the login API; it ALWAYS returns a valid login object. If the user
can't login for whatever reason then an exception is raised and we never reach the
print statement. Pretty awesome huh? The defaults for helpers.user.cond_login take
the user to a login page that redirects to the current page if a session can't be found.

Customizing cases!

Sometimes you don't want the default functionality every single time. What if you don't give a
crap about whether they can login or not? Try the uncond_login function. uncond_login, despite the name,
CAN raise exceptions, they are just of a different nature. It returns None if the user can't login
but has the ability to raise exceptions if a user is banned, for instance.

    login = uncond_login(req)
    print login

This function is useful for, say, when you never really use the login object but just want
to pass the information to a template so it can say who is currently logged in.

It's possible to give custom logic to both cond_login and uncond_login. Let's take a look
at their function signatures first though:

def uncond_login(req, **kwargs)
def cond_login(req, **kwargs)

req is an instance of the colubrid Request object. It's passed as the first parameter
to every HTTP request function, so just blindly pass it on.

Each function can also take a series of keyword arguments. These arguments are functions
that return exceptions. Any keyword argument that is left out resorts to the defaults
for that function. You can pass True if you want the function to raise a default exception.

Some examples:

from colubrid.exceptions import HttpFound, BadRequest
from smogon.helpers.user import cond_login, uncond_login, NotLoggedIn, Banned

# Redirect all banned users to banned.html, print login object of logged in and unlogged in users.
def example1(req):
    login = uncond_login(req, banned=lambda req, login: HttpFound("/banned.html"))
    print login

# Hmm... redirect users to a login screen if they aren't logged in, but print a banned msg if they are banned.  
def example2(req):
    try:
        login = cond_login(req, banned=True)
        print "Welcome to the club, non banned user."
    except Banned, e:
        print e.message

# Make sure the user knows that he is new. 
def example3(req):
    try:
        login = cond_login(req, not_logged_in=True)
        print "Hey buddy :D"
    except NotLoggedIn, e:
        print "WHATS UP YOU'RE NEW, GO LOGIN $_$"

The main reason for passing True to these arguments is when you want to render a different
template depending on a condition, since you can't raise that as an exception.
Other logic should be handled via functions that return colubrid exceptions.

Reference coming soon.