Expressions and Contexts#
app-model provides two complementary primitives that let you describe
conditional behavior in your application without having to evaluate that
condition immediately:
- Expressions (
Expr) are abstract, serializable representations of conditional statements (e.g."x > 5 and is_ready"). They have no value on their own — they need to be evaluated against some context. - Contexts (
Context) are mappings of names to concrete values (e.g.{"x": 7, "is_ready": True}). They provide the values that an expression needs in order to be evaluated.
This separation makes it possible to declare a condition (in code, in a plugin manifest, in a config file...) and evaluate it later, against a state that may change over time.
A common use is to control whether a menu item is visible or a keybinding is
active. An Action may, for example, declare that it is
only enabled when selected_layer_count > 0. The application is then
responsible for keeping the relevant context keys up to date, and the menu/
keybinding system will re-evaluate the expression as the context changes.
A motivating example#
Standard Python expressions like x > 5 and y == 'hello' are evaluated
immediately and reduce to a single value. To delay evaluation, you might
keep them as strings and evaluate later with eval:
expression = "x > 5 and y == 'hello'"
eval(expression, {"x": 7, "y": "hello"}) # True
eval(expression, {"x": 1, "y": "hello"}) # False
This works, but eval is unsafe (it executes arbitrary Python), and a plain
string isn't very ergonomic to construct, combine, or introspect.
app-model provides a richer abstraction for this kind of deferred
conditional logic.
Expressions#
Expr is the abstract base class for an
expression. An Expr is an ast.AST subclass — it represents a parsed
expression tree, but does not yet have a value. You typically don't
instantiate Expr directly; instead, you parse a string with
parse_expression:
from app_model.expressions import parse_expression
expr = parse_expression("x > 5 and y == 'hello'")
expr.eval({"x": 7, "y": "hello"}) # True
expr.eval({"x": 1, "y": "hello"}) # False
For convenience, safe_eval parses and
evaluates in one step:
from app_model.expressions import safe_eval
safe_eval("x > 5 and y == 'hello'", {"x": 7, "y": "hello"}) # True
What's supported (and what's not)#
Unlike eval, parsing an Expr only allows a safe subset of Python.
Supported constructs include:
- Names:
myvar(require a context to evaluate) - Constants: numbers, strings, bytes, booleans,
None - Comparisons:
==,!=,<,<=,>,>=,in,not in,is,is not - Boolean operators:
and,or,not - Binary operators:
+,-,*,/,//,%,**,@,^,&,|,<<,>> - Unary operators:
not,-,+,~ - Conditional expressions:
a if b else c - Container literals: lists, tuples, sets (e.g.
x in [1, 2, 3])
The following are explicitly not supported (and will raise SyntaxError):
- attribute access (
obj.attr) - function calls (
f(x)) - indexing or slicing (
x[0],x[1:2]) - f-strings
- the walrus operator (
a := 1) - comprehensions
- statements & assignments
Building expressions in code#
You can also build expressions directly from
Name and
Constant nodes, using normal Python
operators. This is convenient when you want to construct expressions
programmatically (and gives nice IDE autocompletion when combined with
ContextKey, see below):
from app_model.expressions import Name, Constant
light_is_green = Name[bool]("light_is_green")
count = Name[int]("count")
is_ready = light_is_green & (count > 5)
is_ready.eval({"count": 4, "light_is_green": True}) # False
is_ready.eval({"count": 7, "light_is_green": False}) # False
is_ready.eval({"count": 7, "light_is_green": True}) # True
About &, |, and ~
When working with Expr objects, the bitwise operators &, |, and
~ are overloaded to mean boolean and, or, and not.
This is necessary because Python's and/or/not keywords cannot be
overloaded — using them on Expr objects would short-circuit and just
return one of the operands, instead of building a new expression.
If you actually need bitwise operations, use the
bitand and
bitor methods.
Expressions can be serialized back to strings (e.g. for storage or display):
str(is_ready)
# 'light_is_green and count > 5'
Contexts#
A Context is a mapping of names to values
that can be used to evaluate an expression. For simple cases, a plain dict
will do — but the Context class adds two important capabilities:
- It is a
ChainMap, so contexts can have parents and children (created withnew_child). Children inherit keys from their parents, but can add or override keys locally. - It is evented: the
changedsignal is emitted whenever a key is added, modified, or deleted. Child contexts re-emit their parent's events, so anything listening to a child sees changes from anywhere in the chain.
from app_model.expressions import Context
root = Context()
root["theme"] = "dark"
scoped = root.new_child()
scoped["selected_count"] = 3
# child sees keys from parent
scoped["theme"] # 'dark'
scoped["selected_count"] # 3
@scoped.changed.connect
def on_change(keys):
print("changed:", keys)
root["theme"] = "light" # changed: {'theme'}
scoped["selected_count"] = 7 # changed: {'selected_count'}
When you need to make several changes at once and only emit a single event,
use buffered_changes:
with scoped.buffered_changes():
scoped["a"] = 1
scoped["b"] = 2
# only one `changed` event is emitted, with keys={'a', 'b'}
The bulk mutation methods update(), clear(), and |= are buffered the
same way, so each call emits a single changed event:
scoped.update({"a": 3, "b": 4})
# only one `changed` event is emitted, with keys={'a', 'b'}
Creating contexts for objects#
A typical pattern is to associate a context with an object — for example, a window, a document, or a viewer. When operations happen inside that object (or inside a child object created by it), they should see that object's context.
You could just instantiate a Context() and stash it on the object
yourself:
class Window:
def __init__(self):
self.context = Context() # an isolated root mapping
self.document = Document() # has no idea about Window's context
…but this gives you an isolated, parentless mapping that nothing else can
discover. If Document (or anything created inside Window.__init__)
wants the same context, you have to thread it through manually.
create_context does three extra
things on top of Context() to solve this:
- It registers the context in a process-wide table keyed by
id(obj), so any code can retrieve it later viaget_context(obj)— no need to hold or pass a reference. - It cleans up the registry entry when
objis garbage-collected, viaweakref.finalize, so the table doesn't leak. - It auto-discovers a parent by walking up the call stack looking
for a
selfin some enclosing frame that already has a registered context. The new context is then created as aChainMapchild of that parent (falling back to a process-wide root if none is found).
That last point is the magic that makes nested objects automatically share context without explicit wiring:
from app_model.expressions import create_context, get_context
class Window:
def __init__(self):
create_context(self)
self.document = Document() # constructed inside Window.__init__
class Document:
def __init__(self):
create_context(self) # picks Window's context as parent
w = Window()
get_context(w) # Window's context
get_context(w.document) # Document's context (a ChainMap child of Window's)
get_context(w)["theme"] = "dark"
get_context(w.document)["theme"] # 'dark' — inherited from Window
If Document had used Context() directly, get_context(w.document) would
return None, the Document's context would be a sibling root rather than
a child, and theme would not be visible from inside the document.
Application contexts#
Every Application has a
Context, available as app.context. You
may pass your own (a Context or any mutable mapping) as the context
argument; otherwise a new one is created. Either way, the application adds a
few platform-detection keys to it via
app_model_context:
| Key | Type | Meaning |
|---|---|---|
is_linux |
bool |
Running on Linux |
is_mac |
bool |
Running on macOS |
is_windows |
bool |
Running on Windows |
Anything you put in app.context is available to expressions used in
Action enablement rules, menu when clauses, and
keybinding when clauses.
Context keys: typed, documented names#
Strings like "selected_count" are easy to typo and hard to discover.
ContextKey is a named, documented,
optionally-typed expression node. It subclasses
Name, so a ContextKey is an expression
that you can compose with other expressions using normal operators.
ContextKeys are organized into
ContextNamespace subclasses:
from app_model.expressions import ContextKey, ContextNamespace
class SelectionContextKeys(ContextNamespace[list]):
selected_count = ContextKey(
default_value=0,
description="Number of currently selected items.",
getter=lambda selection: len(selection),
)
has_selection = ContextKey(
default_value=False,
description="Whether anything is selected.",
getter=lambda selection: len(selection) > 0,
)
Each ContextKey has:
- a default value (used when the key isn't in the context yet)
- a description (useful for documentation)
- an optional getter — a function that, given some source object, returns the current value for that key
Because ContextKey is itself an expression, you can compose it directly:
expr = SelectionContextKeys.selected_count > 0
expr.eval({"selected_count": 3}) # True
expr.eval({"selected_count": 0}) # False
This is much friendlier to write and refactor than
parse_expression("selected_count > 0").
Static typing#
ContextKey is generic in two type parameters, ContextKey[A, T]:
Ais the type of the source object passed togetter(matching the parameter onContextNamespace[A]).Tis the value type of the key.
By annotating the class attribute as ContextKey[A, T], you give the
type checker (mypy, pyright, …) full information about reads and writes
through the bound namespace — so mistakes that a plain Context
mapping (ctx["selected_count"]: Any) would never catch become static
errors:
from app_model.expressions import Context, ContextKey, ContextNamespace
class SelectionKeys(ContextNamespace[list]):
selected_count = ContextKey[list, int](
default_value=0,
description="Number of selected items.",
getter=lambda sel: len(sel),
)
ctx = Context()
keys = SelectionKeys(ctx)
reveal_type(keys.selected_count) # int
total: int = keys.selected_count + 1 # OK
keys.selected_count = 3 # OK
# A static type checker flags both of the following:
keys.selected_count.upper() # error: "int" has no attribute "upper"
keys.selected_count = "three" # error: Incompatible: str -> int
Running mypy or pyright on the snippet above produces an error on each of the last two lines.
Binding a namespace to a context#
Once instantiated, a ContextNamespace is bound to a particular
Context. Its declared keys then act as live get/set descriptors on that
context, with the right defaults applied:
from app_model.expressions import Context
ctx = Context()
keys = SelectionContextKeys(ctx)
keys.selected_count # 0 (default)
ctx["selected_count"] # 0
keys.selected_count = 3 # sets ctx["selected_count"] = 3
ctx["selected_count"] # 3
keys.dict()
# {'selected_count': 3, 'has_selection': False}
keys.reset_all() # restore defaults
This gives you a typed, attribute-style API on top of a plain mapping — useful for keeping context updates close to the model objects that drive them.
Discovering all declared keys#
Every ContextKey you declare is recorded in a process-wide registry,
which is convenient for documentation generation:
from app_model.expressions import ContextKey
for info in ContextKey.info():
print(info.key, info.type, info.description)
Each entry is a ContextKeyInfo
named tuple with key, type, description, and namespace fields.
Putting it all together#
Several app-model types accept Expr instances as conditions:
CommandRule.enablement— when a command is enabled in the UIMenuRule.when— when a menu item is shownKeyBindingRule.when— when a keybinding is activeToggleRule.condition— when a command should appear "checked" in the UI
A typical end-to-end pattern looks like:
from app_model import Action, Application
from app_model.expressions import ContextKey, ContextNamespace
from app_model.types import KeyBindingRule, KeyCode, KeyMod
class MyKeys(ContextNamespace[list]):
selected_count = ContextKey(
default_value=0,
description="Number of selected items",
getter=lambda sel: len(sel),
)
app = Application("my-app")
keys = MyKeys(app.context)
def delete_selection():
print("deleted!")
app.register_action(
Action(
id="delete",
title="Delete",
callback=delete_selection,
enablement=MyKeys.selected_count > 0,
keybindings=[
KeyBindingRule(
primary=KeyMod.CtrlCmd | KeyCode.Delete,
when=MyKeys.selected_count > 0,
)
],
)
)
# Later, as your application's selection state changes, update the context.
# Anything looking at the action's `enablement` (e.g. a Qt menu) will be
# notified via the Context's `changed` signal and can refresh its state.
keys.selected_count = 0 # action becomes disabled
keys.selected_count = 2 # action becomes enabled
Summary#
- Define the names you care about with
ContextKeyinside aContextNamespace. - Use those keys to build
Exprobjects that describe the conditions under which actions, menus, and keybindings should be enabled or shown. - Maintain a
Contextthat holds the current values for those keys, and keep it in sync with your application state. - The
changedsignal on the context will let any consumers (menus, keybindings, etc.) re-evaluate the relevant expressions whenever anything they depend on changes.