tesserae-el 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,16 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .mypy_cache/
10
+ .coverage
11
+ htmlcov/
12
+ .vscode/
13
+ .pi/
14
+
15
+ # graphify knowledge-graph output (built by `graphify update .`; local cache and paths)
16
+ graphify-out/
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ All notable changes to the package. Versions follow [Semantic Versioning](https://semver.org); below
4
+ 1.0 a minor version may break the API. The language version is separate and is 0.1 for every release
5
+ here (`docs/versioning.md`).
6
+
7
+ ## 0.1.0
8
+
9
+ The first release: everything in the plan up to step 8.
10
+
11
+ ### The language
12
+
13
+ - Expressions over a whitelist of Python's syntax tree (arithmetic, comparisons, conditionals,
14
+ subscripts, comprehensions, f-strings, a set of built-in functions and methods), with `cond ? a : b`
15
+ as a second spelling of `a if cond else b`.
16
+ - `{{ }}` templates, with one step budget for all parts.
17
+ - Limits on source size, nesting, nodes, steps, ranges, repeats, powers, integers and strings; every
18
+ limit is a named `TelLimitError`.
19
+ - Errors that carry the line and column in the host file (`Origin`), the text, a caret and a hint.
20
+
21
+ ### The host side
22
+
23
+ - `Scope` (`lookup`), `MapScope`, `evaluate_tracked` (the names and attribute paths an evaluation read),
24
+ host functions and host methods, registered at compile time.
25
+ - `compile_condition`, `Condition`, `select` and `select_tracked` for `if` / `elif` / `else` chains.
26
+ - `compile_repeater`, `compile_repeater_parts`, `Repeater.items`, `reconcile`, `reconcile_tracked`,
27
+ `RepeaterState`: keyed entries, `<name>_0001` names that are never reused, the fewest moved entries.
28
+ - `fill`, `fill_template`, `literal` and `Expression.canonical` / `Template.canonical`: TEL's Python
29
+ form, for building expression text from Python values and comparing two spellings.
30
+ - `compile_template` always returns a `Template` (`is_text` for plain text).
31
+
32
+ ### Safety
33
+
34
+ - A host object may be carried in a scope and its attributes read; nothing may call its methods,
35
+ also not through a list that holds it (`sum`, `sorted`, `==`, `in`, `str`, text).
36
+ - An escape corpus (233 lines, every line refused by every entry point), a Hypothesis fuzzer and
37
+ a removal check of more than 500 deliberate breakages, each of which a test must catch.
38
+ - `docs/security-review.md` says what is protected, how it is checked and what is not guaranteed.
39
+
40
+ ### Known gaps
41
+
42
+ - A compiled expression keeps about 0.5 to 0.75 times the memory of the `expr.py` it replaces, not the
43
+ 0.5 asked for (`docs/benchmarks.md`, step 8).
44
+ - Not run on a free-threaded Python build.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mind Derivative
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.5
2
+ Name: tesserae-el
3
+ Version: 0.1.0
4
+ Summary: TEL, the Tesserae Expression Language: a small, safe expression language for YAML and Python.
5
+ Project-URL: Repository, https://github.com/mindderivative/tess-el
6
+ Project-URL: Documentation, https://github.com/mindderivative/tess-el/blob/main/docs/language.md
7
+ Project-URL: Changelog, https://github.com/mindderivative/tess-el/blob/main/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/mindderivative/tess-el/issues
9
+ Author: Mind Derivative
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: declarative,expression-language,sandbox,yaml
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.14
20
+ Description-Content-Type: text/markdown
21
+
22
+ # TEL
23
+
24
+ TEL, the Tesserae Expression Language, is a small, safe expression language and a Python
25
+ library that parses and evaluates it. It lets plain YAML (or Python code) express
26
+ conditions, repeaters and live values.
27
+
28
+ > **Status:** alpha, package 0.1.0, language version 0.1. The API may change before 1.0 (a minor
29
+ > version may break it; see [`docs/versioning.md`](https://github.com/mindderivative/tess-el/blob/main/docs/versioning.md)).
30
+ > The design is in [`docs/language.md`](https://github.com/mindderivative/tess-el/blob/main/docs/language.md);
31
+ > what is protected, how it is checked and what is not guaranteed is in
32
+ > [`docs/security-review.md`](https://github.com/mindderivative/tess-el/blob/main/docs/security-review.md).
33
+
34
+ TEL needs Python 3.14 or later and has no dependencies:
35
+
36
+ ```sh
37
+ pip install tesserae-el
38
+ ```
39
+
40
+ It evaluates expressions and `{{ }}` templates (with limits and positions in errors), tracks the names
41
+ and attribute paths an evaluation read, takes host functions and methods, reads conditions
42
+ (`compile_condition`, `select`) and repeaters (`compile_repeater`, `reconcile`) for a host that
43
+ builds the tree, and builds expression text from Python values (`fill`, `canonical`).
44
+
45
+ ```python
46
+ import tel
47
+
48
+ expr = tel.compile_expression("'low' if battery < 20 else f'{battery}%'", language="0.1")
49
+ expr.evaluate(tel.MapScope({"battery": 63})) # '63%'
50
+ expr.evaluate(tel.MapScope({"battery": 12})) # 'low'
51
+ ```
52
+
53
+ A conditional can also be written `cond ? a : b`: the same as `a if cond else b`, with the same
54
+ precedence (lowest, right-associative), and it may not be mixed with `if/else` without brackets.
55
+ **In YAML, quote a value that contains ` : `**: a colon followed by a space ends a plain scalar, so
56
+ `x: a ? b : c` is a YAML error and `- a ? b : c` is read as a mapping.
57
+
58
+ A condition reads an expression as yes or no. The host owns the `if:`, `elif:` and `else:` keys;
59
+ `select` gives the index of the first condition that holds, or `None` for the `else`, and
60
+ `select_tracked` also gives the paths read by every condition tested up to the winner.
61
+
62
+ ```python
63
+ chain = [tel.compile_condition(t, language="0.1") for t in ("unread > 0", "muted")]
64
+ tel.select(chain, tel.MapScope({"unread": 0, "muted": True})) # 1
65
+ ```
66
+
67
+ In YAML, give a condition or a key as text: quote a value with ` : ` in it, and quote a bare `true`
68
+ or `1`, which YAML loads as a bool or an int (TEL refuses a non-text value with a `TypeError`).
69
+
70
+ To build an expression in Python, fill placeholders with values: each `$name` (outside strings and
71
+ comments) becomes a checked literal, so a value can only be data and a string is quoted. The result is
72
+ text for any `compile_*` function.
73
+
74
+ ```python
75
+ text = tel.fill("battery < $limit or name in $names", {"limit": 20, "names": ["a", "b"]})
76
+ # "battery < 20 or name in ['a', 'b']"
77
+ tel.fill_template("Hello {{ $who }}!", {"who": "Ada"}) # "Hello {{ 'Ada' }}!"
78
+ ```
79
+
80
+ Two spellings of one expression have one canonical text, for comparing an expression built in Python
81
+ with one written as text (compare within one run; do not store it):
82
+
83
+ ```python
84
+ tel.compile_expression("a<20", language="0.1").canonical # 'a < 20'
85
+ tel.compile_expression("c ? a : b", language="0.1").canonical # 'a if c else b'
86
+ ```
87
+
88
+ A repeater reads a header (`item in items`, or `i, item in enumerate(items)`) and a key expression,
89
+ and gives the list's items with their keys. The host owns the `for:` and `key:` keys and builds the
90
+ nodes; each item's `scope(parent)` is the scope for its children.
91
+
92
+ ```python
93
+ rep = tel.compile_repeater("w in workspaces", key="w.id", name="Workspace", language="0.1")
94
+ items = rep.items(tel.MapScope({"workspaces": [{"id": 7}, {"id": 9}]}))
95
+ [(item.index, item.key) for item in items] # [(0, 7), (1, 9)]
96
+
97
+ # keep the state between calls: entries are new or kept, and keys can be removed
98
+ both = tel.MapScope({"workspaces": [{"id": 7}, {"id": 9}]})
99
+ result = rep.reconcile(both, tel.RepeaterState())
100
+ [e.name for e in result.entries] # ['Workspace_0001', 'Workspace_0002']
101
+ result = rep.reconcile(tel.MapScope({"workspaces": [{"id": 9}]}), result.state)
102
+ (result.removed, result.entries[0].name) # ((7,), 'Workspace_0002')
103
+ ```
104
+ A file that holds the loop variable, the list and the key apart (the Shell's TDL) passes them
105
+ separately, each with its own origin; the result is the same repeater:
106
+
107
+ ```python
108
+ rep = tel.compile_repeater_parts(
109
+ "w",
110
+ "workspaces",
111
+ key="w.id",
112
+ name="Workspace",
113
+ language="0.1",
114
+ names_origin=tel.Origin("A.tdl", 12, 9),
115
+ items_origin=tel.Origin("A.tdl", 12, 15),
116
+ key_origin=tel.Origin("A.tdl", 12, 35),
117
+ )
118
+ ```
119
+
120
+
121
+ ```python
122
+ template = tel.compile_template("Battery {{ battery }}%, {{ state }}", language="0.1")
123
+ template.evaluate(
124
+ tel.MapScope({"battery": 63, "state": "discharging"})
125
+ ) # 'Battery 63%, discharging'
126
+ ```
127
+
128
+ A host adds its own functions and methods when it compiles. TEL calls only what the host listed:
129
+
130
+ ```python
131
+ expr = tel.compile_expression(
132
+ "format_number(total, 1) + ' ' + price.formatted()",
133
+ language="0.1",
134
+ functions={"format_number": lambda x, digits=0: f"{x:,.{digits}f}"},
135
+ methods={Price: {"formatted": Price.formatted}},
136
+ )
137
+ ```
138
+
139
+ To know which names an evaluation actually read, so a host re-runs it only when one of them changes:
140
+
141
+ ```python
142
+ expr = tel.compile_expression("'low' if battery < 20 else state", language="0.1")
143
+ value, reads = expr.evaluate_tracked(tel.MapScope({"battery": 63, "state": "ok"}))
144
+ # value == 'ok', reads == {'battery', 'state'}; with battery=12 it reads only {'battery'}
145
+ ```
146
+
147
+ A read is a name, or an attribute chain on a name: `RootShell.DP1.Top_Bar.Width` reports that whole
148
+ path, so an expression depends only on what it reads. `Tracked.names` gives the top-level names, and
149
+ `expr.paths` every path in the text, before any evaluation.
150
+
151
+ A scope is anything with `lookup(name)` (the value, or `KeyError`) and optionally `names()`. What TEL
152
+ may ask of it, and what it must do in return (quick, no effects, plain values), is written clause by
153
+ clause in [`docs/language.md`](https://github.com/mindderivative/tess-el/blob/main/docs/language.md) section 12.2 and tested in
154
+ `tests/test_scope_contract.py`.
155
+
156
+ A template that is exactly one `{{ }}` part gives that part's value with its type; any other text with
157
+ parts gives text. Text with no part is a template that evaluates to itself (`Template.is_text`).
158
+
159
+ A bad expression is an error that says where (`tel.TelError`, with a stable `code`, a line and a
160
+ column), never a hang: every size and every loop is limited (`tel.Limits`). An expression can read
161
+ names from the scope you give it and call a few built-in functions and methods; it cannot reach
162
+ files, the process, the network, or an object's private attributes.
163
+
164
+ PyPI name: `tesserae-el` (not yet published). Import name: `tel`.
165
+
166
+ ## Development
167
+
168
+ ```sh
169
+ uv pip install -e . --group dev # into the active venv (Python 3.14+)
170
+ python tools/check.py # ruff, format check, mypy (strict), pytest: what CI runs
171
+ python tools/wrapup.py # what is still behind before work is handed over
172
+ python tools/removal_check.py # break each rule of the language on purpose: a test must fail
173
+ tools/status.sh # branch, unpushed work, version, mailbox, board
174
+ ```
175
+
176
+ Work is tracked on the [TEL (tess-el) board](https://github.com/users/mindderivative/projects/4)
177
+ (`python tools/board.py status`). `graphify update .` rebuilds the local code graph.
178
+ Benchmarks: [`docs/benchmarks.md`](https://github.com/mindderivative/tess-el/blob/main/docs/benchmarks.md) (the `expr.py` baseline). Behaviour reference: [`docs/reference-cases.md`](https://github.com/mindderivative/tess-el/blob/main/docs/reference-cases.md).
179
+ Agent instructions are in [`AGENTS.md`](AGENTS.md); project skills are in `.agents/skills/`.
180
+
181
+ ## Versioning
182
+
183
+ See [`docs/versioning.md`](https://github.com/mindderivative/tess-el/blob/main/docs/versioning.md).
184
+
185
+ ## Licence
186
+
187
+ [MIT](https://github.com/mindderivative/tess-el/blob/main/LICENSE)
@@ -0,0 +1,166 @@
1
+ # TEL
2
+
3
+ TEL, the Tesserae Expression Language, is a small, safe expression language and a Python
4
+ library that parses and evaluates it. It lets plain YAML (or Python code) express
5
+ conditions, repeaters and live values.
6
+
7
+ > **Status:** alpha, package 0.1.0, language version 0.1. The API may change before 1.0 (a minor
8
+ > version may break it; see [`docs/versioning.md`](https://github.com/mindderivative/tess-el/blob/main/docs/versioning.md)).
9
+ > The design is in [`docs/language.md`](https://github.com/mindderivative/tess-el/blob/main/docs/language.md);
10
+ > what is protected, how it is checked and what is not guaranteed is in
11
+ > [`docs/security-review.md`](https://github.com/mindderivative/tess-el/blob/main/docs/security-review.md).
12
+
13
+ TEL needs Python 3.14 or later and has no dependencies:
14
+
15
+ ```sh
16
+ pip install tesserae-el
17
+ ```
18
+
19
+ It evaluates expressions and `{{ }}` templates (with limits and positions in errors), tracks the names
20
+ and attribute paths an evaluation read, takes host functions and methods, reads conditions
21
+ (`compile_condition`, `select`) and repeaters (`compile_repeater`, `reconcile`) for a host that
22
+ builds the tree, and builds expression text from Python values (`fill`, `canonical`).
23
+
24
+ ```python
25
+ import tel
26
+
27
+ expr = tel.compile_expression("'low' if battery < 20 else f'{battery}%'", language="0.1")
28
+ expr.evaluate(tel.MapScope({"battery": 63})) # '63%'
29
+ expr.evaluate(tel.MapScope({"battery": 12})) # 'low'
30
+ ```
31
+
32
+ A conditional can also be written `cond ? a : b`: the same as `a if cond else b`, with the same
33
+ precedence (lowest, right-associative), and it may not be mixed with `if/else` without brackets.
34
+ **In YAML, quote a value that contains ` : `**: a colon followed by a space ends a plain scalar, so
35
+ `x: a ? b : c` is a YAML error and `- a ? b : c` is read as a mapping.
36
+
37
+ A condition reads an expression as yes or no. The host owns the `if:`, `elif:` and `else:` keys;
38
+ `select` gives the index of the first condition that holds, or `None` for the `else`, and
39
+ `select_tracked` also gives the paths read by every condition tested up to the winner.
40
+
41
+ ```python
42
+ chain = [tel.compile_condition(t, language="0.1") for t in ("unread > 0", "muted")]
43
+ tel.select(chain, tel.MapScope({"unread": 0, "muted": True})) # 1
44
+ ```
45
+
46
+ In YAML, give a condition or a key as text: quote a value with ` : ` in it, and quote a bare `true`
47
+ or `1`, which YAML loads as a bool or an int (TEL refuses a non-text value with a `TypeError`).
48
+
49
+ To build an expression in Python, fill placeholders with values: each `$name` (outside strings and
50
+ comments) becomes a checked literal, so a value can only be data and a string is quoted. The result is
51
+ text for any `compile_*` function.
52
+
53
+ ```python
54
+ text = tel.fill("battery < $limit or name in $names", {"limit": 20, "names": ["a", "b"]})
55
+ # "battery < 20 or name in ['a', 'b']"
56
+ tel.fill_template("Hello {{ $who }}!", {"who": "Ada"}) # "Hello {{ 'Ada' }}!"
57
+ ```
58
+
59
+ Two spellings of one expression have one canonical text, for comparing an expression built in Python
60
+ with one written as text (compare within one run; do not store it):
61
+
62
+ ```python
63
+ tel.compile_expression("a<20", language="0.1").canonical # 'a < 20'
64
+ tel.compile_expression("c ? a : b", language="0.1").canonical # 'a if c else b'
65
+ ```
66
+
67
+ A repeater reads a header (`item in items`, or `i, item in enumerate(items)`) and a key expression,
68
+ and gives the list's items with their keys. The host owns the `for:` and `key:` keys and builds the
69
+ nodes; each item's `scope(parent)` is the scope for its children.
70
+
71
+ ```python
72
+ rep = tel.compile_repeater("w in workspaces", key="w.id", name="Workspace", language="0.1")
73
+ items = rep.items(tel.MapScope({"workspaces": [{"id": 7}, {"id": 9}]}))
74
+ [(item.index, item.key) for item in items] # [(0, 7), (1, 9)]
75
+
76
+ # keep the state between calls: entries are new or kept, and keys can be removed
77
+ both = tel.MapScope({"workspaces": [{"id": 7}, {"id": 9}]})
78
+ result = rep.reconcile(both, tel.RepeaterState())
79
+ [e.name for e in result.entries] # ['Workspace_0001', 'Workspace_0002']
80
+ result = rep.reconcile(tel.MapScope({"workspaces": [{"id": 9}]}), result.state)
81
+ (result.removed, result.entries[0].name) # ((7,), 'Workspace_0002')
82
+ ```
83
+ A file that holds the loop variable, the list and the key apart (the Shell's TDL) passes them
84
+ separately, each with its own origin; the result is the same repeater:
85
+
86
+ ```python
87
+ rep = tel.compile_repeater_parts(
88
+ "w",
89
+ "workspaces",
90
+ key="w.id",
91
+ name="Workspace",
92
+ language="0.1",
93
+ names_origin=tel.Origin("A.tdl", 12, 9),
94
+ items_origin=tel.Origin("A.tdl", 12, 15),
95
+ key_origin=tel.Origin("A.tdl", 12, 35),
96
+ )
97
+ ```
98
+
99
+
100
+ ```python
101
+ template = tel.compile_template("Battery {{ battery }}%, {{ state }}", language="0.1")
102
+ template.evaluate(
103
+ tel.MapScope({"battery": 63, "state": "discharging"})
104
+ ) # 'Battery 63%, discharging'
105
+ ```
106
+
107
+ A host adds its own functions and methods when it compiles. TEL calls only what the host listed:
108
+
109
+ ```python
110
+ expr = tel.compile_expression(
111
+ "format_number(total, 1) + ' ' + price.formatted()",
112
+ language="0.1",
113
+ functions={"format_number": lambda x, digits=0: f"{x:,.{digits}f}"},
114
+ methods={Price: {"formatted": Price.formatted}},
115
+ )
116
+ ```
117
+
118
+ To know which names an evaluation actually read, so a host re-runs it only when one of them changes:
119
+
120
+ ```python
121
+ expr = tel.compile_expression("'low' if battery < 20 else state", language="0.1")
122
+ value, reads = expr.evaluate_tracked(tel.MapScope({"battery": 63, "state": "ok"}))
123
+ # value == 'ok', reads == {'battery', 'state'}; with battery=12 it reads only {'battery'}
124
+ ```
125
+
126
+ A read is a name, or an attribute chain on a name: `RootShell.DP1.Top_Bar.Width` reports that whole
127
+ path, so an expression depends only on what it reads. `Tracked.names` gives the top-level names, and
128
+ `expr.paths` every path in the text, before any evaluation.
129
+
130
+ A scope is anything with `lookup(name)` (the value, or `KeyError`) and optionally `names()`. What TEL
131
+ may ask of it, and what it must do in return (quick, no effects, plain values), is written clause by
132
+ clause in [`docs/language.md`](https://github.com/mindderivative/tess-el/blob/main/docs/language.md) section 12.2 and tested in
133
+ `tests/test_scope_contract.py`.
134
+
135
+ A template that is exactly one `{{ }}` part gives that part's value with its type; any other text with
136
+ parts gives text. Text with no part is a template that evaluates to itself (`Template.is_text`).
137
+
138
+ A bad expression is an error that says where (`tel.TelError`, with a stable `code`, a line and a
139
+ column), never a hang: every size and every loop is limited (`tel.Limits`). An expression can read
140
+ names from the scope you give it and call a few built-in functions and methods; it cannot reach
141
+ files, the process, the network, or an object's private attributes.
142
+
143
+ PyPI name: `tesserae-el` (not yet published). Import name: `tel`.
144
+
145
+ ## Development
146
+
147
+ ```sh
148
+ uv pip install -e . --group dev # into the active venv (Python 3.14+)
149
+ python tools/check.py # ruff, format check, mypy (strict), pytest: what CI runs
150
+ python tools/wrapup.py # what is still behind before work is handed over
151
+ python tools/removal_check.py # break each rule of the language on purpose: a test must fail
152
+ tools/status.sh # branch, unpushed work, version, mailbox, board
153
+ ```
154
+
155
+ Work is tracked on the [TEL (tess-el) board](https://github.com/users/mindderivative/projects/4)
156
+ (`python tools/board.py status`). `graphify update .` rebuilds the local code graph.
157
+ Benchmarks: [`docs/benchmarks.md`](https://github.com/mindderivative/tess-el/blob/main/docs/benchmarks.md) (the `expr.py` baseline). Behaviour reference: [`docs/reference-cases.md`](https://github.com/mindderivative/tess-el/blob/main/docs/reference-cases.md).
158
+ Agent instructions are in [`AGENTS.md`](AGENTS.md); project skills are in `.agents/skills/`.
159
+
160
+ ## Versioning
161
+
162
+ See [`docs/versioning.md`](https://github.com/mindderivative/tess-el/blob/main/docs/versioning.md).
163
+
164
+ ## Licence
165
+
166
+ [MIT](https://github.com/mindderivative/tess-el/blob/main/LICENSE)
@@ -0,0 +1,81 @@
1
+ # Error codes
2
+
3
+ Every error TEL raises has a `code`: a short stable identifier. Match on the code, never on the
4
+ message. A test (`tests/test_error_codes.py`) keeps this page and the source in step: a code that is
5
+ raised but not listed here, or listed and never raised, fails it.
6
+
7
+ ## `TelSyntaxError`: the text is not valid, or is not allowed
8
+
9
+ | Code | When |
10
+ |---|---|
11
+ | `empty-expression` | The text is empty or only whitespace. |
12
+ | `syntax-error` | Python cannot read the text as one expression. If the text is valid as statements, the hint says TEL has none. |
13
+ | `invalid-text` | The text contains a null byte or a lone surrogate. |
14
+ | `disallowed-construct` | A construct that is not in the language: `lambda`, `:=`, `await`, `yield`, `& \| ^ << >> ~ @`, a t-string, or any syntax-tree node not on the whitelist. |
15
+ | `constant-type` | A constant that is not `None`, `bool`, `int`, `float` or `str`: bytes, complex, `...`. |
16
+ | `private-name` | A name, loop variable or argument name starting with `_` (except `_` as a loop variable). |
17
+ | `private-attribute` | An attribute starting with `_`. |
18
+ | `is-operand` | `is` or `is not` compared with anything but `None`, `True` or `False`. |
19
+ | `dict-unpack` | `**` in a dict display. |
20
+ | `call-unpack` | `**` in a call. |
21
+ | `call-target` | A call whose callee is not a name or `value.method`. |
22
+ | `call-not-function` | A call to a name that is not a built-in function (or a function the host allowed), or to a comprehension variable. |
23
+ | `method-format` | `format` or `format_map` (a format string can read attributes). |
24
+ | `method-not-available` | A method that is not on the whitelist, such as `append`, `pop`, `update`. |
25
+ | `isinstance-type` | `isinstance` with anything but one of `str int float bool list dict` as its second argument. |
26
+ | `comprehension-async` | An `async` comprehension. |
27
+ | `comprehension-target` | A comprehension loop variable that is not a name or names in a tuple. |
28
+ | `repeater-header` | A repeater header that is not `name in expression` (or `name, name in expression`): it is empty, has no `in` or nothing after it, a loop variable that is not a name, a Python keyword, or a name used twice. The error points at the part that is wrong. |
29
+ | `template-unclosed` | A `{{` in a template is never closed by `}}`. The error points at the `{{`. |
30
+ | `template-empty` | A `{{ }}` with nothing between the braces. The error points at the `{{`. |
31
+
32
+ ## `TelEvaluationError`: the expression could not be evaluated in this scope
33
+
34
+ Messages name types and names, never values from the scope.
35
+
36
+ | Code | When |
37
+ |---|---|
38
+ | `unknown-name` | A name is not in the scope (and is not a built-in being called). The hint suggests the nearest name. |
39
+ | `function-as-value` | A built-in function's name is read as a value (`len`, not `len(x)`). |
40
+ | `value-not-plain` | An object that is not a plain value is used in an operator, a comparison, a subscript or index, text, a set or dict key, or a function or method argument; also a container with such an object inside it given to `min`, `max`, `sum`, `sorted`, `any`, `all`, `set`, `dict`, `str`, a comparison, `in`, text, `.index` or `.count` (the object's own methods would run). |
41
+ | `bad-operand` | An operator, sign or `**` that cannot take these types, or a result that is not a real number. |
42
+ | `bad-comparison` | `<`, `<=`, `>` or `>=` between types that cannot be ordered. |
43
+ | `percent-format` | `%` on text; use an f-string. |
44
+ | `division-by-zero` | `/`, `//`, `%` or `**` by zero. |
45
+ | `number-too-large` | A number too large for the operation (for example an integer division result that does not fit a float). |
46
+ | `no-attribute` | An object or plain value has no readable attribute with that name. |
47
+ | `no-key` | A mapping read by attribute has no such key. |
48
+ | `attribute-is-method` | An attribute that is a method (or a callable) is read as a value. |
49
+ | `attribute-denied` | Reading an attribute of, or indexing, a module, class, function or similar. |
50
+ | `attribute-failed` | The host's own property raised while being read. |
51
+ | `bad-index` | An index or slice that does not fit the value. |
52
+ | `bad-key` | A dict key or set member that cannot be hashed. |
53
+ | `not-iterable` | A loop, spread or membership test over something that is not a text, list, tuple, dict, set or range; a repeater's list that is a set or a frozenset (its order is not stable) or that is not a text, list, tuple, dict or range. |
54
+ | `bad-unpack` | A loop target with a different number of names than the item has values. A repeater with several names needs each item to be a list or tuple of that length. |
55
+ | `bad-key-type` | A repeater key that is not an `int`, a `str` or a tuple of those (a `float`, `bool` or `None` is refused: `1`, `1.0` and `True` would be one key). The message names the item and the type. |
56
+ | `duplicate-key` | Two items of a repeater have the same key. The message names both items by position, never the key. |
57
+ | `bad-call` | A built-in or host function or method failed, or was given arguments it cannot take. The message names the function and the class of the exception, never its text. |
58
+ | `result-not-plain` | A function or method the host registered returned something that is not a plain value. |
59
+ | `method-not-for-type` | A method called on a value that does not have it in TEL (for example `.upper()` on a number). |
60
+ | `bad-format` | An f-string format spec that does not fit the value. |
61
+
62
+ ## `TelLimitError`: a limit was exceeded
63
+
64
+ | Code | When |
65
+ |---|---|
66
+ | `limit-source` | The text is longer than `max_source`. |
67
+ | `limit-depth` | The syntax tree is nested deeper than `max_depth`, or is too deep for Python to read. |
68
+ | `limit-nodes` | The syntax tree has more than `max_nodes` nodes. |
69
+ | `limit-steps` | An evaluation took more than `max_steps` steps. |
70
+ | `limit-range` | A `range` is longer than `max_range`. |
71
+ | `limit-sequence` | A repeated or joined sequence is longer than `max_sequence`. |
72
+ | `limit-pow-exponent` | A `**` exponent is over `max_pow_exponent`. A constant exponent is refused when the text is read. |
73
+ | `limit-int-bits` | An integer, written or computed, is over `max_int_bits` bits. |
74
+ | `limit-string` | A string, written or computed, is over `max_string` characters. |
75
+
76
+ ## `TelVersionError`: the language version
77
+
78
+ | Code | When |
79
+ |---|---|
80
+ | `unsupported-language` | The version is text but not one this release supports. |
81
+ | `language-not-text` | The version is not text. YAML reads an unquoted `0.1` as a number. |