Skip to main content

big_code_analysis_ast/getter/
python.rs

1//! `Getter` implementation for Python.
2#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]
3
4use super::*;
5
6use crate::lang_helpers::python::{python_is_bare_string, python_is_bare_string_parenthesis};
7
8/// The role of a `{`, `:` or `=`, which Python spells both as syntax
9/// and inside an f-string's replacement field.
10///
11/// As syntax each is an operator (#1486). The interpolation opener
12/// (`f"{x}"`, and a nested `{w}` inside a format spec) is spelling, not
13/// an operation — the six interpolating languages settled that in #1314
14/// and Python follows them. The `:` that opens a format spec
15/// (`f"{x:>10}"`) introduces the format mini-language, whose text is
16/// string content and counts as nothing, so its delimiter does not
17/// count either. The self-documenting `=` (`f"{x=}"`) is a directive of
18/// the same field: it asks for the expression's text to be printed and
19/// assigns nothing, like the `!r` conversion beside it, which was
20/// already unbilled (#1551).
21fn replacement_field_role(kind: Python, parent: Option<Python>) -> TokenRole {
22    use Python::*;
23
24    match (kind, parent) {
25        // role-bypass: allow(StringLit) — token role under an interpolation, not whether the node
26        // is a literal
27        (LBRACE | EQ, Some(Interpolation | FormatExpression)) | (COLON, Some(FormatSpecifier)) => {
28            TokenRole::Unknown
29        }
30        _ => TokenRole::Operator,
31    }
32}
33
34impl Getter for PythonCode {
35    // The mapping is the `opens` annotations of `roles/python.rs`
36    // (#1696); the rows read no bytes and no chain, so the byte-less
37    // spelling forwards with none.
38    impl_byte_less_space_kind!(python);
39
40    fn get_space_kind_with_code<'a>(
41        node: &Node<'a>,
42        code: &[u8],
43        ancestors: Ancestors<'a, '_>,
44    ) -> SpaceKind {
45        crate::roles::python::opens_space(node, code, ancestors)
46    }
47
48    keyword_roles!(python);
49
50    paying_roles!(python, control_flow);
51
52    fn get_op_type<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> TokenRole {
53        use Python::*;
54
55        let kind: Python = node.kind_id().into();
56        // Bracket openers, `;`, `:` and `=` are vocabulary like every
57        // other getter's (#1395, #1486); only the f-string
58        // replacement-field spellings are withdrawn. An early return
59        // rather than an arm, because the match below is one rustfmt
60        // declines to format.
61        if matches!(kind, LBRACE | COLON | EQ) {
62            let parent = ancestors.parent(node).map(|p| p.kind_id().into());
63            return replacement_field_role(kind, parent);
64        }
65        // The parentheses around a bare string are discarded with it,
66        // as CPython drops them (#1610).
67        if kind == LPAREN && python_is_bare_string_parenthesis(node, ancestors) {
68            return TokenRole::Unknown;
69        }
70
71        // The comparison operators — the compounds `not in` / `is not`
72        // included — and `and` / `or` are not here: the `Comparison`
73        // and `ShortCircuit` rows of `roles/python.rs` declare them and
74        // `get_paying_role` bills each at its leaf (#1694).
75        match kind {
76            // The `not` / `in` / `is` leaf tokens are operators on their own
77            // (`not x`, `a in b`, `a is b`, `for x in y`), but the grammar
78            // also nests them inside the compound `not in` (Notin) and
79            // `is not` (Isnot) nodes. When the leaf's parent is one of those
80            // compounds, the compound itself is classified as the single
81            // operator, so the leaf must yield Unknown — otherwise
82            // `a not in b` would count `not` + `in` as two operators (#413).
83            // The `Comparison` row pays a bare `in` / `is` only under the
84            // `comparison_operator` wrapper, which is the gate the
85            // counting consumers need; the `in` of a `for` clause and a
86            // comprehension is the spelling the row leaves to this arm.
87            // role-bypass: allow(Comparison) — the operator classification of the spellings the
88            // row's `under ComparisonOperator` gate leaves out: a loop's `in`
89            Not | In | Is => match ancestors.parent(node).map(|p| p.kind_id().into()) {
90                Some(Notin | Isnot) => TokenRole::Unknown,
91                _ => TokenRole::Operator,
92            },
93            // The `assert` / `for` / `while` / `except` / `elif` keywords
94            // are the `Branch` / `Loop` / `Catch` / `ElseIf` rows' payers
95            // and `get_paying_role` bills them (#1697). `if` stays: the
96            // `Branch` row's payer gate declines the ternary's `if` so
97            // cyclomatic does not count it beside the owner, while
98            // Halstead bills that spelling as it always has (`if` and
99            // `else` are the ternary's operators); the statement's `if`
100            // reaches `get_paying_role` first and never gets here.
101            // role-bypass: allow(Exit, Branch) — the operator classification of the `yield`
102            // expression the row owns as an exit, and of the `if` spelling the `Branch`
103            // row's `not_under_ternary` gate leaves out; neither a projection the row answers
104            Import | DOT | From | COMMA | As | STAR | GTGT | COLONEQ | Return
105            | Del | Raise | Pass | Break | Continue | If | Else | Async
106            | Try | Finally | With | DASHGT | Global | Nonlocal | Exec
107            | AT | PLUS | DASH | SLASH | PERCENT | SLASHSLASH | STARSTAR | PIPE
108            | AMP | CARET | LTLT | TILDE
109            | PLUSEQ | DASHEQ | STAREQ | SLASHEQ | ATEQ | SLASHSLASHEQ | PERCENTEQ | STARSTAREQ
110            | GTGTEQ | LTLTEQ | AMPEQ | CARETEQ | PIPEEQ | Yield | Print | LPAREN | LBRACK
111            | SEMI
112            // `match` / `case` keyword tokens (Match=26, Case=27), mirroring
113            // the cyclomatic metric which already counts each `case` clause
114            // and the Rust Halstead which counts `match` (#413).
115            | Match | Case
116            // `nonlocal` keyword token, for parity with `global` which was
117            // already classified (#413).
118            // `await`: count only the await-expression node (Await=237);
119            // Await2 (keyword token 95) is the nested keyword and was being
120            // double-counted, mirroring how `yield` counts only the Yield
121            // node and not its keyword leaf (#413).
122            | Await
123            // `def`, `class` and `lambda`'s keyword token are not here:
124            // `roles/python.rs` declares them and `get_keyword_role`
125            // bills them (#1693).
126            => {
127                TokenRole::Operator
128            }
129            Identifier | Integer | Float | True | False | None => TokenRole::Operand,
130            // role-bypass: allow(StringLit) — the operand classification of the literal
131            // under the row's `wraps` list, a projection the row does not answer
132            String => {
133                // A bare string statement's string — its sole value, or a
134                // fragment of an implicitly concatenated one — is discarded,
135                // so it is not an operand (#695). The LOC walk bills the same
136                // strings as comment rows through this predicate, so the two
137                // agree on which strings are discarded; whether one is also
138                // documentation is `python_documentation_string_run`'s
139                // question, which Halstead deliberately does not ask (#1597).
140                if python_is_bare_string(node, ancestors) {
141                    return TokenRole::Unknown;
142                }
143                // Regression #191: an f-string wraps `Interpolation` children
144                // whose inner expressions are walked and counted separately.
145                // Skip the wrapping literal to avoid double-counting (same
146                // pattern as #180 for Bash/Elixir and #184 for PHP).
147                Self::string_operand_type(node, crate::roles::python::string_lit::WRAPS)
148            }
149            _ => TokenRole::Unknown,
150        }
151    }
152
153    get_operator!(Python);
154}