Debian Codegraph @

src/app_model/registries/_register.py

raw
1 from __future__ import annotations
2
3 from typing import TYPE_CHECKING, overload
4
5 from app_model.types import Action
6
7 if TYPE_CHECKING:
8 from typing import Any, Callable, Literal, TypeVar
9
10 from app_model import Application, expressions
11 from app_model.types import (
12 DisposeCallable,
13 Icon, # noqa: F401 ... used in type hints for docs
14 IconOrDict,
15 KeyBindingRuleOrDict,
16 MenuRuleOrDict,
17 )
18
19 CommandCallable = TypeVar("CommandCallable", bound=Callable[..., Any])
20 CommandDecorator = Callable[[Callable], Callable]
21
22
23 @overload
24 def register_action(
25 app: Application | str, id_or_action: Action
26 ) -> DisposeCallable: ...
27
28
29 @overload
30 def register_action(
31 app: Application | str,
32 id_or_action: str,
33 title: str,
34 *,
35 callback: Literal[None] = ...,
36 category: str | None = ...,
37 tooltip: str | None = ...,
38 icon: IconOrDict | None = ...,
39 enablement: expressions.Expr | None = ...,
40 menus: list[MenuRuleOrDict] | None = ...,
41 keybindings: list[KeyBindingRuleOrDict] | None = ...,
42 palette: bool = True,
43 ) -> CommandDecorator: ...
44
45
46 @overload
47 def register_action(
48 app: Application | str,
49 id_or_action: str,
50 title: str,
51 *,
52 callback: Callable[..., Any],
53 category: str | None = ...,
54 tooltip: str | None = ...,
55 icon: IconOrDict | None = ...,
56 enablement: expressions.Expr | None = ...,
57 menus: list[MenuRuleOrDict] | None = ...,
58 keybindings: list[KeyBindingRuleOrDict] | None = ...,
59 palette: bool = True,
60 ) -> DisposeCallable: ...
61
62
63 def register_action(
64 app: Application | str,
65 id_or_action: str | Action,
66 title: str | None = None,
67 *,
68 callback: Callable[..., Any] | None = None,
69 category: str | None = None,
70 tooltip: str | None = None,
71 icon: IconOrDict | None = None,
72 enablement: expressions.Expr | None = None,
73 menus: list[MenuRuleOrDict] | None = None,
74 keybindings: list[KeyBindingRuleOrDict] | None = None,
75 palette: bool = True,
76 ) -> CommandDecorator | DisposeCallable:
77 """Register an action.
78
79 This is a functional form of the
80 [`Application.register_action()`][app_model.Application.register_action] method.
81 It accepts various overloads to allow for a more concise syntax. See examples
82 below.
83
84 An `Action` is the "complete" representation of a command. The command is the
85 function/callback itself, and an action also includes information about where and
86 whether it appears in menus and optional keybinding rules. Since, most of the
87 arguments to this function are simply passed through to the `Action` constructor,
88 see also docstrings for:
89
90 - [`Action`][app_model.types.Action]
91 - [`CommandRule`][app_model.types.CommandRule]
92 - [`MenuRule`][app_model.types.MenuRule]
93 - [`KeyBindingRule`][app_model.types.KeyBindingRule]
94
95 Parameters
96 ----------
97 app: Application | str
98 The app in which to register the action. If a string, the app is retrieved
99 or created as necessary using
100 [`Application.get_or_create(app)`][app_model.Application.get_or_create].
101 id_or_action : str | Action
102 Either a complete Action object or a string id of the command being registered.
103 If an `Action` object is provided, then all other arguments are ignored.
104 title : str | None
105 Title by which the command is represented in the UI. Required when
106 `id_or_action` is a string.
107 callback : CommandHandler | None
108 Callable object that executes this command, by default None. If not provided,
109 a decorator is returned that can be used to decorate a function that executes
110 this action.
111 category : str | None
112 Category string by which the command may be grouped in the UI, by default None
113 tooltip : str | None
114 Tooltip to show when hovered., by default None
115 icon : Icon | None
116 [`Icon`][app_model.types.Icon] used to represent this command,
117 e.g. on buttons or in menus. by default None
118 enablement : expressions.Expr | None
119 Condition which must be true to enable the command in in the UI,
120 by default None
121 menus : list[MenuRuleOrDict] | None
122 List of [`MenuRule`][app_model.types.MenuRule] or kwarg `dicts` containing menu
123 placements for this action, by default None
124 keybindings : list[KeyBindingRuleOrDict] | None
125 List of [`KeyBindingRule`][app_model.types.KeyBindingRule] or kwargs `dicts`
126 containing default keybindings for this action, by default None
127 palette : bool
128 Whether to adds this command to the Command Palette, by default True
129
130 Returns
131 -------
132 CommandDecorator
133 If `callback` is not provided, then a decorator is returned that can be used to
134 decorate a function as the executor of the command.
135 DisposeCallable
136 If `callback` is provided, or `id_or_action` is an `Action` object, then a
137 function is returned that may be used to unregister the action.
138
139 Raises
140 ------
141 ValueError
142 If `id_or_action` is a string and `title` is not provided.
143 TypeError
144 If `id_or_action` is not a string or an `Action` object.
145
146 Examples
147 --------
148 This function can be used directly or as a decorator, and accepts arguments in
149 various forms.
150
151 ## Passing an existing Action object
152
153 When the `id_or_action` argument is an instance of `app_model.Action`, then
154 all other arguments are ignored, the action object is registered directly, and the
155 return value is a function that may be used to unregister the action is returned.
156
157 ```python
158 from app_model import Application, Action, register_action
159
160 app = Application.get_or_create("myapp")
161 action = Action("my_action", title="My Action", callback=lambda: print("hi"))
162 register_action(app, action)
163
164 app.commands.execute_command("my_action") # prints "hi"
165 ```
166
167 ## Creating a new Action
168
169 When the `id_or_action` argument is a string, it is interpreted as the `id`
170 of the command being registered, in which case `title` must then also be provided.
171 All other arguments are optional, but may be used to customize the action being
172 created (with keybindings, menus, icons, etc).
173
174 ```python
175 register_action(
176 app,
177 "my_action2",
178 title="My Action2",
179 callback=lambda: print("hello again!"),
180 )
181
182 app.commands.execute_command("my_action2") # prints "hello again!"
183 ```
184
185 ## Usage as a decorator
186
187 If `callback` is not provided, then a decorator is returned that can be used
188 decorate a function as the executor of the command:
189
190 ```python
191 @register_action(app, "my_action3", title="My Action3")
192 def my_action3():
193 print("hello again, again!")
194
195
196 app.commands.execute_command("my_action3") # prints "hello again, again!"
197 ```
198
199 ## Passing app as a string
200
201 Note that in all of the above examples, the first `app` argument may be either an
202 instance of an [`Application`][app_model.Application] object, or a string name of
203 an application. If a string is provided, then the application is retrieved or
204 created as necessary using
205 [`Application.get_or_create()`][app_model.Application.get_or_create].
206
207 ```python
208 register_action(
209 "myapp", # app name instead of Application instance
210 "my_action4",
211 title="My Action4",
212 callback=lambda: print("hello again, again, again!"),
213 )
214 ```
215 """
216 if isinstance(id_or_action, Action):
217 return _register_action_obj(app, id_or_action)
218 if isinstance(id_or_action, str):
219 if not title:
220 raise ValueError("'title' is required when 'id' is a string")
221 return _register_action_str(
222 app=app,
223 id=id_or_action,
224 title=title,
225 category=category,
226 tooltip=tooltip,
227 icon=icon,
228 enablement=enablement,
229 callback=callback,
230 palette=palette,
231 menus=menus,
232 keybindings=keybindings,
233 )
234 raise TypeError(
235 f"'id_or_action' must be a string or an Action not {type(id_or_action)}"
236 )
237
238
239 def _register_action_str(
240 app: Application | str, **kwargs: Any
241 ) -> CommandDecorator | DisposeCallable:
242 """Create and register an Action with a string id and title.
243
244 Helper for `register_action()`.
245
246 If `kwargs['callback']` is a callable, a complete `Action` is created
247 (thereby performing type validation and casting) and registered with the
248 corresponding registries. Otherwise a decorator returned that can be used
249 to decorate the callable that executes the action.
250 """
251 if kwargs.get("callback") is not None:
252 return _register_action_obj(app, Action(**kwargs))
253
254 def decorator(command: CommandCallable, **k: Any) -> CommandCallable:
255 if not callable(command):
256 raise TypeError(
257 "@register_action decorator must be passed a callable object"
258 )
259 _register_action_obj(app, Action(**{**kwargs, **k, "callback": command}))
260 return command
261
262 decorator.__doc__ = f"Decorate function as callback for command {kwargs['id']!r}"
263 return decorator
264
265
266 def _register_action_obj(app: Application | str, action: Action) -> DisposeCallable:
267 """Register an Action object. Return a function that unregisters the action.
268
269 Helper for `register_action()`.
270 """
271 from app_model._app import Application
272
273 app = app if isinstance(app, Application) else Application.get_or_create(app)
274 return app._register_action_obj(action)