root/alamode.py

"""'A La Mode' is a helper module for web apps. This is version 1.0.16.

See alamode.html for more info.

LICENSE
-------
This work, including the source code, documentation
and related data, is placed into the public domain.

The original author is Robert Brewer.
fumanchu@aminus.org
http://projects.amor.org/misc/wiki/Alamode

THIS SOFTWARE IS PROVIDED AS-IS, WITHOUT WARRANTY
OF ANY KIND, NOT EVEN THE IMPLIED WARRANTY OF
MERCHANTABILITY. THE AUTHOR OF THIS SOFTWARE
ASSUMES _NO_ RESPONSIBILITY FOR ANY CONSEQUENCE
RESULTING FROM THE USE, MODIFICATION, OR
REDISTRIBUTION OF THIS SOFTWARE.
"""

__all__ = ['Adapter', 'AdapterFromHTML', 'AdapterToHTML',
           'checked', 'selected',
           'coerce_in', 'coerce_out',
           'escape_url', 'escape_spaces', 'unescape_spaces',
           'from_html', 'to_html',
           'inttuple', 'strtuple',
           'parse_date', 'sane_year',
           'quote', 'urljoin',
           'today', 'now',
           ]

import datetime
today = datetime.date.today
now = datetime.datetime.now

import sys, traceback

# Quoting and escaping
from xml.sax.saxutils import quoteattr as quote

control = "".join(map(chr, xrange(32)))
reserved = ";/?:@&=+$,"
unwise = '<>#%"'
def escape_url(url, escape_unwise=True):
    """Replace excluded URL characters with hex-encoded (%XX)."""
    chars = control + reserved + " "
    if escape_unwise:
        chars += unwise
    for char in chars:
        url = url.replace(char, hex(ord(char)).replace("0x", "%"))
    return url


def urljoin(*atoms):
    """urljoin(*atoms) -> Join path atoms with / to form a complete url."""
    return u"/".join([x.strip(r"\/") for x in atoms])

def selected(value):
    """If value is True, return a valid XHTML 'selected' attribute, else u''."""
    if value:
        return u' selected="selected" '
    return u''

def checked(value):
    """If value is True, return a valid XHTML 'checked' attribute, else u''."""
    if value:
        return u' checked="checked" '
    return u''

def escape_spaces(val, repl='&nbsp;'):
    """escape_spaces(val, repl='&nbsp;') -> val, made safe for HTML forms.
    
    Replace leading and trailing spaces with &nbsp;, to get around browsers
    like IE, Firefox and Lynx which strip leading and trailing spaces from
    form element values upon submit. See unescape_spaces() for the reverse
    transform.
    
    IE, Firefox: occurs with option elements (display only; if a separate
    value argument is given (<option value=' x '>), there's no problem).
    
    Lynx: occurs with submit buttons.
    """
    
    replfunc = lambda m: repl * len(m.group(0))
    if isinstance(val, basestring):
        val = re.sub(r'^( +)', replfunc, val)
        val = re.sub(r'( +)$', replfunc, val)
    return val

def unescape_spaces(val, esc='\xa0'):
    """unescape_spaces(val, esc='\xa0') -> val, unescaped from an HTML form.
    
    The reverse of escape_spaces(). Replace leading and trailing
    occurrences of the 'esc' arg with spaces.
    
    Notice that the default pattern is not '&nbsp;', as it is for
    escape_spaces(). Most browsers/servers replace &nbsp; values with \xa0
    when submitting form data.
    """
    
    replfunc = lambda m: " " * len(m.group(0))
    if isinstance(val, basestring):
        val = re.sub(r'^(%s+)' % re.escape(esc), replfunc, val)
        val = re.sub(r'(%s+)$' % re.escape(esc), replfunc, val)
    return val


###########################################################################
##                                                                       ##
##                               Adapters                                ##
##                                                                       ##
###########################################################################

try:
    import fixedpoint
except ImportError:
    pass

try:
    import decimal
except ImportError:
    pass

import re

def _pop_head_atom(aList):
    try:
        return aList.pop(0)
    except IndexError:
        return 0

latin1Replacements = {u'~a': u'\u00E1', u'~e': u'\u00E9',
                      u'~i': u'\u00ED', u'~n': u'\u00F1',
                      u'~o': u'\u00F3', u'~u': u'\u00FA',
                      u'~y': u'\u00FD',
                      u'~A': u'\u00C1', u'~E': u'\u00C9',
                      u'~I': u'\u00CD', u'~N': u'\u00D1',
                      u'~O': u'\u00D3', u'~U': u'\u00DA',
                      u'~Y': u'\u00DD'}


class strtuple(tuple):
    """A new type for HTML: a tuple of strings."""
    pass

class inttuple(tuple):
    """A new type for HTML: a tuple of string-ified ints."""
    pass

def sane_year(yearAsString, lookahead=20):
    """Sanity-check years entered as less than four digits.
    
    If users want to enter years between 0 A.D. and 99 A.D., they need to
    enter it as a four-digit year (0000-0099). Dates entered as less than
    four digits take the current century, unless that places them past the
    current year by (lookahead) years or more, in which case they take the
    previous century."""
    yearAsInt = int(yearAsString)
    if yearAsInt < 100 and len(yearAsString) < 4:
        currentYear = today().year
        currentCentury, rem = divmod(currentYear, 100)
        yearAsInt += (currentCentury * 100)
        if yearAsInt >= (currentYear + lookahead):
            yearAsInt -= 100
    return yearAsInt

def parse_date(dateAsString):
    atoms = re.split(r"\D", dateAsString)
    if len(atoms) != 3:
        raise ValueError("Date values must be in the form: mm dd yy.")
    atoms = sane_year(atoms[2]), int(atoms[0]), int(atoms[1])
    return atoms


class Adapter(object):
    """Transform values according to their type. Must be subclassed.
    
    In order for your subclass to work, you need to provide functions
    named 'coerce_' + type, where 'type' refers to the type you wish to
    support. Replace dots in the type name by underscores. For example,
    to coerce datetime.date objects, you must provide a function in your
    subclass named 'coerce_datetime_date'. For builtins, do not include
    the module name '__builtin__', just use 'coerce_unicode', for example.
    
    If you try to coerce a value for whose type you have not provided a
    coercion function, a TypeError is raised.
    
    When writing Adapters for Cation, you should at least provide
    coerce_* functions for: bool, float, int, inttuple, long, NoneType,
    str, strtuple, and unicode. For most applications, you should
    also provide:
        datetime.datetime
                .date
                .time
    and:
        fixedpoint.FixedPoint or decimal.Decimal (preferably both)
    """
    
    def coerce(self, value, valuetype=None):
        """coerce(value, valuetype=None) -> value, coerced by valuetype."""
        if valuetype is None:
            valuetype = type(value)
        
        mod = valuetype.__module__
        if mod == "__builtin__":
            xform = "coerce_%s" % valuetype.__name__
        else:
            xform = "coerce_%s_%s" % (mod, valuetype.__name__)
        xform = xform.replace(".", "_")
        try:
            xform = getattr(self, xform)
        except AttributeError:
            raise TypeError("'%s' is not handled by %s." %
                            (valuetype, self.__class__))
        return xform(value)


class AdapterFromHTML(Adapter):
    """Transform values according to their type from HTML strings."""
    
    def substitute_latin_1(self, value):
        """Replace markup with high-ASCII equiv. (e.g.: ~n with \u00F1)."""
        value = unicode(value)
        for eachKey, eachValue in latin1Replacements.items():
            value = value.replace(eachKey, eachValue)
        return value
    
    def coerce_bool(self, value):
        return value.lower() in ('true', 't', '1', '-1',
                                 'y', 'yes', 'on', 'si')
    
    def coerce_datetime_datetime(self, value):
        value = value.strip()
        if value == '':
            return None
        try:
            aDate, aTime = value.split(" ")
            timeatoms = map(int, aTime.split(":"))
        except ValueError:
            aDate = value
            aTime = ''
            timeatoms = [0, 0, 0]
        try:
            atoms = re.match(r"^([0-9][0-9]?)[/-]([0-9][0-9]?)[/-]([0-9][0-9]*)",
                             aDate).groups(0)
        except AttributeError:
            return None
        
        month, day, year = [x for x in atoms]
        month, day, year = int(month), int(day), sane_year(year)
        hour = _pop_head_atom(timeatoms)
        minute = _pop_head_atom(timeatoms)
        second = _pop_head_atom(timeatoms)
        if ('pm' in aTime or 'PM' in aTime) and hour < 12:
            hour += 12
        return datetime.datetime(year, month, day, hour, minute, second)
    
    def coerce_datetime_date(self, value):
        value = value.strip()
        if value == '':
            return None
        try:
            atoms = re.match(r"^([0-9][0-9]?)[/-]([0-9][0-9]?)[/-]([0-9][0-9]*)",
                             value).groups(0)
        except AttributeError:
            return None
        month, day, year = [x for x in atoms]
        month, day, year = int(month), int(day), sane_year(year)
        return datetime.date(year, month, day)
    
    def coerce_datetime_time(self, value):
        value = value.strip()
        if value == '':
            return None
        
        # Pull out am/pm indicator
        if value[-1] in ('a', 'p'):
            pm = (value[-1] == 'p')
            value = value[:-1]
        else:
            pm = False
        
        timeatoms = map(int, value.split(":"))
        hour = _pop_head_atom(timeatoms)
        minute = _pop_head_atom(timeatoms)
        second = _pop_head_atom(timeatoms)
        
        if pm and hour < 12:
            hour += 12
        
        return datetime.time(hour, minute, second)
    
    def coerce_decimal_Decimal(self, value):
        value = str(value).replace('$', '')
        if value == '':
            return None
        return decimal.Decimal(value)
    
    def coerce_float(self, value):
        value = str(value).replace('$', '')
        if value == '':
            return None
        return float(value)
    
    def coerce_fixedpoint_FixedPoint(self, value):
        value = str(value).replace('$', '')
        if value == '':
            return None
        return fixedpoint.FixedPoint(value)
    
    def coerce_int(self, value):
        if value == '':
            return None
        value = int(value)
        if isinstance(value, long):
            raise ValueError("invalid literal for int(): %s" % value)
        return value
    
    def coerce_alamode_inttuple(self, value):
        value = [int(x.strip()) for x in value.split(",")]
        return tuple(value)
    
    def coerce_long(self, value):
        if value == '':
            return None
        return long(value)
    
    coerce_NoneType = substitute_latin_1
    coerce_str = substitute_latin_1
    
    def coerce_alamode_strtuple(self, value):
        value = [x.strip() for x in value.split(",")]
        return tuple(value)
    
    coerce_unicode = substitute_latin_1
    
    def coerce_list(self, value):
        """Return a list of strings or ints from a repr of such."""
        atoms = []
        for x in value[1:-1].split(","):
            x = x.strip()
            if x.startswith("'") and x.endswith("'"):
                atoms.append(x)
            else:
                atoms.append(int(x))
        return atoms
    
    def coerce_tuple(self, value):
        """Return a tuple of strings or ints from a repr of such."""
        return tuple(self.coerce_list(value))

