Lib/Cookie.py

   1 #!/usr/bin/env python
   2 #
   3
   4 ####
   5 # Copyright 2000 by Timothy O'Malley <timo@alum.mit.edu>
   6 #
   7 #                All Rights Reserved
   8 #
   9 # Permission to use, copy, modify, and distribute this software
  10 # and its documentation for any purpose and without fee is hereby
  11 # granted, provided that the above copyright notice appear in all
  12 # copies and that both that copyright notice and this permission
  13 # notice appear in supporting documentation, and that the name of
  14 # Timothy O'Malley  not be used in advertising or publicity
  15 # pertaining to distribution of the software without specific, written
  16 # prior permission.
  17 #
  18 # Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  19 # SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  20 # AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
  21 # ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  22 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  23 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  24 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  25 # PERFORMANCE OF THIS SOFTWARE.
  26 #
  27 ####
  28 #
  29 # Id: Cookie.py,v 2.29 2000/08/23 05:28:49 timo Exp
  30 #   by Timothy O'Malley <timo@alum.mit.edu>
  31 #
  32 #  Cookie.py is a Python module for the handling of HTTP
  33 #  cookies as a Python dictionary.  See RFC 2109 for more
  34 #  information on cookies.
  35 #
  36 #  The original idea to treat Cookies as a dictionary came from
  37 #  Dave Mitchell (davem@magnet.com) in 1995, when he released the
  38 #  first version of nscookie.py.
  39 #
  40 ####
  41
  42 r"""
  43 Here's a sample session to show how to use this module.
  44 At the moment, this is the only documentation.
  45
  46 The Basics
  47 ----------
  48
  49 Importing is easy..
  50
  51    >>> import Cookie
  52
  53 Most of the time you start by creating a cookie.  Cookies come in
  54 three flavors, each with slighly different encoding semanitcs, but
  55 more on that later.
  56
  57    >>> C = Cookie.SimpleCookie()
  58    >>> C = Cookie.SerialCookie()
  59    >>> C = Cookie.SmartCookie()
  60
  61 [Note: Long-time users of Cookie.py will remember using
  62 Cookie.Cookie() to create an Cookie object.  Although deprecated, it
  63 is still supported by the code.  See the Backward Compatibility notes
  64 for more information.]
  65
  66 Once you've created your Cookie, you can add values just as if it were
  67 a dictionary.
  68
  69    >>> C = Cookie.SmartCookie()
  70    >>> C["fig"] = "newton"
  71    >>> C["sugar"] = "wafer"
  72    >>> print C
  73    Set-Cookie: fig=newton;
  74    Set-Cookie: sugar=wafer;
  75
  76 Notice that the printable representation of a Cookie is the
  77 appropriate format for a Set-Cookie: header.  This is the
  78 default behavior.  You can change the header and printed
  79 attributes by using the the .output() function
  80
  81    >>> C = Cookie.SmartCookie()
  82    >>> C["rocky"] = "road"
  83    >>> C["rocky"]["path"] = "/cookie"
  84    >>> print C.output(header="Cookie:")
  85    Cookie: rocky=road; Path=/cookie;
  86    >>> print C.output(attrs=[], header="Cookie:")
  87    Cookie: rocky=road;
  88
  89 The load() method of a Cookie extracts cookies from a string.  In a
  90 CGI script, you would use this method to extract the cookies from the
  91 HTTP_COOKIE environment variable.
  92
  93    >>> C = Cookie.SmartCookie()
  94    >>> C.load("chips=ahoy; vienna=finger")
  95    >>> print C
  96    Set-Cookie: chips=ahoy;
  97    Set-Cookie: vienna=finger;
  98
  99 The load() method is darn-tootin smart about identifying cookies
 100 within a string.  Escaped quotation marks, nested semicolons, and other
 101 such trickeries do not confuse it.
 102
 103    >>> C = Cookie.SmartCookie()
 104    >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
 105    >>> print C
 106    Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
 107
 108 Each element of the Cookie also supports all of the RFC 2109
 109 Cookie attributes.  Here's an example which sets the Path
 110 attribute.
 111
 112    >>> C = Cookie.SmartCookie()
 113    >>> C["oreo"] = "doublestuff"
 114    >>> C["oreo"]["path"] = "/"
 115    >>> print C
 116    Set-Cookie: oreo=doublestuff; Path=/;
 117
 118 Each dictionary element has a 'value' attribute, which gives you
 119 back the value associated with the key.
 120
 121    >>> C = Cookie.SmartCookie()
 122    >>> C["twix"] = "none for you"
 123    >>> C["twix"].value
 124    'none for you'
 125
 126
 127 A Bit More Advanced
 128 -------------------
 129
 130 As mentioned before, there are three different flavors of Cookie
 131 objects, each with different encoding/decoding semantics.  This
 132 section briefly discusses the differences.
 133
 134 SimpleCookie
 135
 136 The SimpleCookie expects that all values should be standard strings.
 137 Just to be sure, SimpleCookie invokes the str() builtin to convert
 138 the value to a string, when the values are set dictionary-style.
 139
 140    >>> C = Cookie.SimpleCookie()
 141    >>> C["number"] = 7
 142    >>> C["string"] = "seven"
 143    >>> C["number"].value
 144    '7'
 145    >>> C["string"].value
 146    'seven'
 147    >>> print C
 148    Set-Cookie: number=7;
 149    Set-Cookie: string=seven;
 150
 151
 152 SerialCookie
 153
 154 The SerialCookie expects that all values should be serialized using
 155 cPickle (or pickle, if cPickle isn't available).  As a result of
 156 serializing, SerialCookie can save almost any Python object to a
 157 value, and recover the exact same object when the cookie has been
 158 returned.  (SerialCookie can yield some strange-looking cookie
 159 values, however.)
 160
 161    >>> C = Cookie.SerialCookie()
 162    >>> C["number"] = 7
 163    >>> C["string"] = "seven"
 164    >>> C["number"].value
 165    7
 166    >>> C["string"].value
 167    'seven'
 168    >>> print C
 169    Set-Cookie: number="I7\012.";
 170    Set-Cookie: string="S'seven'\012p1\012.";
 171
 172 Be warned, however, if SerialCookie cannot de-serialize a value (because
 173 it isn't a valid pickle'd object), IT WILL RAISE AN EXCEPTION.
 174
 175
 176 SmartCookie
 177
 178 The SmartCookie combines aspects of each of the other two flavors.
 179 When setting a value in a dictionary-fashion, the SmartCookie will
 180 serialize (ala cPickle) the value *if and only if* it isn't a
 181 Python string.  String objects are *not* serialized.  Similarly,
 182 when the load() method parses out values, it attempts to de-serialize
 183 the value.  If it fails, then it fallsback to treating the value
 184 as a string.
 185
 186    >>> C = Cookie.SmartCookie()
 187    >>> C["number"] = 7
 188    >>> C["string"] = "seven"
 189    >>> C["number"].value
 190    7
 191    >>> C["string"].value
 192    'seven'
 193    >>> print C
 194    Set-Cookie: number="I7\012.";
 195    Set-Cookie: string=seven;
 196
 197
 198 Backwards Compatibility
 199 -----------------------
 200
 201 In order to keep compatibilty with earlier versions of Cookie.py,
 202 it is still possible to use Cookie.Cookie() to create a Cookie.  In
 203 fact, this simply returns a SmartCookie.
 204
 205    >>> C = Cookie.Cookie()
 206    >>> print C.__class__.__name__
 207    SmartCookie
 208
 209
 210 Finis.
 211 """  #"
 212 #     ^
 213 #     |----helps out font-lock
 214
 215 #
 216 # Import our required modules
 217 #
 218 import string
 219
 220 try:
 221     from cPickle import dumps, loads
 222 except ImportError:
 223     from pickle import dumps, loads
 224
 225 try:
 226     import re
 227 except ImportError:
 228     raise ImportError, "Cookie.py requires 're' from Python 1.5 or later"
 229
 230 __all__ = ["CookieError","BaseCookie","SimpleCookie","SerialCookie",
 231            "SmartCookie","Cookie"]
 232
 233 _nulljoin = ''.join
 234 _spacejoin = ' '.join
 235
 236 #
 237 # Define an exception visible to External modules
 238 #
 239 class CookieError(Exception):
 240     pass
 241
 242
 243 # These quoting routines conform to the RFC2109 specification, which in
 244 # turn references the character definitions from RFC2068.  They provide
 245 # a two-way quoting algorithm.  Any non-text character is translated
 246 # into a 4 character sequence: a forward-slash followed by the
 247 # three-digit octal equivalent of the character.  Any '\' or '"' is
 248 # quoted with a preceeding '\' slash.
 249 #
 250 # These are taken from RFC2068 and RFC2109.
 251 #       _LegalChars       is the list of chars which don't require "'s
 252 #       _Translator       hash-table for fast quoting
 253 #
 254 _LegalChars       = string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~"
 255 _Translator       = {
 256     '\000' : '\\000',  '\001' : '\\001',  '\002' : '\\002',
 257     '\003' : '\\003',  '\004' : '\\004',  '\005' : '\\005',
 258     '\006' : '\\006',  '\007' : '\\007',  '\010' : '\\010',
 259     '\011' : '\\011',  '\012' : '\\012',  '\013' : '\\013',
 260     '\014' : '\\014',  '\015' : '\\015',  '\016' : '\\016',
 261     '\017' : '\\017',  '\020' : '\\020',  '\021' : '\\021',
 262     '\022' : '\\022',  '\023' : '\\023',  '\024' : '\\024',
 263     '\025' : '\\025',  '\026' : '\\026',  '\027' : '\\027',
 264     '\030' : '\\030',  '\031' : '\\031',  '\032' : '\\032',
 265     '\033' : '\\033',  '\034' : '\\034',  '\035' : '\\035',
 266     '\036' : '\\036',  '\037' : '\\037',
 267
 268     '"' : '\\"',       '\\' : '\\\\',
 269
 270     '\177' : '\\177',  '\200' : '\\200',  '\201' : '\\201',
 271     '\202' : '\\202',  '\203' : '\\203',  '\204' : '\\204',
 272     '\205' : '\\205',  '\206' : '\\206',  '\207' : '\\207',
 273     '\210' : '\\210',  '\211' : '\\211',  '\212' : '\\212',
 274     '\213' : '\\213',  '\214' : '\\214',  '\215' : '\\215',
 275     '\216' : '\\216',  '\217' : '\\217',  '\220' : '\\220',
 276     '\221' : '\\221',  '\222' : '\\222',  '\223' : '\\223',
 277     '\224' : '\\224',  '\225' : '\\225',  '\226' : '\\226',
 278     '\227' : '\\227',  '\230' : '\\230',  '\231' : '\\231',
 279     '\232' : '\\232',  '\233' : '\\233',  '\234' : '\\234',
 280     '\235' : '\\235',  '\236' : '\\236',  '\237' : '\\237',
 281     '\240' : '\\240',  '\241' : '\\241',  '\242' : '\\242',
 282     '\243' : '\\243',  '\244' : '\\244',  '\245' : '\\245',
 283     '\246' : '\\246',  '\247' : '\\247',  '\250' : '\\250',
 284     '\251' : '\\251',  '\252' : '\\252',  '\253' : '\\253',
 285     '\254' : '\\254',  '\255' : '\\255',  '\256' : '\\256',
 286     '\257' : '\\257',  '\260' : '\\260',  '\261' : '\\261',
 287     '\262' : '\\262',  '\263' : '\\263',  '\264' : '\\264',
 288     '\265' : '\\265',  '\266' : '\\266',  '\267' : '\\267',
 289     '\270' : '\\270',  '\271' : '\\271',  '\272' : '\\272',
 290     '\273' : '\\273',  '\274' : '\\274',  '\275' : '\\275',
 291     '\276' : '\\276',  '\277' : '\\277',  '\300' : '\\300',
 292     '\301' : '\\301',  '\302' : '\\302',  '\303' : '\\303',
 293     '\304' : '\\304',  '\305' : '\\305',  '\306' : '\\306',
 294     '\307' : '\\307',  '\310' : '\\310',  '\311' : '\\311',
 295     '\312' : '\\312',  '\313' : '\\313',  '\314' : '\\314',
 296     '\315' : '\\315',  '\316' : '\\316',  '\317' : '\\317',
 297     '\320' : '\\320',  '\321' : '\\321',  '\322' : '\\322',
 298     '\323' : '\\323',  '\324' : '\\324',  '\325' : '\\325',
 299     '\326' : '\\326',  '\327' : '\\327',  '\330' : '\\330',
 300     '\331' : '\\331',  '\332' : '\\332',  '\333' : '\\333',
 301     '\334' : '\\334',  '\335' : '\\335',  '\336' : '\\336',
 302     '\337' : '\\337',  '\340' : '\\340',  '\341' : '\\341',
 303     '\342' : '\\342',  '\343' : '\\343',  '\344' : '\\344',
 304     '\345' : '\\345',  '\346' : '\\346',  '\347' : '\\347',
 305     '\350' : '\\350',  '\351' : '\\351',  '\352' : '\\352',
 306     '\353' : '\\353',  '\354' : '\\354',  '\355' : '\\355',
 307     '\356' : '\\356',  '\357' : '\\357',  '\360' : '\\360',
 308     '\361' : '\\361',  '\362' : '\\362',  '\363' : '\\363',
 309     '\364' : '\\364',  '\365' : '\\365',  '\366' : '\\366',
 310     '\367' : '\\367',  '\370' : '\\370',  '\371' : '\\371',
 311     '\372' : '\\372',  '\373' : '\\373',  '\374' : '\\374',
 312     '\375' : '\\375',  '\376' : '\\376',  '\377' : '\\377'
 313     }
 314
 315 def _quote(str, LegalChars=_LegalChars,
 316            idmap=string._idmap, translate=string.translate):
 317     #
 318     # If the string does not need to be double-quoted,
 319     # then just return the string.  Otherwise, surround
 320     # the string in doublequotes and precede quote (with a \)
 321     # special characters.
 322     #
 323     if "" == translate(str, idmap, LegalChars):
 324         return str
 325     else:
 326         return '"' + _nulljoin( map(_Translator.get, str, str) ) + '"'
 327 # end _quote
 328
 329
 330 _OctalPatt = re.compile(r"\\[0-3][0-7][0-7]")
 331 _QuotePatt = re.compile(r"[\\].")
 332
 333 def _unquote(str):
 334     # If there aren't any doublequotes,
 335     # then there can't be any special characters.  See RFC 2109.
 336     if  len(str) < 2:
 337         return str
 338     if str[0] != '"' or str[-1] != '"':
 339         return str
 340
 341     # We have to assume that we must decode this string.
 342     # Down to work.
 343
 344     # Remove the "s
 345     str = str[1:-1]
 346
 347     # Check for special sequences.  Examples:
 348     #    \012 --> \n
 349     #    \"   --> "
 350     #
 351     i = 0
 352     n = len(str)
 353     res = []
 354     while 0 <= i < n:
 355         Omatch = _OctalPatt.search(str, i)
 356         Qmatch = _QuotePatt.search(str, i)
 357         if not Omatch and not Qmatch:              # Neither matched
 358             res.append(str[i:])
 359             break
 360         # else:
 361         j = k = -1
 362         if Omatch: j = Omatch.start(0)
 363         if Qmatch: k = Qmatch.start(0)
 364         if Qmatch and ( not Omatch or k < j ):     # QuotePatt matched
 365             res.append(str[i:k])
 366             res.append(str[k+1])
 367             i = k+2
 368         else:                                      # OctalPatt matched
 369             res.append(str[i:j])
 370             res.append( chr( int(str[j+1:j+4], 8) ) )
 371             i = j+4
 372     return _nulljoin(res)
 373 # end _unquote
 374
 375 # The _getdate() routine is used to set the expiration time in
 376 # the cookie's HTTP header.      By default, _getdate() returns the
 377 # current time in the appropriate "expires" format for a
 378 # Set-Cookie header.     The one optional argument is an offset from
 379 # now, in seconds.      For example, an offset of -3600 means "one hour ago".
 380 # The offset may be a floating point number.
 381 #
 382
 383 _weekdayname = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
 384
 385 _monthname = [None,
 386               'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
 387               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 388
 389 def _getdate(future=0, weekdayname=_weekdayname, monthname=_monthname):
 390     from time import gmtime, time
 391     now = time()
 392     year, month, day, hh, mm, ss, wd, y, z = gmtime(now + future)
 393     return "%s, %02d-%3s-%4d %02d:%02d:%02d GMT" % \
 394            (weekdayname[wd], day, monthname[month], year, hh, mm, ss)
 395
 396
 397 #
 398 # A class to hold ONE key,value pair.
 399 # In a cookie, each such pair may have several attributes.
 400 #       so this class is used to keep the attributes associated
 401 #       with the appropriate key,value pair.
 402 # This class also includes a coded_value attribute, which
 403 #       is used to hold the network representation of the
 404 #       value.  This is most useful when Python objects are
 405 #       pickled for network transit.
 406 #
 407
 408 class Morsel(dict):
 409     # RFC 2109 lists these attributes as reserved:
 410     #   path       comment         domain
 411     #   max-age    secure      version
 412     #
 413     # For historical reasons, these attributes are also reserved:
 414     #   expires
 415     #
 416     # This dictionary provides a mapping from the lowercase
 417     # variant on the left to the appropriate traditional
 418     # formatting on the right.
 419     _reserved = { "expires" : "expires",
 420                    "path"        : "Path",
 421                    "comment" : "Comment",
 422                    "domain"      : "Domain",
 423                    "max-age" : "Max-Age",
 424                    "secure"      : "secure",
 425                    "version" : "Version",
 426                    }
 427
 428     def __init__(self):
 429         # Set defaults
 430         self.key = self.value = self.coded_value = None
 431
 432         # Set default attributes
 433         for K in self._reserved:
 434             dict.__setitem__(self, K, "")
 435     # end __init__
 436
 437     def __setitem__(self, K, V):
 438         K = K.lower()
 439         if not K in self._reserved:
 440             raise CookieError("Invalid Attribute %s" % K)
 441         dict.__setitem__(self, K, V)
 442     # end __setitem__
 443
 444     def isReservedKey(self, K):
 445         return K.lower() in self._reserved
 446     # end isReservedKey
 447
 448     def set(self, key, val, coded_val,
 449             LegalChars=_LegalChars,
 450             idmap=string._idmap, translate=string.translate ):
 451         # First we verify that the key isn't a reserved word
 452         # Second we make sure it only contains legal characters
 453         if key.lower() in self._reserved:
 454             raise CookieError("Attempt to set a reserved key: %s" % key)
 455         if "" != translate(key, idmap, LegalChars):
 456             raise CookieError("Illegal key value: %s" % key)
 457
 458         # It's a good key, so save it.
 459         self.key                 = key
 460         self.value               = val
 461         self.coded_value         = coded_val
 462     # end set
 463
 464     def output(self, attrs=None, header = "Set-Cookie:"):
 465         return "%s %s" % ( header, self.OutputString(attrs) )
 466
 467     __str__ = output
 468
 469     def __repr__(self):
 470         return '<%s: %s=%s>' % (self.__class__.__name__,
 471                                 self.key, repr(self.value) )
 472
 473     def js_output(self, attrs=None):
 474         # Print javascript
 475         return """
 476         <SCRIPT LANGUAGE="JavaScript">
 477         <!-- begin hiding
 478         document.cookie = \"%s\"
 479         // end hiding -->
 480         </script>
 481         """ % ( self.OutputString(attrs), )
 482     # end js_output()
 483
 484     def OutputString(self, attrs=None):
 485         # Build up our result
 486         #
 487         result = []
 488         RA = result.append
 489
 490         # First, the key=value pair
 491         RA("%s=%s;" % (self.key, self.coded_value))
 492
 493         # Now add any defined attributes
 494         if attrs is None:
 495             attrs = self._reserved
 496         items = self.items()
 497         items.sort()
 498         for K,V in items:
 499             if V == "": continue
 500             if K not in attrs: continue
 501             if K == "expires" and type(V) == type(1):
 502                 RA("%s=%s;" % (self._reserved[K], _getdate(V)))
 503             elif K == "max-age" and type(V) == type(1):
 504                 RA("%s=%d;" % (self._reserved[K], V))
 505             elif K == "secure":
 506                 RA("%s;" % self._reserved[K])
 507             else:
 508                 RA("%s=%s;" % (self._reserved[K], V))
 509
 510         # Return the result
 511         return _spacejoin(result)
 512     # end OutputString
 513 # end Morsel class
 514
 515
 516
 517 #
 518 # Pattern for finding cookie
 519 #
 520 # This used to be strict parsing based on the RFC2109 and RFC2068
 521 # specifications.  I have since discovered that MSIE 3.0x doesn't
 522 # follow the character rules outlined in those specs.  As a
 523 # result, the parsing rules here are less strict.
 524 #
 525
 526 _LegalCharsPatt  = r"[\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\=]"
 527 _CookiePattern = re.compile(
 528     r"(?x)"                       # This is a Verbose pattern
 529     r"(?P<key>"                   # Start of group 'key'
 530     ""+ _LegalCharsPatt +"+?"     # Any word of at least one letter, nongreedy
 531     r")"                          # End of group 'key'
 532     r"\s*=\s*"                    # Equal Sign
 533     r"(?P<val>"                   # Start of group 'val'
 534     r'"(?:[^\\"]|\\.)*"'            # Any doublequoted string
 535     r"|"                            # or
 536     ""+ _LegalCharsPatt +"*"        # Any word or empty string
 537     r")"                          # End of group 'val'
 538     r"\s*;?"                      # Probably ending in a semi-colon
 539     )
 540
 541
 542 # At long last, here is the cookie class.
 543 #   Using this class is almost just like using a dictionary.
 544 # See this module's docstring for example usage.
 545 #
 546 class BaseCookie(dict):
 547     # A container class for a set of Morsels
 548     #
 549
 550     def value_decode(self, val):
 551         """real_value, coded_value = value_decode(STRING)
 552         Called prior to setting a cookie's value from the network
 553         representation.  The VALUE is the value read from HTTP
 554         header.
 555         Override this function to modify the behavior of cookies.
 556         """
 557         return val, val
 558     # end value_encode
 559
 560     def value_encode(self, val):
 561         """real_value, coded_value = value_encode(VALUE)
 562         Called prior to setting a cookie's value from the dictionary
 563         representation.  The VALUE is the value being assigned.
 564         Override this function to modify the behavior of cookies.
 565         """
 566         strval = str(val)
 567         return strval, strval
 568     # end value_encode
 569
 570     def __init__(self, input=None):
 571         if input: self.load(input)
 572     # end __init__
 573
 574     def __set(self, key, real_value, coded_value):
 575         """Private method for setting a cookie's value"""
 576         M = self.get(key, Morsel())
 577         M.set(key, real_value, coded_value)
 578         dict.__setitem__(self, key, M)
 579     # end __set
 580
 581     def __setitem__(self, key, value):
 582         """Dictionary style assignment."""
 583         rval, cval = self.value_encode(value)
 584         self.__set(key, rval, cval)
 585     # end __setitem__
 586
 587     def output(self, attrs=None, header="Set-Cookie:", sep="\n"):
 588         """Return a string suitable for HTTP."""
 589         result = []
 590         items = self.items()
 591         items.sort()
 592         for K,V in items:
 593             result.append( V.output(attrs, header) )
 594         return sep.join(result)
 595     # end output
 596
 597     __str__ = output
 598
 599     def __repr__(self):
 600         L = []
 601         items = self.items()
 602         items.sort()
 603         for K,V in items:
 604             L.append( '%s=%s' % (K,repr(V.value) ) )
 605         return '<%s: %s>' % (self.__class__.__name__, _spacejoin(L))
 606
 607     def js_output(self, attrs=None):
 608         """Return a string suitable for JavaScript."""
 609         result = []
 610         items = self.items()
 611         items.sort()
 612         for K,V in items:
 613             result.append( V.js_output(attrs) )
 614         return _nulljoin(result)
 615     # end js_output
 616
 617     def load(self, rawdata):
 618         """Load cookies from a string (presumably HTTP_COOKIE) or
 619         from a dictionary.  Loading cookies from a dictionary 'd'
 620         is equivalent to calling:
 621             map(Cookie.__setitem__, d.keys(), d.values())
 622         """
 623         if type(rawdata) == type(""):
 624             self.__ParseString(rawdata)
 625         else:
 626             self.update(rawdata)
 627         return
 628     # end load()
 629
 630     def __ParseString(self, str, patt=_CookiePattern):
 631         i = 0            # Our starting point
 632         n = len(str)     # Length of string
 633         M = None         # current morsel
 634
 635         while 0 <= i < n:
 636             # Start looking for a cookie
 637             match = patt.search(str, i)
 638             if not match: break          # No more cookies
 639
 640             K,V = match.group("key"), match.group("val")
 641             i = match.end(0)
 642
 643             # Parse the key, value in case it's metainfo
 644             if K[0] == "$":
 645                 # We ignore attributes which pertain to the cookie
 646                 # mechanism as a whole.  See RFC 2109.
 647                 # (Does anyone care?)
 648                 if M:
 649                     M[ K[1:] ] = V
 650             elif K.lower() in Morsel._reserved:
 651                 if M:
 652                     M[ K ] = _unquote(V)
 653             else:
 654                 rval, cval = self.value_decode(V)
 655                 self.__set(K, rval, cval)
 656                 M = self[K]
 657     # end __ParseString
 658 # end BaseCookie class
 659
 660 class SimpleCookie(BaseCookie):
 661     """SimpleCookie
 662     SimpleCookie supports strings as cookie values.  When setting
 663     the value using the dictionary assignment notation, SimpleCookie
 664     calls the builtin str() to convert the value to a string.  Values
 665     received from HTTP are kept as strings.
 666     """
 667     def value_decode(self, val):
 668         return _unquote( val ), val
 669     def value_encode(self, val):
 670         strval = str(val)
 671         return strval, _quote( strval )
 672 # end SimpleCookie
 673
 674 class SerialCookie(BaseCookie):
 675     """SerialCookie
 676     SerialCookie supports arbitrary objects as cookie values. All
 677     values are serialized (using cPickle) before being sent to the
 678     client.  All incoming values are assumed to be valid Pickle
 679     representations.  IF AN INCOMING VALUE IS NOT IN A VALID PICKLE
 680     FORMAT, THEN AN EXCEPTION WILL BE RAISED.
 681
 682     Note: Large cookie values add overhead because they must be
 683     retransmitted on every HTTP transaction.
 684
 685     Note: HTTP has a 2k limit on the size of a cookie.  This class
 686     does not check for this limit, so be careful!!!
 687     """
 688     def value_decode(self, val):
 689         # This could raise an exception!
 690         return loads( _unquote(val) ), val
 691     def value_encode(self, val):
 692         return val, _quote( dumps(val) )
 693 # end SerialCookie
 694
 695 class SmartCookie(BaseCookie):
 696     """SmartCookie
 697     SmartCookie supports arbitrary objects as cookie values.  If the
 698     object is a string, then it is quoted.  If the object is not a
 699     string, however, then SmartCookie will use cPickle to serialize
 700     the object into a string representation.
 701
 702     Note: Large cookie values add overhead because they must be
 703     retransmitted on every HTTP transaction.
 704
 705     Note: HTTP has a 2k limit on the size of a cookie.  This class
 706     does not check for this limit, so be careful!!!
 707     """
 708     def value_decode(self, val):
 709         strval = _unquote(val)
 710         try:
 711             return loads(strval), val
 712         except:
 713             return strval, val
 714     def value_encode(self, val):
 715         if type(val) == type(""):
 716             return val, _quote(val)
 717         else:
 718             return val, _quote( dumps(val) )
 719 # end SmartCookie
 720
 721
 722 ###########################################################
 723 # Backwards Compatibility:  Don't break any existing code!
 724
 725 # We provide Cookie() as an alias for SmartCookie()
 726 Cookie = SmartCookie
 727
 728 #
 729 ###########################################################
 730
 731 def _test():
 732     import doctest, Cookie
 733     return doctest.testmod(Cookie)
 734
 735 if __name__ == "__main__":
 736     _test()
 737
 738
 739 #Local Variables:
 740 #tab-width: 4
 741 #end: