ยปCore Development>Code coverage>Lib/http/cookies.py

Python code coverage for Lib/http/cookies.py

#countcontent
1n/a####
2n/a# Copyright 2000 by Timothy O'Malley <timo@alum.mit.edu>
3n/a#
4n/a# All Rights Reserved
5n/a#
6n/a# Permission to use, copy, modify, and distribute this software
7n/a# and its documentation for any purpose and without fee is hereby
8n/a# granted, provided that the above copyright notice appear in all
9n/a# copies and that both that copyright notice and this permission
10n/a# notice appear in supporting documentation, and that the name of
11n/a# Timothy O'Malley not be used in advertising or publicity
12n/a# pertaining to distribution of the software without specific, written
13n/a# prior permission.
14n/a#
15n/a# Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
16n/a# SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
17n/a# AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
18n/a# ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19n/a# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
20n/a# WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
21n/a# ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22n/a# PERFORMANCE OF THIS SOFTWARE.
23n/a#
24n/a####
25n/a#
26n/a# Id: Cookie.py,v 2.29 2000/08/23 05:28:49 timo Exp
27n/a# by Timothy O'Malley <timo@alum.mit.edu>
28n/a#
29n/a# Cookie.py is a Python module for the handling of HTTP
30n/a# cookies as a Python dictionary. See RFC 2109 for more
31n/a# information on cookies.
32n/a#
33n/a# The original idea to treat Cookies as a dictionary came from
34n/a# Dave Mitchell (davem@magnet.com) in 1995, when he released the
35n/a# first version of nscookie.py.
36n/a#
37n/a####
38n/a
39n/ar"""
40n/aHere's a sample session to show how to use this module.
41n/aAt the moment, this is the only documentation.
42n/a
43n/aThe Basics
44n/a----------
45n/a
46n/aImporting is easy...
47n/a
48n/a >>> from http import cookies
49n/a
50n/aMost of the time you start by creating a cookie.
51n/a
52n/a >>> C = cookies.SimpleCookie()
53n/a
54n/aOnce you've created your Cookie, you can add values just as if it were
55n/aa dictionary.
56n/a
57n/a >>> C = cookies.SimpleCookie()
58n/a >>> C["fig"] = "newton"
59n/a >>> C["sugar"] = "wafer"
60n/a >>> C.output()
61n/a 'Set-Cookie: fig=newton\r\nSet-Cookie: sugar=wafer'
62n/a
63n/aNotice that the printable representation of a Cookie is the
64n/aappropriate format for a Set-Cookie: header. This is the
65n/adefault behavior. You can change the header and printed
66n/aattributes by using the .output() function
67n/a
68n/a >>> C = cookies.SimpleCookie()
69n/a >>> C["rocky"] = "road"
70n/a >>> C["rocky"]["path"] = "/cookie"
71n/a >>> print(C.output(header="Cookie:"))
72n/a Cookie: rocky=road; Path=/cookie
73n/a >>> print(C.output(attrs=[], header="Cookie:"))
74n/a Cookie: rocky=road
75n/a
76n/aThe load() method of a Cookie extracts cookies from a string. In a
77n/aCGI script, you would use this method to extract the cookies from the
78n/aHTTP_COOKIE environment variable.
79n/a
80n/a >>> C = cookies.SimpleCookie()
81n/a >>> C.load("chips=ahoy; vienna=finger")
82n/a >>> C.output()
83n/a 'Set-Cookie: chips=ahoy\r\nSet-Cookie: vienna=finger'
84n/a
85n/aThe load() method is darn-tootin smart about identifying cookies
86n/awithin a string. Escaped quotation marks, nested semicolons, and other
87n/asuch trickeries do not confuse it.
88n/a
89n/a >>> C = cookies.SimpleCookie()
90n/a >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
91n/a >>> print(C)
92n/a Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
93n/a
94n/aEach element of the Cookie also supports all of the RFC 2109
95n/aCookie attributes. Here's an example which sets the Path
96n/aattribute.
97n/a
98n/a >>> C = cookies.SimpleCookie()
99n/a >>> C["oreo"] = "doublestuff"
100n/a >>> C["oreo"]["path"] = "/"
101n/a >>> print(C)
102n/a Set-Cookie: oreo=doublestuff; Path=/
103n/a
104n/aEach dictionary element has a 'value' attribute, which gives you
105n/aback the value associated with the key.
106n/a
107n/a >>> C = cookies.SimpleCookie()
108n/a >>> C["twix"] = "none for you"
109n/a >>> C["twix"].value
110n/a 'none for you'
111n/a
112n/aThe SimpleCookie expects that all values should be standard strings.
113n/aJust to be sure, SimpleCookie invokes the str() builtin to convert
114n/athe value to a string, when the values are set dictionary-style.
115n/a
116n/a >>> C = cookies.SimpleCookie()
117n/a >>> C["number"] = 7
118n/a >>> C["string"] = "seven"
119n/a >>> C["number"].value
120n/a '7'
121n/a >>> C["string"].value
122n/a 'seven'
123n/a >>> C.output()
124n/a 'Set-Cookie: number=7\r\nSet-Cookie: string=seven'
125n/a
126n/aFinis.
127n/a"""
128n/a
129n/a#
130n/a# Import our required modules
131n/a#
132n/aimport re
133n/aimport string
134n/a
135n/a__all__ = ["CookieError", "BaseCookie", "SimpleCookie"]
136n/a
137n/a_nulljoin = ''.join
138n/a_semispacejoin = '; '.join
139n/a_spacejoin = ' '.join
140n/a
141n/a#
142n/a# Define an exception visible to External modules
143n/a#
144n/aclass CookieError(Exception):
145n/a pass
146n/a
147n/a
148n/a# These quoting routines conform to the RFC2109 specification, which in
149n/a# turn references the character definitions from RFC2068. They provide
150n/a# a two-way quoting algorithm. Any non-text character is translated
151n/a# into a 4 character sequence: a forward-slash followed by the
152n/a# three-digit octal equivalent of the character. Any '\' or '"' is
153n/a# quoted with a preceding '\' slash.
154n/a# Because of the way browsers really handle cookies (as opposed to what
155n/a# the RFC says) we also encode "," and ";".
156n/a#
157n/a# These are taken from RFC2068 and RFC2109.
158n/a# _LegalChars is the list of chars which don't require "'s
159n/a# _Translator hash-table for fast quoting
160n/a#
161n/a_LegalChars = string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~:"
162n/a_UnescapedChars = _LegalChars + ' ()/<=>?@[]{}'
163n/a
164n/a_Translator = {n: '\\%03o' % n
165n/a for n in set(range(256)) - set(map(ord, _UnescapedChars))}
166n/a_Translator.update({
167n/a ord('"'): '\\"',
168n/a ord('\\'): '\\\\',
169n/a})
170n/a
171n/a_is_legal_key = re.compile('[%s]+' % re.escape(_LegalChars)).fullmatch
172n/a
173n/adef _quote(str):
174n/a r"""Quote a string for use in a cookie header.
175n/a
176n/a If the string does not need to be double-quoted, then just return the
177n/a string. Otherwise, surround the string in doublequotes and quote
178n/a (with a \) special characters.
179n/a """
180n/a if str is None or _is_legal_key(str):
181n/a return str
182n/a else:
183n/a return '"' + str.translate(_Translator) + '"'
184n/a
185n/a
186n/a_OctalPatt = re.compile(r"\\[0-3][0-7][0-7]")
187n/a_QuotePatt = re.compile(r"[\\].")
188n/a
189n/adef _unquote(str):
190n/a # If there aren't any doublequotes,
191n/a # then there can't be any special characters. See RFC 2109.
192n/a if str is None or len(str) < 2:
193n/a return str
194n/a if str[0] != '"' or str[-1] != '"':
195n/a return str
196n/a
197n/a # We have to assume that we must decode this string.
198n/a # Down to work.
199n/a
200n/a # Remove the "s
201n/a str = str[1:-1]
202n/a
203n/a # Check for special sequences. Examples:
204n/a # \012 --> \n
205n/a # \" --> "
206n/a #
207n/a i = 0
208n/a n = len(str)
209n/a res = []
210n/a while 0 <= i < n:
211n/a o_match = _OctalPatt.search(str, i)
212n/a q_match = _QuotePatt.search(str, i)
213n/a if not o_match and not q_match: # Neither matched
214n/a res.append(str[i:])
215n/a break
216n/a # else:
217n/a j = k = -1
218n/a if o_match:
219n/a j = o_match.start(0)
220n/a if q_match:
221n/a k = q_match.start(0)
222n/a if q_match and (not o_match or k < j): # QuotePatt matched
223n/a res.append(str[i:k])
224n/a res.append(str[k+1])
225n/a i = k + 2
226n/a else: # OctalPatt matched
227n/a res.append(str[i:j])
228n/a res.append(chr(int(str[j+1:j+4], 8)))
229n/a i = j + 4
230n/a return _nulljoin(res)
231n/a
232n/a# The _getdate() routine is used to set the expiration time in the cookie's HTTP
233n/a# header. By default, _getdate() returns the current time in the appropriate
234n/a# "expires" format for a Set-Cookie header. The one optional argument is an
235n/a# offset from now, in seconds. For example, an offset of -3600 means "one hour
236n/a# ago". The offset may be a floating point number.
237n/a#
238n/a
239n/a_weekdayname = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
240n/a
241n/a_monthname = [None,
242n/a 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
243n/a 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
244n/a
245n/adef _getdate(future=0, weekdayname=_weekdayname, monthname=_monthname):
246n/a from time import gmtime, time
247n/a now = time()
248n/a year, month, day, hh, mm, ss, wd, y, z = gmtime(now + future)
249n/a return "%s, %02d %3s %4d %02d:%02d:%02d GMT" % \
250n/a (weekdayname[wd], day, monthname[month], year, hh, mm, ss)
251n/a
252n/a
253n/aclass Morsel(dict):
254n/a """A class to hold ONE (key, value) pair.
255n/a
256n/a In a cookie, each such pair may have several attributes, so this class is
257n/a used to keep the attributes associated with the appropriate key,value pair.
258n/a This class also includes a coded_value attribute, which is used to hold
259n/a the network representation of the value. This is most useful when Python
260n/a objects are pickled for network transit.
261n/a """
262n/a # RFC 2109 lists these attributes as reserved:
263n/a # path comment domain
264n/a # max-age secure version
265n/a #
266n/a # For historical reasons, these attributes are also reserved:
267n/a # expires
268n/a #
269n/a # This is an extension from Microsoft:
270n/a # httponly
271n/a #
272n/a # This dictionary provides a mapping from the lowercase
273n/a # variant on the left to the appropriate traditional
274n/a # formatting on the right.
275n/a _reserved = {
276n/a "expires" : "expires",
277n/a "path" : "Path",
278n/a "comment" : "Comment",
279n/a "domain" : "Domain",
280n/a "max-age" : "Max-Age",
281n/a "secure" : "Secure",
282n/a "httponly" : "HttpOnly",
283n/a "version" : "Version",
284n/a }
285n/a
286n/a _flags = {'secure', 'httponly'}
287n/a
288n/a def __init__(self):
289n/a # Set defaults
290n/a self._key = self._value = self._coded_value = None
291n/a
292n/a # Set default attributes
293n/a for key in self._reserved:
294n/a dict.__setitem__(self, key, "")
295n/a
296n/a @property
297n/a def key(self):
298n/a return self._key
299n/a
300n/a @property
301n/a def value(self):
302n/a return self._value
303n/a
304n/a @property
305n/a def coded_value(self):
306n/a return self._coded_value
307n/a
308n/a def __setitem__(self, K, V):
309n/a K = K.lower()
310n/a if not K in self._reserved:
311n/a raise CookieError("Invalid attribute %r" % (K,))
312n/a dict.__setitem__(self, K, V)
313n/a
314n/a def setdefault(self, key, val=None):
315n/a key = key.lower()
316n/a if key not in self._reserved:
317n/a raise CookieError("Invalid attribute %r" % (key,))
318n/a return dict.setdefault(self, key, val)
319n/a
320n/a def __eq__(self, morsel):
321n/a if not isinstance(morsel, Morsel):
322n/a return NotImplemented
323n/a return (dict.__eq__(self, morsel) and
324n/a self._value == morsel._value and
325n/a self._key == morsel._key and
326n/a self._coded_value == morsel._coded_value)
327n/a
328n/a __ne__ = object.__ne__
329n/a
330n/a def copy(self):
331n/a morsel = Morsel()
332n/a dict.update(morsel, self)
333n/a morsel.__dict__.update(self.__dict__)
334n/a return morsel
335n/a
336n/a def update(self, values):
337n/a data = {}
338n/a for key, val in dict(values).items():
339n/a key = key.lower()
340n/a if key not in self._reserved:
341n/a raise CookieError("Invalid attribute %r" % (key,))
342n/a data[key] = val
343n/a dict.update(self, data)
344n/a
345n/a def isReservedKey(self, K):
346n/a return K.lower() in self._reserved
347n/a
348n/a def set(self, key, val, coded_val):
349n/a if key.lower() in self._reserved:
350n/a raise CookieError('Attempt to set a reserved key %r' % (key,))
351n/a if not _is_legal_key(key):
352n/a raise CookieError('Illegal key %r' % (key,))
353n/a
354n/a # It's a good key, so save it.
355n/a self._key = key
356n/a self._value = val
357n/a self._coded_value = coded_val
358n/a
359n/a def __getstate__(self):
360n/a return {
361n/a 'key': self._key,
362n/a 'value': self._value,
363n/a 'coded_value': self._coded_value,
364n/a }
365n/a
366n/a def __setstate__(self, state):
367n/a self._key = state['key']
368n/a self._value = state['value']
369n/a self._coded_value = state['coded_value']
370n/a
371n/a def output(self, attrs=None, header="Set-Cookie:"):
372n/a return "%s %s" % (header, self.OutputString(attrs))
373n/a
374n/a __str__ = output
375n/a
376n/a def __repr__(self):
377n/a return '<%s: %s>' % (self.__class__.__name__, self.OutputString())
378n/a
379n/a def js_output(self, attrs=None):
380n/a # Print javascript
381n/a return """
382n/a <script type="text/javascript">
383n/a <!-- begin hiding
384n/a document.cookie = \"%s\";
385n/a // end hiding -->
386n/a </script>
387n/a """ % (self.OutputString(attrs).replace('"', r'\"'))
388n/a
389n/a def OutputString(self, attrs=None):
390n/a # Build up our result
391n/a #
392n/a result = []
393n/a append = result.append
394n/a
395n/a # First, the key=value pair
396n/a append("%s=%s" % (self.key, self.coded_value))
397n/a
398n/a # Now add any defined attributes
399n/a if attrs is None:
400n/a attrs = self._reserved
401n/a items = sorted(self.items())
402n/a for key, value in items:
403n/a if value == "":
404n/a continue
405n/a if key not in attrs:
406n/a continue
407n/a if key == "expires" and isinstance(value, int):
408n/a append("%s=%s" % (self._reserved[key], _getdate(value)))
409n/a elif key == "max-age" and isinstance(value, int):
410n/a append("%s=%d" % (self._reserved[key], value))
411n/a elif key in self._flags:
412n/a if value:
413n/a append(str(self._reserved[key]))
414n/a else:
415n/a append("%s=%s" % (self._reserved[key], value))
416n/a
417n/a # Return the result
418n/a return _semispacejoin(result)
419n/a
420n/a
421n/a#
422n/a# Pattern for finding cookie
423n/a#
424n/a# This used to be strict parsing based on the RFC2109 and RFC2068
425n/a# specifications. I have since discovered that MSIE 3.0x doesn't
426n/a# follow the character rules outlined in those specs. As a
427n/a# result, the parsing rules here are less strict.
428n/a#
429n/a
430n/a_LegalKeyChars = r"\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\="
431n/a_LegalValueChars = _LegalKeyChars + r'\[\]'
432n/a_CookiePattern = re.compile(r"""
433n/a \s* # Optional whitespace at start of cookie
434n/a (?P<key> # Start of group 'key'
435n/a [""" + _LegalKeyChars + r"""]+? # Any word of at least one letter
436n/a ) # End of group 'key'
437n/a ( # Optional group: there may not be a value.
438n/a \s*=\s* # Equal Sign
439n/a (?P<val> # Start of group 'val'
440n/a "(?:[^\\"]|\\.)*" # Any doublequoted string
441n/a | # or
442n/a \w{3},\s[\w\d\s-]{9,11}\s[\d:]{8}\sGMT # Special case for "expires" attr
443n/a | # or
444n/a [""" + _LegalValueChars + r"""]* # Any word or empty string
445n/a ) # End of group 'val'
446n/a )? # End of optional value group
447n/a \s* # Any number of spaces.
448n/a (\s+|;|$) # Ending either at space, semicolon, or EOS.
449n/a """, re.ASCII | re.VERBOSE) # re.ASCII may be removed if safe.
450n/a
451n/a
452n/a# At long last, here is the cookie class. Using this class is almost just like
453n/a# using a dictionary. See this module's docstring for example usage.
454n/a#
455n/aclass BaseCookie(dict):
456n/a """A container class for a set of Morsels."""
457n/a
458n/a def value_decode(self, val):
459n/a """real_value, coded_value = value_decode(STRING)
460n/a Called prior to setting a cookie's value from the network
461n/a representation. The VALUE is the value read from HTTP
462n/a header.
463n/a Override this function to modify the behavior of cookies.
464n/a """
465n/a return val, val
466n/a
467n/a def value_encode(self, val):
468n/a """real_value, coded_value = value_encode(VALUE)
469n/a Called prior to setting a cookie's value from the dictionary
470n/a representation. The VALUE is the value being assigned.
471n/a Override this function to modify the behavior of cookies.
472n/a """
473n/a strval = str(val)
474n/a return strval, strval
475n/a
476n/a def __init__(self, input=None):
477n/a if input:
478n/a self.load(input)
479n/a
480n/a def __set(self, key, real_value, coded_value):
481n/a """Private method for setting a cookie's value"""
482n/a M = self.get(key, Morsel())
483n/a M.set(key, real_value, coded_value)
484n/a dict.__setitem__(self, key, M)
485n/a
486n/a def __setitem__(self, key, value):
487n/a """Dictionary style assignment."""
488n/a if isinstance(value, Morsel):
489n/a # allow assignment of constructed Morsels (e.g. for pickling)
490n/a dict.__setitem__(self, key, value)
491n/a else:
492n/a rval, cval = self.value_encode(value)
493n/a self.__set(key, rval, cval)
494n/a
495n/a def output(self, attrs=None, header="Set-Cookie:", sep="\015\012"):
496n/a """Return a string suitable for HTTP."""
497n/a result = []
498n/a items = sorted(self.items())
499n/a for key, value in items:
500n/a result.append(value.output(attrs, header))
501n/a return sep.join(result)
502n/a
503n/a __str__ = output
504n/a
505n/a def __repr__(self):
506n/a l = []
507n/a items = sorted(self.items())
508n/a for key, value in items:
509n/a l.append('%s=%s' % (key, repr(value.value)))
510n/a return '<%s: %s>' % (self.__class__.__name__, _spacejoin(l))
511n/a
512n/a def js_output(self, attrs=None):
513n/a """Return a string suitable for JavaScript."""
514n/a result = []
515n/a items = sorted(self.items())
516n/a for key, value in items:
517n/a result.append(value.js_output(attrs))
518n/a return _nulljoin(result)
519n/a
520n/a def load(self, rawdata):
521n/a """Load cookies from a string (presumably HTTP_COOKIE) or
522n/a from a dictionary. Loading cookies from a dictionary 'd'
523n/a is equivalent to calling:
524n/a map(Cookie.__setitem__, d.keys(), d.values())
525n/a """
526n/a if isinstance(rawdata, str):
527n/a self.__parse_string(rawdata)
528n/a else:
529n/a # self.update() wouldn't call our custom __setitem__
530n/a for key, value in rawdata.items():
531n/a self[key] = value
532n/a return
533n/a
534n/a def __parse_string(self, str, patt=_CookiePattern):
535n/a i = 0 # Our starting point
536n/a n = len(str) # Length of string
537n/a parsed_items = [] # Parsed (type, key, value) triples
538n/a morsel_seen = False # A key=value pair was previously encountered
539n/a
540n/a TYPE_ATTRIBUTE = 1
541n/a TYPE_KEYVALUE = 2
542n/a
543n/a # We first parse the whole cookie string and reject it if it's
544n/a # syntactically invalid (this helps avoid some classes of injection
545n/a # attacks).
546n/a while 0 <= i < n:
547n/a # Start looking for a cookie
548n/a match = patt.match(str, i)
549n/a if not match:
550n/a # No more cookies
551n/a break
552n/a
553n/a key, value = match.group("key"), match.group("val")
554n/a i = match.end(0)
555n/a
556n/a if key[0] == "$":
557n/a if not morsel_seen:
558n/a # We ignore attributes which pertain to the cookie
559n/a # mechanism as a whole, such as "$Version".
560n/a # See RFC 2965. (Does anyone care?)
561n/a continue
562n/a parsed_items.append((TYPE_ATTRIBUTE, key[1:], value))
563n/a elif key.lower() in Morsel._reserved:
564n/a if not morsel_seen:
565n/a # Invalid cookie string
566n/a return
567n/a if value is None:
568n/a if key.lower() in Morsel._flags:
569n/a parsed_items.append((TYPE_ATTRIBUTE, key, True))
570n/a else:
571n/a # Invalid cookie string
572n/a return
573n/a else:
574n/a parsed_items.append((TYPE_ATTRIBUTE, key, _unquote(value)))
575n/a elif value is not None:
576n/a parsed_items.append((TYPE_KEYVALUE, key, self.value_decode(value)))
577n/a morsel_seen = True
578n/a else:
579n/a # Invalid cookie string
580n/a return
581n/a
582n/a # The cookie string is valid, apply it.
583n/a M = None # current morsel
584n/a for tp, key, value in parsed_items:
585n/a if tp == TYPE_ATTRIBUTE:
586n/a assert M is not None
587n/a M[key] = value
588n/a else:
589n/a assert tp == TYPE_KEYVALUE
590n/a rval, cval = value
591n/a self.__set(key, rval, cval)
592n/a M = self[key]
593n/a
594n/a
595n/aclass SimpleCookie(BaseCookie):
596n/a """
597n/a SimpleCookie supports strings as cookie values. When setting
598n/a the value using the dictionary assignment notation, SimpleCookie
599n/a calls the builtin str() to convert the value to a string. Values
600n/a received from HTTP are kept as strings.
601n/a """
602n/a def value_decode(self, val):
603n/a return _unquote(val), val
604n/a
605n/a def value_encode(self, val):
606n/a strval = str(val)
607n/a return strval, _quote(strval)