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