From db02ddc75d27b8c5dde9595e5122a22b3f7c4a1b Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sun, 20 Jul 2025 14:31:45 +0200 Subject: [PATCH 1/2] gh-136640: clarify documentation of AST subclasses attributes --- Doc/library/ast.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index ef6c62dca1e124..a1cbe3588ad12c 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -91,11 +91,12 @@ Node classes end_lineno end_col_offset - Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have - :attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and - :attr:`end_col_offset` attributes. The :attr:`lineno` and :attr:`end_lineno` - are the first and last line numbers of source text span (1-indexed so the - first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset` + Most instances of classes part of this module, e.g. instances of subclasses of + :class:`ast.expr`, :class:`ast.stmt` and others (see + `Abstract Grammar `__), have :attr:`lineno`, :attr:`col_offset`, + :attr:`end_lineno`, and :attr:`end_col_offset` attributes. The :attr:`lineno` and + :attr:`end_lineno` are the first and last line numbers of source text span (1-indexed + so the first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding UTF-8 byte offsets of the first and last tokens that generated the node. The UTF-8 offset is recorded because the parser uses UTF-8 internally. From bdc3e765bc447ef29b3db09000bc6e0a0589db17 Mon Sep 17 00:00:00 2001 From: Matthieu Lienart Date: Sun, 20 Jul 2025 14:36:33 +0200 Subject: [PATCH 2/2] update proposal based on feedback --- Doc/library/ast.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index a1cbe3588ad12c..4daac538233097 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -91,10 +91,10 @@ Node classes end_lineno end_col_offset - Most instances of classes part of this module, e.g. instances of subclasses of + Most classes part of the AST module have the :attr:`lineno`, :attr:`col_offset`, + :attr:`end_lineno`, and :attr:`end_col_offset` attributes, including subclasses of :class:`ast.expr`, :class:`ast.stmt` and others (see - `Abstract Grammar `__), have :attr:`lineno`, :attr:`col_offset`, - :attr:`end_lineno`, and :attr:`end_col_offset` attributes. The :attr:`lineno` and + `Abstract Grammar `__). The :attr:`lineno` and :attr:`end_lineno` are the first and last line numbers of source text span (1-indexed so the first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding UTF-8 byte offsets of the first and last tokens that