blob: 3ec90184beefb75c75a1d22cbedbca19dc8a9abd [file] [log] [blame]
Guido van Rossumb51eaa11997-03-07 00:21:55 +00001"""Tokenization help for Python programs.
Guido van Rossum4d8e8591992-01-01 19:34:47 +00002
Florent Xicluna43e4ea12010-09-03 19:54:02 +00003tokenize(readline) is a generator that breaks a stream of bytes into
4Python tokens. It decodes the bytes according to PEP-0263 for
5determining source file encoding.
Trent Nelson428de652008-03-18 22:41:35 +00006
Florent Xicluna43e4ea12010-09-03 19:54:02 +00007It accepts a readline-like method which is called repeatedly to get the
8next line of input (or b"" for EOF). It generates 5-tuples with these
9members:
Tim Peters4efb6e92001-06-29 23:51:08 +000010
11 the token type (see token.py)
12 the token (a string)
13 the starting (row, column) indices of the token (a 2-tuple of ints)
14 the ending (row, column) indices of the token (a 2-tuple of ints)
15 the original line (string)
16
17It is designed to match the working of the Python tokenizer exactly, except
18that it produces COMMENT tokens for comments and gives type OP for all
Florent Xicluna43e4ea12010-09-03 19:54:02 +000019operators. Additionally, all token lists start with an ENCODING token
20which tells you which encoding was used to decode the bytes stream.
21"""
Guido van Rossumb51eaa11997-03-07 00:21:55 +000022
Ka-Ping Yee244c5932001-03-01 13:56:40 +000023__author__ = 'Ka-Ping Yee <ping@lfw.org>'
Trent Nelson428de652008-03-18 22:41:35 +000024__credits__ = ('GvR, ESR, Tim Peters, Thomas Wouters, Fred Drake, '
25 'Skip Montanaro, Raymond Hettinger, Trent Nelson, '
26 'Michael Foord')
Serhiy Storchakacf4a2f22015-03-11 17:18:03 +020027from builtins import open as _builtin_open
Benjamin Peterson433f32c2008-12-12 01:25:05 +000028from codecs import lookup, BOM_UTF8
Raymond Hettinger3fb79c72010-09-09 07:15:18 +000029import collections
Victor Stinner58c07522010-11-09 01:08:59 +000030from io import TextIOWrapper
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -050031from itertools import chain
32import re
33import sys
34from token import *
35
Serhiy Storchakadafea852013-09-16 23:51:56 +030036cookie_re = re.compile(r'^[ \t\f]*#.*coding[:=][ \t]*([-\w.]+)', re.ASCII)
Serhiy Storchaka768c16c2014-01-09 18:36:09 +020037blank_re = re.compile(br'^[ \t\f]*(?:[#\r\n]|$)', re.ASCII)
Guido van Rossum4d8e8591992-01-01 19:34:47 +000038
Skip Montanaro40fc1602001-03-01 04:27:19 +000039import token
Alexander Belopolskyb9d10d02010-11-11 14:07:41 +000040__all__ = token.__all__ + ["COMMENT", "tokenize", "detect_encoding",
41 "NL", "untokenize", "ENCODING", "TokenInfo"]
Skip Montanaro40fc1602001-03-01 04:27:19 +000042del token
43
Guido van Rossum1aec3231997-04-08 14:24:39 +000044COMMENT = N_TOKENS
45tok_name[COMMENT] = 'COMMENT'
Guido van Rossuma90c78b1998-04-03 16:05:38 +000046NL = N_TOKENS + 1
47tok_name[NL] = 'NL'
Trent Nelson428de652008-03-18 22:41:35 +000048ENCODING = N_TOKENS + 2
49tok_name[ENCODING] = 'ENCODING'
50N_TOKENS += 3
Meador Inge00c7f852012-01-19 00:44:45 -060051EXACT_TOKEN_TYPES = {
52 '(': LPAR,
53 ')': RPAR,
54 '[': LSQB,
55 ']': RSQB,
56 ':': COLON,
57 ',': COMMA,
58 ';': SEMI,
59 '+': PLUS,
60 '-': MINUS,
61 '*': STAR,
62 '/': SLASH,
63 '|': VBAR,
64 '&': AMPER,
65 '<': LESS,
66 '>': GREATER,
67 '=': EQUAL,
68 '.': DOT,
69 '%': PERCENT,
70 '{': LBRACE,
71 '}': RBRACE,
72 '==': EQEQUAL,
73 '!=': NOTEQUAL,
74 '<=': LESSEQUAL,
75 '>=': GREATEREQUAL,
76 '~': TILDE,
77 '^': CIRCUMFLEX,
78 '<<': LEFTSHIFT,
79 '>>': RIGHTSHIFT,
80 '**': DOUBLESTAR,
81 '+=': PLUSEQUAL,
82 '-=': MINEQUAL,
83 '*=': STAREQUAL,
84 '/=': SLASHEQUAL,
85 '%=': PERCENTEQUAL,
86 '&=': AMPEREQUAL,
87 '|=': VBAREQUAL,
88 '^=': CIRCUMFLEXEQUAL,
89 '<<=': LEFTSHIFTEQUAL,
90 '>>=': RIGHTSHIFTEQUAL,
91 '**=': DOUBLESTAREQUAL,
92 '//': DOUBLESLASH,
93 '//=': DOUBLESLASHEQUAL,
Benjamin Petersond51374e2014-04-09 23:55:56 -040094 '@': AT,
95 '@=': ATEQUAL,
Meador Inge00c7f852012-01-19 00:44:45 -060096}
Guido van Rossum1aec3231997-04-08 14:24:39 +000097
Raymond Hettinger3fb79c72010-09-09 07:15:18 +000098class TokenInfo(collections.namedtuple('TokenInfo', 'type string start end line')):
Raymond Hettingeraa17a7f2009-04-29 14:21:25 +000099 def __repr__(self):
Raymond Hettingera0e79402010-09-09 08:29:05 +0000100 annotated_type = '%d (%s)' % (self.type, tok_name[self.type])
101 return ('TokenInfo(type=%s, string=%r, start=%r, end=%r, line=%r)' %
102 self._replace(type=annotated_type))
Raymond Hettingeraa17a7f2009-04-29 14:21:25 +0000103
Meador Inge00c7f852012-01-19 00:44:45 -0600104 @property
105 def exact_type(self):
106 if self.type == OP and self.string in EXACT_TOKEN_TYPES:
107 return EXACT_TOKEN_TYPES[self.string]
108 else:
109 return self.type
110
Eric S. Raymondb08b2d32001-02-09 11:10:16 +0000111def group(*choices): return '(' + '|'.join(choices) + ')'
Guido van Rossum68468eb2003-02-27 20:14:51 +0000112def any(*choices): return group(*choices) + '*'
113def maybe(*choices): return group(*choices) + '?'
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000114
Antoine Pitroufd036452008-08-19 17:56:33 +0000115# Note: we use unicode matching for names ("\w") but ascii matching for
116# number literals.
Guido van Rossum3b631771997-10-27 20:44:15 +0000117Whitespace = r'[ \f\t]*'
118Comment = r'#[^\r\n]*'
119Ignore = Whitespace + any(r'\\\r?\n' + Whitespace) + maybe(Comment)
Benjamin Peterson33856de2010-08-30 14:41:20 +0000120Name = r'\w+'
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000121
Antoine Pitroufd036452008-08-19 17:56:33 +0000122Hexnumber = r'0[xX][0-9a-fA-F]+'
Georg Brandlfceab5a2008-01-19 20:08:23 +0000123Binnumber = r'0[bB][01]+'
124Octnumber = r'0[oO][0-7]+'
Antoine Pitroufd036452008-08-19 17:56:33 +0000125Decnumber = r'(?:0+|[1-9][0-9]*)'
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000126Intnumber = group(Hexnumber, Binnumber, Octnumber, Decnumber)
Antoine Pitroufd036452008-08-19 17:56:33 +0000127Exponent = r'[eE][-+]?[0-9]+'
128Pointfloat = group(r'[0-9]+\.[0-9]*', r'\.[0-9]+') + maybe(Exponent)
129Expfloat = r'[0-9]+' + Exponent
Guido van Rossum1aec3231997-04-08 14:24:39 +0000130Floatnumber = group(Pointfloat, Expfloat)
Antoine Pitroufd036452008-08-19 17:56:33 +0000131Imagnumber = group(r'[0-9]+[jJ]', Floatnumber + r'[jJ]')
Guido van Rossum1aec3231997-04-08 14:24:39 +0000132Number = group(Imagnumber, Floatnumber, Intnumber)
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000133
Christian Heimes0b3847d2012-06-20 11:17:58 +0200134StringPrefix = r'(?:[bB][rR]?|[rR][bB]?|[uU])?'
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000135
Tim Petersde495832000-10-07 05:09:39 +0000136# Tail end of ' string.
137Single = r"[^'\\]*(?:\\.[^'\\]*)*'"
138# Tail end of " string.
139Double = r'[^"\\]*(?:\\.[^"\\]*)*"'
140# Tail end of ''' string.
141Single3 = r"[^'\\]*(?:(?:\\.|'(?!''))[^'\\]*)*'''"
142# Tail end of """ string.
143Double3 = r'[^"\\]*(?:(?:\\.|"(?!""))[^"\\]*)*"""'
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000144Triple = group(StringPrefix + "'''", StringPrefix + '"""')
Tim Petersde495832000-10-07 05:09:39 +0000145# Single-line ' or " string.
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000146String = group(StringPrefix + r"'[^\n'\\]*(?:\\.[^\n'\\]*)*'",
147 StringPrefix + r'"[^\n"\\]*(?:\\.[^\n"\\]*)*"')
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000148
Tim Petersde495832000-10-07 05:09:39 +0000149# Because of leftmost-then-longest match semantics, be sure to put the
150# longest operators first (e.g., if = came before ==, == would get
151# recognized as two instances of =).
Guido van Rossumb053cd82006-08-24 03:53:23 +0000152Operator = group(r"\*\*=?", r">>=?", r"<<=?", r"!=",
Neal Norwitzc1505362006-12-28 06:47:50 +0000153 r"//=?", r"->",
Benjamin Petersond51374e2014-04-09 23:55:56 -0400154 r"[+\-*/%&@|^=<>]=?",
Tim Petersde495832000-10-07 05:09:39 +0000155 r"~")
Thomas Wouterse1519a12000-08-24 21:44:52 +0000156
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000157Bracket = '[][(){}]'
Georg Brandldde00282007-03-18 19:01:53 +0000158Special = group(r'\r?\n', r'\.\.\.', r'[:;.,@]')
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000159Funny = group(Operator, Bracket, Special)
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000160
Guido van Rossum3b631771997-10-27 20:44:15 +0000161PlainToken = group(Number, Funny, String, Name)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000162Token = Ignore + PlainToken
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000163
Tim Petersde495832000-10-07 05:09:39 +0000164# First (or only) line of ' or " string.
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000165ContStr = group(StringPrefix + r"'[^\n'\\]*(?:\\.[^\n'\\]*)*" +
Ka-Ping Yee1ff08b12001-01-15 22:04:30 +0000166 group("'", r'\\\r?\n'),
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000167 StringPrefix + r'"[^\n"\\]*(?:\\.[^\n"\\]*)*' +
Ka-Ping Yee1ff08b12001-01-15 22:04:30 +0000168 group('"', r'\\\r?\n'))
Ezio Melotti2cc3b4b2012-11-03 17:38:43 +0200169PseudoExtras = group(r'\\\r?\n|\Z', Comment, Triple)
Guido van Rossum3b631771997-10-27 20:44:15 +0000170PseudoToken = Whitespace + group(PseudoExtras, Number, Funny, ContStr, Name)
Guido van Rossum1aec3231997-04-08 14:24:39 +0000171
Benjamin Peterson33856de2010-08-30 14:41:20 +0000172def _compile(expr):
173 return re.compile(expr, re.UNICODE)
174
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200175endpats = {"'": Single, '"': Double,
176 "'''": Single3, '"""': Double3,
177 "r'''": Single3, 'r"""': Double3,
178 "b'''": Single3, 'b"""': Double3,
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200179 "R'''": Single3, 'R"""': Double3,
180 "B'''": Single3, 'B"""': Double3,
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000181 "br'''": Single3, 'br"""': Double3,
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200182 "bR'''": Single3, 'bR"""': Double3,
183 "Br'''": Single3, 'Br"""': Double3,
184 "BR'''": Single3, 'BR"""': Double3,
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000185 "rb'''": Single3, 'rb"""': Double3,
186 "Rb'''": Single3, 'Rb"""': Double3,
187 "rB'''": Single3, 'rB"""': Double3,
188 "RB'''": Single3, 'RB"""': Double3,
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000189 "u'''": Single3, 'u"""': Double3,
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000190 "U'''": Single3, 'U"""': Double3,
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000191 'r': None, 'R': None, 'b': None, 'B': None,
192 'u': None, 'U': None}
Guido van Rossum4d8e8591992-01-01 19:34:47 +0000193
Guido van Rossum9d6897a2002-08-24 06:54:19 +0000194triple_quoted = {}
195for t in ("'''", '"""',
196 "r'''", 'r"""', "R'''", 'R"""',
Guido van Rossum4fe72f92007-11-12 17:40:10 +0000197 "b'''", 'b"""', "B'''", 'B"""',
198 "br'''", 'br"""', "Br'''", 'Br"""',
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000199 "bR'''", 'bR"""', "BR'''", 'BR"""',
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000200 "rb'''", 'rb"""', "rB'''", 'rB"""',
201 "Rb'''", 'Rb"""', "RB'''", 'RB"""',
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000202 "u'''", 'u"""', "U'''", 'U"""',
Christian Heimes0b3847d2012-06-20 11:17:58 +0200203 ):
Guido van Rossum9d6897a2002-08-24 06:54:19 +0000204 triple_quoted[t] = t
205single_quoted = {}
206for t in ("'", '"',
207 "r'", 'r"', "R'", 'R"',
Guido van Rossum4fe72f92007-11-12 17:40:10 +0000208 "b'", 'b"', "B'", 'B"',
209 "br'", 'br"', "Br'", 'Br"',
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000210 "bR'", 'bR"', "BR'", 'BR"' ,
Armin Ronacherc0eaeca2012-03-04 13:07:57 +0000211 "rb'", 'rb"', "rB'", 'rB"',
212 "Rb'", 'Rb"', "RB'", 'RB"' ,
Armin Ronacher6ecf77b2012-03-04 12:04:06 +0000213 "u'", 'u"', "U'", 'U"',
Christian Heimes0b3847d2012-06-20 11:17:58 +0200214 ):
Guido van Rossum9d6897a2002-08-24 06:54:19 +0000215 single_quoted[t] = t
216
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000217tabsize = 8
Fred Drake9b8d8012000-08-17 04:45:13 +0000218
Ka-Ping Yee28c62bb2001-03-23 05:22:49 +0000219class TokenError(Exception): pass
220
221class StopTokenizing(Exception): pass
Fred Drake9b8d8012000-08-17 04:45:13 +0000222
Tim Peters5ca576e2001-06-18 22:08:13 +0000223
Thomas Wouters89f507f2006-12-13 04:49:30 +0000224class Untokenizer:
225
226 def __init__(self):
227 self.tokens = []
228 self.prev_row = 1
229 self.prev_col = 0
Trent Nelson428de652008-03-18 22:41:35 +0000230 self.encoding = None
Thomas Wouters89f507f2006-12-13 04:49:30 +0000231
232 def add_whitespace(self, start):
233 row, col = start
Terry Jan Reedy5e6db312014-02-17 16:45:48 -0500234 if row < self.prev_row or row == self.prev_row and col < self.prev_col:
235 raise ValueError("start ({},{}) precedes previous end ({},{})"
236 .format(row, col, self.prev_row, self.prev_col))
Terry Jan Reedy9dc3a362014-02-23 23:33:08 -0500237 row_offset = row - self.prev_row
Terry Jan Reedyf106f8f2014-02-23 23:39:57 -0500238 if row_offset:
Terry Jan Reedy9dc3a362014-02-23 23:33:08 -0500239 self.tokens.append("\\\n" * row_offset)
240 self.prev_col = 0
Thomas Wouters89f507f2006-12-13 04:49:30 +0000241 col_offset = col - self.prev_col
242 if col_offset:
243 self.tokens.append(" " * col_offset)
244
245 def untokenize(self, iterable):
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -0500246 it = iter(iterable)
Dingyuan Wange411b662015-06-22 10:01:12 +0800247 indents = []
248 startline = False
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -0500249 for t in it:
Thomas Wouters89f507f2006-12-13 04:49:30 +0000250 if len(t) == 2:
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -0500251 self.compat(t, it)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000252 break
253 tok_type, token, start, end, line = t
Trent Nelson428de652008-03-18 22:41:35 +0000254 if tok_type == ENCODING:
255 self.encoding = token
256 continue
Terry Jan Reedy9dc3a362014-02-23 23:33:08 -0500257 if tok_type == ENDMARKER:
258 break
Dingyuan Wange411b662015-06-22 10:01:12 +0800259 if tok_type == INDENT:
260 indents.append(token)
261 continue
262 elif tok_type == DEDENT:
263 indents.pop()
264 self.prev_row, self.prev_col = end
265 continue
266 elif tok_type in (NEWLINE, NL):
267 startline = True
268 elif startline and indents:
269 indent = indents[-1]
270 if start[1] >= len(indent):
271 self.tokens.append(indent)
272 self.prev_col = len(indent)
273 startline = False
Thomas Wouters89f507f2006-12-13 04:49:30 +0000274 self.add_whitespace(start)
275 self.tokens.append(token)
276 self.prev_row, self.prev_col = end
277 if tok_type in (NEWLINE, NL):
278 self.prev_row += 1
279 self.prev_col = 0
280 return "".join(self.tokens)
281
282 def compat(self, token, iterable):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000283 indents = []
284 toks_append = self.tokens.append
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -0500285 startline = token[0] in (NEWLINE, NL)
Christian Heimesba4af492008-03-28 00:55:15 +0000286 prevstring = False
Terry Jan Reedy5b8d2c32014-02-17 23:12:16 -0500287
288 for tok in chain([token], iterable):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000289 toknum, tokval = tok[:2]
Trent Nelson428de652008-03-18 22:41:35 +0000290 if toknum == ENCODING:
291 self.encoding = tokval
292 continue
Thomas Wouters89f507f2006-12-13 04:49:30 +0000293
Yury Selivanov75445082015-05-11 22:57:16 -0400294 if toknum in (NAME, NUMBER, ASYNC, AWAIT):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000295 tokval += ' '
296
Christian Heimesba4af492008-03-28 00:55:15 +0000297 # Insert a space between two consecutive strings
298 if toknum == STRING:
299 if prevstring:
300 tokval = ' ' + tokval
301 prevstring = True
302 else:
303 prevstring = False
304
Thomas Wouters89f507f2006-12-13 04:49:30 +0000305 if toknum == INDENT:
306 indents.append(tokval)
307 continue
308 elif toknum == DEDENT:
309 indents.pop()
310 continue
311 elif toknum in (NEWLINE, NL):
312 startline = True
313 elif startline and indents:
314 toks_append(indents[-1])
315 startline = False
316 toks_append(tokval)
Raymond Hettinger68c04532005-06-10 11:05:19 +0000317
Trent Nelson428de652008-03-18 22:41:35 +0000318
Raymond Hettinger68c04532005-06-10 11:05:19 +0000319def untokenize(iterable):
320 """Transform tokens back into Python source code.
Trent Nelson428de652008-03-18 22:41:35 +0000321 It returns a bytes object, encoded using the ENCODING
322 token, which is the first token sequence output by tokenize.
Raymond Hettinger68c04532005-06-10 11:05:19 +0000323
324 Each element returned by the iterable must be a token sequence
Thomas Wouters89f507f2006-12-13 04:49:30 +0000325 with at least two elements, a token number and token value. If
326 only two tokens are passed, the resulting output is poor.
Raymond Hettinger68c04532005-06-10 11:05:19 +0000327
Thomas Wouters89f507f2006-12-13 04:49:30 +0000328 Round-trip invariant for full input:
329 Untokenized source will match input source exactly
330
331 Round-trip invariant for limited intput:
Trent Nelson428de652008-03-18 22:41:35 +0000332 # Output bytes will tokenize the back to the input
333 t1 = [tok[:2] for tok in tokenize(f.readline)]
Raymond Hettinger68c04532005-06-10 11:05:19 +0000334 newcode = untokenize(t1)
Trent Nelson428de652008-03-18 22:41:35 +0000335 readline = BytesIO(newcode).readline
336 t2 = [tok[:2] for tok in tokenize(readline)]
Raymond Hettinger68c04532005-06-10 11:05:19 +0000337 assert t1 == t2
338 """
Thomas Wouters89f507f2006-12-13 04:49:30 +0000339 ut = Untokenizer()
Trent Nelson428de652008-03-18 22:41:35 +0000340 out = ut.untokenize(iterable)
341 if ut.encoding is not None:
342 out = out.encode(ut.encoding)
343 return out
Raymond Hettinger68c04532005-06-10 11:05:19 +0000344
Trent Nelson428de652008-03-18 22:41:35 +0000345
Benjamin Petersond3afada2009-10-09 21:43:09 +0000346def _get_normal_name(orig_enc):
347 """Imitates get_normal_name in tokenizer.c."""
348 # Only care about the first 12 characters.
349 enc = orig_enc[:12].lower().replace("_", "-")
350 if enc == "utf-8" or enc.startswith("utf-8-"):
351 return "utf-8"
352 if enc in ("latin-1", "iso-8859-1", "iso-latin-1") or \
353 enc.startswith(("latin-1-", "iso-8859-1-", "iso-latin-1-")):
354 return "iso-8859-1"
355 return orig_enc
356
Trent Nelson428de652008-03-18 22:41:35 +0000357def detect_encoding(readline):
Raymond Hettingerd1fa3db2002-05-15 02:56:03 +0000358 """
Trent Nelson428de652008-03-18 22:41:35 +0000359 The detect_encoding() function is used to detect the encoding that should
Ezio Melotti4bcc7962013-11-25 05:14:51 +0200360 be used to decode a Python source file. It requires one argument, readline,
Trent Nelson428de652008-03-18 22:41:35 +0000361 in the same way as the tokenize() generator.
362
363 It will call readline a maximum of twice, and return the encoding used
Florent Xicluna43e4ea12010-09-03 19:54:02 +0000364 (as a string) and a list of any lines (left as bytes) it has read in.
Trent Nelson428de652008-03-18 22:41:35 +0000365
366 It detects the encoding from the presence of a utf-8 bom or an encoding
Florent Xicluna43e4ea12010-09-03 19:54:02 +0000367 cookie as specified in pep-0263. If both a bom and a cookie are present,
368 but disagree, a SyntaxError will be raised. If the encoding cookie is an
369 invalid charset, raise a SyntaxError. Note that if a utf-8 bom is found,
Benjamin Peterson689a5582010-03-18 22:29:52 +0000370 'utf-8-sig' is returned.
Trent Nelson428de652008-03-18 22:41:35 +0000371
372 If no encoding is specified, then the default of 'utf-8' will be returned.
373 """
Brett Cannonc33f3f22012-04-20 13:23:54 -0400374 try:
375 filename = readline.__self__.name
376 except AttributeError:
377 filename = None
Trent Nelson428de652008-03-18 22:41:35 +0000378 bom_found = False
379 encoding = None
Benjamin Peterson689a5582010-03-18 22:29:52 +0000380 default = 'utf-8'
Trent Nelson428de652008-03-18 22:41:35 +0000381 def read_or_stop():
382 try:
383 return readline()
384 except StopIteration:
385 return b''
386
387 def find_cookie(line):
388 try:
Martin v. Löwis63674f42012-04-20 14:36:47 +0200389 # Decode as UTF-8. Either the line is an encoding declaration,
390 # in which case it should be pure ASCII, or it must be UTF-8
391 # per default encoding.
392 line_string = line.decode('utf-8')
Trent Nelson428de652008-03-18 22:41:35 +0000393 except UnicodeDecodeError:
Brett Cannonc33f3f22012-04-20 13:23:54 -0400394 msg = "invalid or missing encoding declaration"
395 if filename is not None:
396 msg = '{} for {!r}'.format(msg, filename)
397 raise SyntaxError(msg)
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000398
Serhiy Storchakadafea852013-09-16 23:51:56 +0300399 match = cookie_re.match(line_string)
400 if not match:
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000401 return None
Serhiy Storchakadafea852013-09-16 23:51:56 +0300402 encoding = _get_normal_name(match.group(1))
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000403 try:
404 codec = lookup(encoding)
405 except LookupError:
406 # This behaviour mimics the Python interpreter
Brett Cannonc33f3f22012-04-20 13:23:54 -0400407 if filename is None:
408 msg = "unknown encoding: " + encoding
409 else:
410 msg = "unknown encoding for {!r}: {}".format(filename,
411 encoding)
412 raise SyntaxError(msg)
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000413
Benjamin Peterson1613ed82010-03-18 22:34:15 +0000414 if bom_found:
Florent Xicluna11f0b412012-07-07 12:13:35 +0200415 if encoding != 'utf-8':
Benjamin Peterson1613ed82010-03-18 22:34:15 +0000416 # This behaviour mimics the Python interpreter
Brett Cannonc33f3f22012-04-20 13:23:54 -0400417 if filename is None:
418 msg = 'encoding problem: utf-8'
419 else:
420 msg = 'encoding problem for {!r}: utf-8'.format(filename)
421 raise SyntaxError(msg)
Benjamin Peterson1613ed82010-03-18 22:34:15 +0000422 encoding += '-sig'
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000423 return encoding
Trent Nelson428de652008-03-18 22:41:35 +0000424
425 first = read_or_stop()
Benjamin Peterson433f32c2008-12-12 01:25:05 +0000426 if first.startswith(BOM_UTF8):
Trent Nelson428de652008-03-18 22:41:35 +0000427 bom_found = True
428 first = first[3:]
Benjamin Peterson689a5582010-03-18 22:29:52 +0000429 default = 'utf-8-sig'
Trent Nelson428de652008-03-18 22:41:35 +0000430 if not first:
Benjamin Peterson689a5582010-03-18 22:29:52 +0000431 return default, []
Trent Nelson428de652008-03-18 22:41:35 +0000432
433 encoding = find_cookie(first)
434 if encoding:
435 return encoding, [first]
Serhiy Storchaka768c16c2014-01-09 18:36:09 +0200436 if not blank_re.match(first):
437 return default, [first]
Trent Nelson428de652008-03-18 22:41:35 +0000438
439 second = read_or_stop()
440 if not second:
Benjamin Peterson689a5582010-03-18 22:29:52 +0000441 return default, [first]
Trent Nelson428de652008-03-18 22:41:35 +0000442
443 encoding = find_cookie(second)
444 if encoding:
445 return encoding, [first, second]
446
Benjamin Peterson689a5582010-03-18 22:29:52 +0000447 return default, [first, second]
Trent Nelson428de652008-03-18 22:41:35 +0000448
449
Victor Stinner58c07522010-11-09 01:08:59 +0000450def open(filename):
451 """Open a file in read only mode using the encoding detected by
452 detect_encoding().
453 """
Victor Stinner96917502014-12-05 10:17:10 +0100454 buffer = _builtin_open(filename, 'rb')
Victor Stinner387729e2015-05-26 00:43:58 +0200455 try:
456 encoding, lines = detect_encoding(buffer.readline)
457 buffer.seek(0)
458 text = TextIOWrapper(buffer, encoding, line_buffering=True)
459 text.mode = 'r'
460 return text
461 except:
462 buffer.close()
463 raise
Victor Stinner58c07522010-11-09 01:08:59 +0000464
465
Trent Nelson428de652008-03-18 22:41:35 +0000466def tokenize(readline):
467 """
468 The tokenize() generator requires one argment, readline, which
Raymond Hettingerd1fa3db2002-05-15 02:56:03 +0000469 must be a callable object which provides the same interface as the
Florent Xicluna43e4ea12010-09-03 19:54:02 +0000470 readline() method of built-in file objects. Each call to the function
Trent Nelson428de652008-03-18 22:41:35 +0000471 should return one line of input as bytes. Alternately, readline
Raymond Hettinger68c04532005-06-10 11:05:19 +0000472 can be a callable function terminating with StopIteration:
Trent Nelson428de652008-03-18 22:41:35 +0000473 readline = open(myfile, 'rb').__next__ # Example of alternate readline
Tim Peters8ac14952002-05-23 15:15:30 +0000474
Raymond Hettingerd1fa3db2002-05-15 02:56:03 +0000475 The generator produces 5-tuples with these members: the token type; the
476 token string; a 2-tuple (srow, scol) of ints specifying the row and
477 column where the token begins in the source; a 2-tuple (erow, ecol) of
478 ints specifying the row and column where the token ends in the source;
Florent Xicluna43e4ea12010-09-03 19:54:02 +0000479 and the line on which the token was found. The line passed is the
Tim Peters8ac14952002-05-23 15:15:30 +0000480 logical line; continuation lines are included.
Trent Nelson428de652008-03-18 22:41:35 +0000481
482 The first token sequence will always be an ENCODING token
483 which tells you which encoding was used to decode the bytes stream.
Raymond Hettingerd1fa3db2002-05-15 02:56:03 +0000484 """
Benjamin Peterson21db77e2009-11-14 16:27:26 +0000485 # This import is here to avoid problems when the itertools module is not
486 # built yet and tokenize is imported.
Benjamin Peterson81dd8b92009-11-14 18:09:17 +0000487 from itertools import chain, repeat
Trent Nelson428de652008-03-18 22:41:35 +0000488 encoding, consumed = detect_encoding(readline)
Benjamin Peterson81dd8b92009-11-14 18:09:17 +0000489 rl_gen = iter(readline, b"")
490 empty = repeat(b"")
491 return _tokenize(chain(consumed, rl_gen, empty).__next__, encoding)
Trent Nelson428de652008-03-18 22:41:35 +0000492
493
494def _tokenize(readline, encoding):
Guido van Rossum1aec3231997-04-08 14:24:39 +0000495 lnum = parenlev = continued = 0
Benjamin Peterson33856de2010-08-30 14:41:20 +0000496 numchars = '0123456789'
Guido van Rossumde655271997-04-09 17:15:54 +0000497 contstr, needcont = '', 0
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000498 contline = None
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000499 indents = [0]
Guido van Rossum1aec3231997-04-08 14:24:39 +0000500
Yury Selivanov75445082015-05-11 22:57:16 -0400501 # 'stashed' and 'ctx' are used for async/await parsing
502 stashed = None
503 ctx = [('sync', 0)]
504
Trent Nelson428de652008-03-18 22:41:35 +0000505 if encoding is not None:
Benjamin Peterson689a5582010-03-18 22:29:52 +0000506 if encoding == "utf-8-sig":
507 # BOM will already have been stripped.
508 encoding = "utf-8"
Raymond Hettingera48db392009-04-29 00:34:27 +0000509 yield TokenInfo(ENCODING, encoding, (0, 0), (0, 0), '')
Benjamin Peterson0fe14382008-06-05 23:07:42 +0000510 while True: # loop over lines in stream
Raymond Hettinger68c04532005-06-10 11:05:19 +0000511 try:
512 line = readline()
513 except StopIteration:
Trent Nelson428de652008-03-18 22:41:35 +0000514 line = b''
515
516 if encoding is not None:
517 line = line.decode(encoding)
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000518 lnum += 1
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000519 pos, max = 0, len(line)
520
521 if contstr: # continued string
Guido van Rossumde655271997-04-09 17:15:54 +0000522 if not line:
Collin Winterce36ad82007-08-30 01:19:48 +0000523 raise TokenError("EOF in multi-line string", strstart)
Guido van Rossum3b631771997-10-27 20:44:15 +0000524 endmatch = endprog.match(line)
525 if endmatch:
526 pos = end = endmatch.end(0)
Raymond Hettingera48db392009-04-29 00:34:27 +0000527 yield TokenInfo(STRING, contstr + line[:end],
Thomas Wouters89f507f2006-12-13 04:49:30 +0000528 strstart, (lnum, end), contline + line)
Guido van Rossumde655271997-04-09 17:15:54 +0000529 contstr, needcont = '', 0
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000530 contline = None
Guido van Rossumde655271997-04-09 17:15:54 +0000531 elif needcont and line[-2:] != '\\\n' and line[-3:] != '\\\r\n':
Raymond Hettingera48db392009-04-29 00:34:27 +0000532 yield TokenInfo(ERRORTOKEN, contstr + line,
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000533 strstart, (lnum, len(line)), contline)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000534 contstr = ''
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000535 contline = None
Guido van Rossumde655271997-04-09 17:15:54 +0000536 continue
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000537 else:
538 contstr = contstr + line
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000539 contline = contline + line
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000540 continue
541
Guido van Rossum1aec3231997-04-08 14:24:39 +0000542 elif parenlev == 0 and not continued: # new statement
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000543 if not line: break
544 column = 0
Guido van Rossum1aec3231997-04-08 14:24:39 +0000545 while pos < max: # measure leading whitespace
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000546 if line[pos] == ' ':
547 column += 1
548 elif line[pos] == '\t':
549 column = (column//tabsize + 1)*tabsize
550 elif line[pos] == '\f':
551 column = 0
552 else:
553 break
554 pos += 1
555 if pos == max:
556 break
Guido van Rossum1aec3231997-04-08 14:24:39 +0000557
558 if line[pos] in '#\r\n': # skip comments or blank lines
Thomas Wouters89f507f2006-12-13 04:49:30 +0000559 if line[pos] == '#':
560 comment_token = line[pos:].rstrip('\r\n')
561 nl_pos = pos + len(comment_token)
Raymond Hettingera48db392009-04-29 00:34:27 +0000562 yield TokenInfo(COMMENT, comment_token,
Thomas Wouters89f507f2006-12-13 04:49:30 +0000563 (lnum, pos), (lnum, pos + len(comment_token)), line)
Raymond Hettingera48db392009-04-29 00:34:27 +0000564 yield TokenInfo(NL, line[nl_pos:],
Thomas Wouters89f507f2006-12-13 04:49:30 +0000565 (lnum, nl_pos), (lnum, len(line)), line)
566 else:
Raymond Hettingera48db392009-04-29 00:34:27 +0000567 yield TokenInfo((NL, COMMENT)[line[pos] == '#'], line[pos:],
Guido van Rossum1aec3231997-04-08 14:24:39 +0000568 (lnum, pos), (lnum, len(line)), line)
569 continue
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000570
571 if column > indents[-1]: # count indents or dedents
572 indents.append(column)
Raymond Hettingera48db392009-04-29 00:34:27 +0000573 yield TokenInfo(INDENT, line[:pos], (lnum, 0), (lnum, pos), line)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000574 while column < indents[-1]:
Raymond Hettingerda99d1c2005-06-21 07:43:58 +0000575 if column not in indents:
576 raise IndentationError(
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000577 "unindent does not match any outer indentation level",
578 ("<tokenize>", lnum, pos, line))
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000579 indents = indents[:-1]
Yury Selivanov75445082015-05-11 22:57:16 -0400580
581 cur_indent = indents[-1]
582 while len(ctx) > 1 and ctx[-1][1] >= cur_indent:
583 ctx.pop()
584
Raymond Hettingera48db392009-04-29 00:34:27 +0000585 yield TokenInfo(DEDENT, '', (lnum, pos), (lnum, pos), line)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000586
587 else: # continued statement
Guido van Rossumde655271997-04-09 17:15:54 +0000588 if not line:
Collin Winterce36ad82007-08-30 01:19:48 +0000589 raise TokenError("EOF in multi-line statement", (lnum, 0))
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000590 continued = 0
591
592 while pos < max:
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200593 pseudomatch = _compile(PseudoToken).match(line, pos)
Guido van Rossum3b631771997-10-27 20:44:15 +0000594 if pseudomatch: # scan for tokens
595 start, end = pseudomatch.span(1)
Guido van Rossumde655271997-04-09 17:15:54 +0000596 spos, epos, pos = (lnum, start), (lnum, end), end
Ezio Melotti2cc3b4b2012-11-03 17:38:43 +0200597 if start == end:
598 continue
Guido van Rossum1aec3231997-04-08 14:24:39 +0000599 token, initial = line[start:end], line[start]
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000600
Georg Brandldde00282007-03-18 19:01:53 +0000601 if (initial in numchars or # ordinary number
602 (initial == '.' and token != '.' and token != '...')):
Raymond Hettingera48db392009-04-29 00:34:27 +0000603 yield TokenInfo(NUMBER, token, spos, epos, line)
Guido van Rossum1aec3231997-04-08 14:24:39 +0000604 elif initial in '\r\n':
Yury Selivanov75445082015-05-11 22:57:16 -0400605 if stashed:
606 yield stashed
607 stashed = None
Raymond Hettingera48db392009-04-29 00:34:27 +0000608 yield TokenInfo(NL if parenlev > 0 else NEWLINE,
Thomas Wouters89f507f2006-12-13 04:49:30 +0000609 token, spos, epos, line)
Guido van Rossum1aec3231997-04-08 14:24:39 +0000610 elif initial == '#':
Thomas Wouters89f507f2006-12-13 04:49:30 +0000611 assert not token.endswith("\n")
Yury Selivanov75445082015-05-11 22:57:16 -0400612 if stashed:
613 yield stashed
614 stashed = None
Raymond Hettingera48db392009-04-29 00:34:27 +0000615 yield TokenInfo(COMMENT, token, spos, epos, line)
Guido van Rossum9d6897a2002-08-24 06:54:19 +0000616 elif token in triple_quoted:
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200617 endprog = _compile(endpats[token])
Guido van Rossum3b631771997-10-27 20:44:15 +0000618 endmatch = endprog.match(line, pos)
619 if endmatch: # all on one line
620 pos = endmatch.end(0)
Guido van Rossum1aec3231997-04-08 14:24:39 +0000621 token = line[start:pos]
Raymond Hettingera48db392009-04-29 00:34:27 +0000622 yield TokenInfo(STRING, token, spos, (lnum, pos), line)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000623 else:
Guido van Rossum1aec3231997-04-08 14:24:39 +0000624 strstart = (lnum, start) # multiple lines
625 contstr = line[start:]
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000626 contline = line
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000627 break
Guido van Rossum9d6897a2002-08-24 06:54:19 +0000628 elif initial in single_quoted or \
629 token[:2] in single_quoted or \
630 token[:3] in single_quoted:
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000631 if token[-1] == '\n': # continued string
Guido van Rossum1aec3231997-04-08 14:24:39 +0000632 strstart = (lnum, start)
Antoine Pitrou10a99b02011-10-11 15:45:56 +0200633 endprog = _compile(endpats[initial] or
634 endpats[token[1]] or
635 endpats[token[2]])
Guido van Rossumde655271997-04-09 17:15:54 +0000636 contstr, needcont = line[start:], 1
Guido van Rossuma90c78b1998-04-03 16:05:38 +0000637 contline = line
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000638 break
639 else: # ordinary string
Raymond Hettingera48db392009-04-29 00:34:27 +0000640 yield TokenInfo(STRING, token, spos, epos, line)
Benjamin Peterson33856de2010-08-30 14:41:20 +0000641 elif initial.isidentifier(): # ordinary name
Yury Selivanov75445082015-05-11 22:57:16 -0400642 if token in ('async', 'await'):
643 if ctx[-1][0] == 'async' and ctx[-1][1] < indents[-1]:
644 yield TokenInfo(
645 ASYNC if token == 'async' else AWAIT,
646 token, spos, epos, line)
647 continue
648
649 tok = TokenInfo(NAME, token, spos, epos, line)
650 if token == 'async' and not stashed:
651 stashed = tok
652 continue
653
654 if token == 'def':
655 if (stashed
656 and stashed.type == NAME
657 and stashed.string == 'async'):
658
659 ctx.append(('async', indents[-1]))
660
661 yield TokenInfo(ASYNC, stashed.string,
662 stashed.start, stashed.end,
663 stashed.line)
664 stashed = None
665 else:
666 ctx.append(('sync', indents[-1]))
667
668 if stashed:
669 yield stashed
670 stashed = None
671
672 yield tok
Guido van Rossum3b631771997-10-27 20:44:15 +0000673 elif initial == '\\': # continued stmt
674 continued = 1
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000675 else:
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000676 if initial in '([{':
677 parenlev += 1
678 elif initial in ')]}':
679 parenlev -= 1
Yury Selivanov75445082015-05-11 22:57:16 -0400680 if stashed:
681 yield stashed
682 stashed = None
Raymond Hettingera48db392009-04-29 00:34:27 +0000683 yield TokenInfo(OP, token, spos, epos, line)
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000684 else:
Raymond Hettingera48db392009-04-29 00:34:27 +0000685 yield TokenInfo(ERRORTOKEN, line[pos],
Guido van Rossumde655271997-04-09 17:15:54 +0000686 (lnum, pos), (lnum, pos+1), line)
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000687 pos += 1
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000688
Yury Selivanov75445082015-05-11 22:57:16 -0400689 if stashed:
690 yield stashed
691 stashed = None
692
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000693 for indent in indents[1:]: # pop remaining indent levels
Raymond Hettingera48db392009-04-29 00:34:27 +0000694 yield TokenInfo(DEDENT, '', (lnum, 0), (lnum, 0), '')
695 yield TokenInfo(ENDMARKER, '', (lnum, 0), (lnum, 0), '')
Guido van Rossumfc6f5331997-03-07 00:21:12 +0000696
Trent Nelson428de652008-03-18 22:41:35 +0000697
698# An undocumented, backwards compatible, API for all the places in the standard
699# library that expect to be able to use tokenize with strings
700def generate_tokens(readline):
701 return _tokenize(readline, None)
Raymond Hettinger6c60d092010-09-09 04:32:39 +0000702
Meador Inge14c0f032011-10-07 08:53:38 -0500703def main():
704 import argparse
705
706 # Helper error handling routines
707 def perror(message):
708 print(message, file=sys.stderr)
709
710 def error(message, filename=None, location=None):
711 if location:
712 args = (filename,) + location + (message,)
713 perror("%s:%d:%d: error: %s" % args)
714 elif filename:
715 perror("%s: error: %s" % (filename, message))
716 else:
717 perror("error: %s" % message)
718 sys.exit(1)
719
720 # Parse the arguments and options
721 parser = argparse.ArgumentParser(prog='python -m tokenize')
722 parser.add_argument(dest='filename', nargs='?',
723 metavar='filename.py',
724 help='the file to tokenize; defaults to stdin')
Meador Inge00c7f852012-01-19 00:44:45 -0600725 parser.add_argument('-e', '--exact', dest='exact', action='store_true',
726 help='display token names using the exact type')
Meador Inge14c0f032011-10-07 08:53:38 -0500727 args = parser.parse_args()
728
729 try:
730 # Tokenize the input
731 if args.filename:
732 filename = args.filename
Victor Stinner96917502014-12-05 10:17:10 +0100733 with _builtin_open(filename, 'rb') as f:
Meador Inge14c0f032011-10-07 08:53:38 -0500734 tokens = list(tokenize(f.readline))
735 else:
736 filename = "<stdin>"
737 tokens = _tokenize(sys.stdin.readline, None)
738
739 # Output the tokenization
740 for token in tokens:
Meador Inge00c7f852012-01-19 00:44:45 -0600741 token_type = token.type
742 if args.exact:
743 token_type = token.exact_type
Meador Inge14c0f032011-10-07 08:53:38 -0500744 token_range = "%d,%d-%d,%d:" % (token.start + token.end)
745 print("%-20s%-15s%-15r" %
Meador Inge00c7f852012-01-19 00:44:45 -0600746 (token_range, tok_name[token_type], token.string))
Meador Inge14c0f032011-10-07 08:53:38 -0500747 except IndentationError as err:
748 line, column = err.args[1][1:3]
749 error(err.args[0], filename, (line, column))
750 except TokenError as err:
751 line, column = err.args[1]
752 error(err.args[0], filename, (line, column))
753 except SyntaxError as err:
754 error(err, filename)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200755 except OSError as err:
Meador Inge14c0f032011-10-07 08:53:38 -0500756 error(err)
757 except KeyboardInterrupt:
758 print("interrupted\n")
759 except Exception as err:
760 perror("unexpected error: %s" % err)
761 raise
762
Raymond Hettinger6c60d092010-09-09 04:32:39 +0000763if __name__ == "__main__":
Meador Inge14c0f032011-10-07 08:53:38 -0500764 main()