`tokenize` --- Tokenizer for Python source¶

Code source : Lib/tokenize.py

The tokenize module provides a lexical scanner for Python source code, implemented in Python. The scanner in this module returns comments as tokens as well, making it useful for implementing "pretty-printers", including colorizers for on-screen displays.

To simplify token stream handling, all operator and delimiter tokens and Ellipsis are returned using the generic OP token type. The TokenInfo.exact_type property gives the exact token type.

Avertissement

Note that the functions in this module are only designed to parse syntactically valid Python code (code that does not raise when parsed using ast.parse()). The behavior of the functions in this module is undefined when providing invalid Python code and it can change at any point.

Tokenizing input¶

Le point d'entrée principal est un générateur :

tokenize.tokenize(readline)¶

Le générateur tokenize() prend un argument readline qui doit être un objet appelable exposant la même interface que la méthode io.IOBase.readline() des objets fichiers. Chaque appel a la fonction doit renvoyer une ligne sous forme de bytes.

The generator produces TokenInfo objects.

Modifié dans la version 3.1: Changed to yield TokenInfo objects instead of plain tuples.

tokenize() détermine le codage source du fichier en recherchant une nomenclature UTF-8 ou un cookie d'encodage, selon la PEP 263.

tokenize.generate_tokens(readline)¶

Tokenize a source reading unicode strings instead of bytes.

Like tokenize(), the readline argument is a callable returning a single line of input. However, generate_tokens() expects readline to return a str object rather than bytes.

The result is an iterator yielding TokenInfo objects, exactly like tokenize(). It does not yield an ENCODING token.

class tokenize.TokenInfo(type, string, start, end, line)¶

A named tuple describing a token. It has five fields and an additional exact_type property.

Ajouté dans la version 3.1.

type¶: An integer identifying the token type, as defined by the constants in token, such as NAME and STRING. Operators and delimiters have type OP; use exact_type for their specific token type.

string¶

The token text as a str. For STRING tokens, this includes the quotes, any prefix, and escape sequences, without evaluating them.

For an ENCODING token, this is the encoding name. Tokens inserted without corresponding source text can have an empty string. In FSTRING_MIDDLE and TSTRING_MIDDLE tokens, doubled braces are replaced by single braces.

start¶

A 2-tuple (srow, scol) of ints specifying the inclusive start position of the token in the source. Rows are numbered from 1 and columns from 0. Columns count Unicode code points; a tab counts as one column, without expanding it to a tab stop.

For an ENCODING token, this is (0, 0).

end¶

A 2-tuple (erow, ecol) of ints specifying the exclusive end position of the token. Rows are numbered from 1 and columns from 0. For a token spanning multiple lines, erow is the final row and ecol is the column on that row.

For example, the name spam at the beginning of the first line has start equal to (1, 0) and end equal to (1, 4).

For an ENCODING token, this is (0, 0). A NEWLINE or NL token inserted at the end of input without a final newline can have an end column one beyond the source text.

line¶: A str containing the full source line on which the token was found, including surrounding text and the line terminator if present. For a token spanning multiple lines, this can contain several source lines. It is empty for ENCODING and ENDMARKER tokens.

exact_type¶: An integer identifying the specific operator type for OP tokens, as defined by the constants in token. For all other token types, this equals type. For example, a + token has type equal to OP and exact_type equal to PLUS.

Ajouté dans la version 3.3.

All constants from the token module are also exported from tokenize.

Une autre fonction est fournie pour inverser le processus de tokenisation. Ceci est utile pour créer des outils permettant de codifier un script, de modifier le flux de jetons et de réécrire le script modifié.

tokenize.untokenize(iterable)¶

Convertit les jetons en code source Python. L'iterable doit renvoyer des séquences avec au moins deux éléments, le type de jeton et la chaîne de caractères associée. Tout élément de séquence supplémentaire est ignoré.

The result is guaranteed to tokenize back to match the input so that the conversion is lossless and round-trips are assured. The guarantee applies only to the token type and token string as the spacing between tokens (column positions) may change.

It returns bytes, encoded using the ENCODING token, which is the first token sequence output by tokenize(). If there is no encoding token in the input, it returns a str instead.

tokenize() a besoin de détecter le codage des fichiers sources qu'il code. La fonction utilisée pour cela est disponible :

tokenize.detect_encoding(readline)¶

La fonction detect_encoding() est utilisée pour détecter l'encodage à utiliser pour décoder un fichier source Python. Il nécessite un seul argument, readline, de la même manière que le générateur tokenize().

Il appelle readline au maximum deux fois et renvoie le codage utilisé (sous forme de chaîne) et une liste de toutes les lignes (non décodées à partir des octets) dans lesquelles il a été lu.

