Skip to content
Merged
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# 0177. The writes check reads a name where it is stored, every class and owner it may be, and exec as its own only where a binding always runs

Status: accepted. The Factory Builder's story of 2026-11-09, issue 655, "check_writes: routes still open after issue 640, an aliased stored name, a second class traced, exec by a binding that never runs", with the four routes Muse's read of the merged pull request "Check_writes holds a class by any name, another module's names, sys reached other ways, code run from text and a command a shell runs" added to it. It amends decision 0171's row "Still not held".

## Decision

| What | Decided | Because |
|---|---|---|
| A name read where it is stored | `tools/check_writes.py` reads a name stored under an `if`, a `try`, a walrus or a top-level tuple, beside a plain assignment too, and a name a function declares `global`, at every module it goes by, through each import and re-export of it, `from a import P as Q` (`_origin`), and by any name for its module, a local one or a module-level alias too. A name a `def` or a `class` binds that an assignment at the top level also binds is bound two ways, and refused where it is set on. What each of those modules stores it as, and what each of their functions that declares it `global` assigns it, is read, as decision 0171 reads them in the module that names it | `_traced` looked the name up as the importer spells it, read only the current module's `global` assignments, and read a name's plain assignment alone where it had one |
| Every class and owner it may be | An attribute set on a name that may be more than one class is refused if any of them is outside its module's top level. An attribute or a key set on a name that may be more than one module's value is given apart for each owner, so PATCHERS allows each only by name | Decision 0171 read the first class and the first owner alone, so a second one was let through, a PATCHERS file's among them |
| Another module's names held first | `vars(m)` or `m.__dict__` held by a name, a function's, the module's own, a global or an imported one, or reached as another module's attribute by any name for that module, read in the scope that gives it, and then handed to a call, or handed on by a walrus, or as `getattr(holder, 'd')`, through any second name it is given too, is refused as when it is handed on at once (`_namespaces`). An unbound fill, `dict.update(other.TABLE, ...)`, by `dict`, `list` or `set`, a name from builtins, collections or typing, `MutableMapping`, or a name given one, `D = dict`, here or in another module of the repo's it is imported from, read in the scope that gives it, fills its first argument, and so does an augmented assignment on an imported container's name, `LIST += [w]`; its receiver is read too, since the name may be no type, `from other import TABLE as dict`. `__ior__` and `__iadd__` fill as `update` does | Decision 0171 refused only the expression handed on in place, and only the bound fill |
| A nonlocal value two steps away | What a nested function assigns a name it declares `nonlocal` is read in that function's own scope, so a local name it gives first, `p = Port; c = p`, is followed | It was read in the outer function, where `p` is no name |
| exec, eval and compile, as a module's own | Only an import or a definition at the module's top level, under no `if`, `try` or function, exempts the name, for a use on a line below it, a use in a function's body too, since the function may be called before the binding runs; and not if it is deleted anywhere, by `del`, an `except ... as` of its name, or `globals().__delitem__` or `pop` by a literal key, or bound two ways. A function's own import of `re.compile` is refused too: import it at the top level. Any of the three given as a literal key, an f-string of constants too, `getattr` argument, `getattr` as an attribute too, or as the key a `get`, `pop`, `setdefault`, `__getitem__` or `__delitem__` reads, a bound one's first argument and an unbound one's second, `dict.get(d, 'eval')`, runs code from text; a bound `get`'s default is no key, `vars(len.__self__)['eval']` | A binding that may never run, or has not run yet, or is undone, leaves the builtin, and a builtin reached by its name runs as surely as one named |
| Loads reached other ways | A loader module's name, `sys`, `modules`, `__builtins__` or `__import__` given as a literal key, `getattr` argument or accessor key as exec's are, and `__builtins__` as any module's attribute, is a load by name. A plain mapping read by such a literal, `cfg.get('modules')`, is refused too: name the key otherwise | `getattr(mutants, 'importlib')`, `k.__builtins__['eval']` and `vars(os).pop('sys')` each reach a module by its name, and the syntax cannot tell a mapping from a module's names |
| Shell words | A command after a `case` pattern's `)`, its alternatives and an opening `(` too, after `in`, `;;`, `;&` or `;;&`, spaced or not; after `eval`, `watch`, `stdbuf`, `setsid`, `coproc`, `ionice`, `unbuffer`, `caffeinate` or `doas` with their options; and after `timeout`, `flock`, `taskset` or `chrt`, with options that take a value, and the word each takes first, `timeout -s KILL 60 git push`, is a command. Prose that puts one of these words before git, "we watch git", is refused as well; a `)` alone, "(see log) git", is not | Each runs the next word |
| One module, two files | Two files that are one module, a module's own file and a package's file of the same dotted name, are refused, and a function's reading is cached under its node, never its id. A problem found twice is told once | Which one Python imports cannot be told, and the run dropped the second while its cache entries stayed, keyed on ids a later tree could reuse |
| Still not held | As decision 0171 names, but for the routes above: a RUNNERS function handed a write's arguments by its caller; a name given by a loop, a `with`, a container, a call's return, a call's argument to the function that fills it, a starred part, or a class's attribute, `class H: d = vars(m)`; a container filled by `__init__` or by a fill method `getattr` names; a module's own `exec` binding undone through `globals()` by a key that is not a literal; a key built any other way, or given by a starred argument; a container's type subclassed in the module, `class D(dict)`, or given by a global; a module-level unpacking that is not a tuple to a tuple of one length; a `def` or a `class` under an `if` beside an assignment of its name; a module reached by `getattr` of a name that is not a literal, by `unittest.mock.patch`, or another Python run as a process; a command after a backtick, built from parts, read from outside the code, or after a word that runs the next and is not one of those named; a `match` capture's shadow | Each is still the review's, for the reasons decision 0171 gives |