from_html = AdapterFromHTML()


class AdapterToHTML(Adapter):
    """Transform values according to their type to HTML strings."""
    
    def to_unicode(self, value):
        return unicode(value)
    
    coerce_bool = to_unicode
    
    def coerce_datetime_datetime(self, value):
        return ('%s/%s/%04d %s:%02d:%02d' %
                (value.month, value.day, value.year,
                 value.hour, value.minute, value.second))
    
    def coerce_datetime_date(self, value):
        return '%s/%s/%04d' % (value.month, value.day, value.year)
    
    def coerce_datetime_time(self, value):
        if value is None:
            return ""
        if value.second:
            return '%s:%02d:%02d' % (value.hour, value.minute, value.second)
        else:
            h = value.hour
            m = value.minute
            pm = (h >= 12)
            if h > 12:
                h -= 12
            return u"%d:%02d%s" % (h, m, ('a', 'p')[pm])
    
    coerce_decimal_Decimal = to_unicode
    coerce_fixedpoint_FixedPoint = to_unicode
    coerce_float = to_unicode
    coerce_int = to_unicode
    coerce_alamode_inttuple = to_unicode
    coerce_long = to_unicode
    
    def coerce_NoneType(self, value):
        return u''
    
    coerce_str = to_unicode
    coerce_alamode_strtuple = to_unicode
    coerce_unicode = to_unicode
    coerce_list = repr
    coerce_tuple = repr

to_html = AdapterToHTML()

missing=object()

typenames = {'int': 'a whole number',
             'long': 'a whole number',
             'date': 'a date (of the form m/d/yyyy)',
             'datetime': 'a date and time (of the form m/d/yyyy hh:mm:ss)',
             'FixedPoint': 'a dollar amount',
             'decimal': 'a dollar amount',
             'Decimal': 'a dollar amount',
             }

def coerce_in(paramMap, key, type, default=missing):
    """coerce_in(paramMap, key, type, default=missing) -> instance of type.
    
    Coerces an inbound parameter to the specified type. If the parameter
    is not present, the default is returned instead.
    """
    try:
        value = paramMap[key]
    except KeyError, x:
        if default is missing:
            x.args += (u"A value named '%s' was expected "
                       u"but not supplied." % key,)
            raise x
        else:
            return default
    
    try:
        coerced = from_html.coerce(value, type)
    except Exception, x:
        msg = ("The value named '%s' should be %s, but the supplied value "
               "(%s) could not be converted to that type.")
        tname = type.__name__
        raise TypeError(msg % (key, typenames.get(tname, tname), `value`))
    return coerced

def coerce_out(obj, attr=missing, default=missing):
    """coerce_out(obj, attr=missing, default=missing) -> unicode.
    
    Convert an outbound value or attribute to a unicode string.
    If attr is missing, the object itself is coerced. If attr is
    present, that attribute of the object is retrieved and coerced.
    If attr does not exist for obj, the default is returned.
    """
    if attr is missing:
        return to_html.coerce(obj)
    else:
        if default is missing:
            return to_html.coerce(getattr(obj, attr))
        else:
            return to_html.coerce(getattr(obj, attr, default))