Il détecte l'encodage par la présence d'une marqueur UTF-8 (BOM) ou d'un cookie de codage, comme spécifié dans la PEP 263. Si un BOM et un cookie sont présents, mais en désaccord, un SyntaxError sera levée. Notez que si le BOM est trouvé, 'utf-8-sig' sera renvoyé comme encodage.

Si aucun codage n'est spécifié, la valeur par défaut, 'utf-8', sera renvoyée.

Utilisez open() pour ouvrir les fichiers source Python : ça utilise detect_encoding() pour détecter le codage du fichier.

tokenize.open(filename)¶: Ouvre un fichier en mode lecture seule en utilisant l'encodage détecté par dectect_encoding().

Ajouté dans la version 3.2.

exception tokenize.TokenError¶

Déclenché lorsque soit une docstring soit une expression qui pourrait être divisée sur plusieurs lignes n'est pas complété dans le fichier, par exemple :

"""Beginning of
docstring

ou :

[1,
 2,
 3

Command-line usage¶

Ajouté dans la version 3.3.

The tokenize module can be executed as a script from the command line. It is as simple as:

python -m tokenize [-e] [filename.py]

Les options suivantes sont acceptées :

-h, --help¶: Montre ce message d'aide et quitte

-e, --exact¶: Affiche les noms de jetons en utilisant le même type.

Si filename.py est spécifié, son contenu est tokenisé vers stdout. Sinon, la tokenisation est effectuée sur ce qui est fourni sur stdin.

Ajouté dans la version 3.15: Output is in color by default and can be controlled using environment variables.

Exemples¶

Exemple d'un script qui transforme les littéraux de type float en type Decimal :

from tokenize import tokenize, untokenize, NUMBER, STRING, NAME, OP
from io import BytesIO

def decistmt(s):
    """Substitute Decimals for floats in a string of statements.

    >>> from decimal import Decimal
    >>> s = 'print(+21.3e-5*-.1234/81.7)'
    >>> decistmt(s)
    "print (+Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7'))"

    The format of the exponent is inherited from the platform C library.
    Known cases are "e-007" (Windows) and "e-07" (not Windows).  Since
    we're only showing 12 digits, and the 13th isn't close to 5, the
    rest of the output should be platform-independent.

    >>> exec(s)  #doctest: +ELLIPSIS
    -3.21716034272e-0...7

    Output from calculations with Decimal should be identical across all
    platforms.

    >>> exec(decistmt(s))
    -3.217160342717258261933904529E-7
    """
    result = []
    g = tokenize(BytesIO(s.encode('utf-8')).readline)  # tokenize the string
    for toknum, tokval, _, _, _ in g:
        if toknum == NUMBER and '.' in tokval:  # replace NUMBER tokens
            result.extend([
                (NAME, 'Decimal'),
                (OP, '('),
                (STRING, repr(tokval)),
                (OP, ')')
            ])
        else:
            result.append((toknum, tokval))
    return untokenize(result).decode('utf-8')

Exemple de tokenisation à partir de la ligne de commande. Le script :

def say_hello():
    print("Hello, World!")

say_hello()

will be tokenized to the following output where the first column is the range of the line/column coordinates where the token is found, the second column is the name of the token, and the final column is the value of the token (if any):

$ python -m tokenize hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          OP             '('
1,14-1,15:          OP             ')'
1,15-1,16:          OP             ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           OP             '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          OP             ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         ''
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           OP             '('
4,10-4,11:          OP             ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      ''

Les noms exacts des types de jeton peuvent être affichés en utilisant l’option : -e :

$ python -m tokenize -e hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          LPAR           '('
1,14-1,15:          RPAR           ')'
1,15-1,16:          COLON          ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           LPAR           '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          RPAR           ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         ''
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           LPAR           '('
4,10-4,11:          RPAR           ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      ''

Example of tokenizing a file programmatically, reading unicode strings instead of bytes with generate_tokens():

import tokenize

with tokenize.open('hello.py') as f:
    tokens = tokenize.generate_tokens(f.readline)
    for token in tokens:
        print(token)

Or reading bytes directly with tokenize():

import tokenize

with open('hello.py', 'rb') as f:
    tokens = tokenize.tokenize(f.readline)
    for token in tokens:
        print(token)

`tokenize` --- Tokenizer for Python source¶

Tokenizing input¶

Command-line usage¶

Exemples¶

Table des matières

Sujet précédent

Sujet suivant

Cette page

tokenize --- Tokenizer for Python source¶

Tokenizing input¶

Command-line usage¶

Exemples¶

`tokenize` --- Tokenizer for Python source¶