## Why

The reads of issue 640, "check_writes: routes still open after issue 596, a runner's helper, a class or instance reached through another name, sys.modules by getattr", and of the pull request that closed it found these routes after their changes' last fix rounds. Each is a pattern the syntax names, taken only by code written to hide a write, so the check names it. None is on main, which passes as before.

## Boundaries

| Boundary | Check |
|---|---|
| A name stored under an `if` and imported under another name, beside a plain assignment, or as a top-level tuple's part, and a `global` another module's function, or the importing module's own, assigns, by any name for its module, are read where they are stored | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "a stored name is read only under its own name", mutant: "a global is read only in the module that names it", mutant: "a top-level tuple's parts are not stored", mutant: "a global the importing module's function assigns is not read", mutant: "a global through a local name for its module is not read", mutant: "an import beside a store is not followed", mutant: "a module-level alias as an attribute's base is not read", mutant: "a name a def binds and an if stores is read as the def", mutant: "a def an if stores is not bound two ways", mutant: "a name set on that the module binds two ways is let through" |
| A second class or owner a name may be is read, a PATCHERS file's too | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "only the first class it may be is read", mutant: "only the first owner it may be is read" |
| `vars(m)` held by a function's or the module's name, then handed on, and an unbound fill of another module's container, are refused; a module's own container filled passes | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "vars held by a name is not read", mutant: "vars a function's name holds is not read", mutant: "vars a module's name holds is not read", mutant: "vars held by a global is not read", mutant: "vars held by an imported name is not read", mutant: "an unbound fill is not read", mutant: "a container's type imported from collections is not read", mutant: "a container's type by a module's other name is not read", mutant: "a container's type by a function's name is not read", mutant: "__ior__ and __iadd__ fill nothing", mutant: "the receiver of an unbound fill is not read", mutant: "a container's type a module stores is read in a function's scope", mutant: "a container's type is seen by its name alone", mutant: "a container's type a default gives is read in its function", mutant: "a container's type imported from the repo is not followed", mutant: "an imported container filled in place by its name is not read", mutant: "vars held by another module's name as an attribute is not read", mutant: "vars handed on by a walrus is not read", mutant: "vars behind a second name through an attribute is not followed", mutant: "vars behind a second name through a walrus is not followed", mutant: "a holder's re-export is not followed", mutant: "getattr of a holder is not read as its attribute" |
| A nonlocal value two steps away is read in its own function | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "a nonlocal value is read in the outer function" |
| exec or eval bound under an `if`, a `try` or a function, used before or inside its own binding, deleted by `del` or an `except`, or given as a literal key, `getattr` or accessor argument, is refused; one imported at the top level passes | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "a binding under an if, a try or a function exempts exec", mutant: "a deleted exec is still the module's own", mutant: "exec bound below its use is the module's own", mutant: "an except deletes nothing", mutant: "exec by a literal key is let through", mutant: "exec by getattr is let through", mutant: "exec by an accessor is let through", mutant: "exec imported from builtins is the module's own", mutant: "getattr as an attribute is let through", mutant: "an f-string of constants is no literal", mutant: "__delitem__ reads no key", mutant: "an unbound accessor's text runner is not read", mutant: "a bound get's default is read as a key" |
| A loader by `getattr` or a literal key, `sys` or `modules` by `get`, and `__builtins__` as an attribute, are refused | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "a loader by getattr is let through", mutant: "a loader by a literal key is let through", mutant: "sys or modules by get is let through", mutant: "a key read by pop, setdefault or __getitem__ is let through", mutant: "an unbound accessor's key is not read", mutant: "__builtins__ as an attribute is let through" |
| A command after a `case` pattern's `)`, after `eval`, `watch`, `stdbuf`, `setsid` and their kind, and after `timeout` or `flock` and an option with its value, is refused; a `)` in prose before git passes | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "a case pattern's ) leads no command", mutant: "eval, watch and stdbuf run no command", mutant: "timeout's options take no value", mutant: "flock runs no command", mutant: "taskset and chrt take no first word", mutant: "a case pattern's alternatives or ( lead no command", mutant: "a second case pattern leads no command", mutant: "a case pattern after ;& leads no command", mutant: "a case lead needs a space after it" |
| Two files of one module are refused, and a reading is cached under the node | `tests/test_tools.py::test_the_routes_issue_655_names_are_refused`, `tools/check_writes.py`, mutant: "two files of one module are read as one", mutant: "a reading is cached under a function's id", mutant: "a function's scope is cached under its id", mutant: "a problem is told as often as it is found" |
Loading
Loading