Core Events¶
The following events are defined by xonsh itself. For more information about events, see the events tutorial.
Listing¶
on_chdir(olddir: str, newdir: str) -> None¶
Fires when the current directory is changed for any reason.
on_command_not_found(cmd: list[str]) -> None¶
Fires if a command is not found (only in interactive sessions).
Parameters:
cmd: The command that was attempted
on_envvar_change(name: str, oldvalue: Any, newvalue: Any) -> None¶
Fires after an environment variable is changed. Note: Setting envvars inside the handler might cause a recursion until the limit.
on_envvar_new(name: str, value: Any) -> None¶
Fires after a new environment variable is created. Note: Setting envvars inside the handler might cause a recursion until the limit.
on_exit() -> None¶
Fired after all commands have been executed, before tear-down occurs.
NOTE: All the caveats of the atexit module also apply to this event.
on_import_post_create_module(module: Module, spec: ModuleSpec) -> None¶
Fires after a module is created by its loader but before the loader returns it. The parameters here are the module object itself and the spec object. See importlib for more details.
on_import_post_exec_module¶
on_import_post_create_module(module: Module) -> None
Fires after a module is executed by its loader but before the loader returns it. The only parameter is the module itself. See importlib for more details.
on_import_post_find_spec(spec, fullname, path, target) -> None¶
Fires after all import find_spec() calls have been executed. The parameters here the spec and the arguments importlib.abc.MetaPathFinder.find_spec(). Namely,
spec:A ModuleSpec object if the spec was found, or None if it was not.
fullname:The full name of the module to import.
path:None if a top-level import, otherwise the
__path__of the parent package.target:Target module used to make a better guess about the package spec.
on_import_pre_create_module(spec: ModuleSpec) -> None¶
Fires right before a module is created by its loader. The only parameter is the spec object. See importlib for more details.
on_import_pre_exec_module(module: Module) -> None¶
Fires right before a module is executed by its loader. The only parameter is the module itself. See importlib for more details.
on_import_pre_find_spec(fullname: str, path: str, target: module or None) -> None¶
Fires before any import find_spec() calls have been executed. The parameters here are the same as importlib.abc.MetaPathFinder.find_spec(). Namely,
fullname:The full name of the module to import.
path:None if a top-level import, otherwise the
__path__of the parent package.target:Target module used to make a better guess about the package spec.
on_lscolors_change(key: str, oldvalue: Any, newvalue: Any) -> None¶
Fires after a value in LS_COLORS changes, when a new key is added (oldvalue is None) or when an existing key is deleted (newvalue is None). LS_COLORS values must be (ANSI color) strings, None is unambiguous. Does not fire when the whole environment variable changes (see on_envvar_change). Does not fire for each value when LS_COLORS is first instantiated. Normal usage is to arm the event handler, then read (not modify) all existing values.
on_post_cmdloop() -> None¶
Fired just after the command loop finishes, if it is.
NOTE: All the caveats of the atexit module also apply to this event.
on_post_init() -> None¶
Fired after all initialization is finished and we’re ready to do work.
NOTE: This is fired before the wizard is automatically started.
on_post_prompt() -> None¶
Fires just after the prompt returns
on_post_rc() -> None¶
Fired just after rc files are loaded, if they are.
on_postcommand(cmd: str, rtn: int, out: str or None, ts: list) -> None¶
Fires just after a command is executed. The arguments are the same as history.
Parameters:
cmd: The command that was executed (after transformation)rtn: The result of the command executed (0for success)out: If xonsh stores command output, this is the outputts: Timestamps, in the order of[starting, ending]
on_pre_cmdloop() -> None¶
Fired just before the command loop is started, if it is.
on_pre_prompt() -> None¶
Fires just before showing the prompt
on_pre_prompt_format() -> None¶
Fires before the prompt will be formatted
on_pre_rc() -> None¶
Fired just before rc files are loaded, if they are.
on_pre_spec_run_ls(spec: xonsh.built_ins.SubprocSpec) -> None¶
Fires right before a SubprocSpec.run() is called for the ls command.
on_precommand(cmd: str) -> None¶
Fires just before a command is executed.
on_ptk_create(prompter: PromptSession, history: PromptToolkitHistory, completer: PromptToolkitCompleter, bindings: KeyBindings) ->¶
Fired after prompt toolkit has been initialized
on_transform_command(cmd: str) -> str¶
Fired to request xontribs to transform a command line. Return the transformed command, or the same command if no transformation occurs. Only done for interactive sessions.
This may be fired multiple times per command, with other transformers input or output, so design any handlers for this carefully.
on_xonfig_info_requested() -> list[tuple[str, str]]¶
Register a callable that will return extra info when xonfig info is called.
on_xontribs_loaded() -> None¶
Fired after external xontribs with entrypoints defined are loaded.
Event Categories¶
Additionally, there are a few categories of events whose names are part of the specification of the event. These events are fired if they exist, and are ignored otherwise. Here are their specifications.
on_pre_spec_run(spec: SubprocSpec) -> None¶
This event fires whenever any command has its SubprocSpec.run()
method called. This is fired prior to the run call executing anything
at all. This receives the SubprocSpec object as spec that triggered
the event, allowing the handler to modify the spec if needed. For example,
if we wanted to intercept all specs, we could write:
@events.on_pre_spec_run
def print_when_ls(spec=None, **kwargs):
print("Running a command")
on_pre_spec_run_<cmd-name>(spec: SubprocSpec) -> None¶
This event fires whenever a command with a give name (<cmd-name>)
has its SubprocSpec.run() method called. This is fired
prior to the run call executing anything at all. This receives the
SubprocSpec object as spec that triggered the event, allowing
the handler to modify the spec if needed. For example, if we wanted to
intercept an ls spec, we could write:
@events.on_pre_spec_run_ls
def print_when_ls(spec=None, **kwargs):
print("Look at me list stuff!")
on_post_spec_run(spec: SubprocSpec) -> None¶
This event fires whenever any command has its SubprocSpec.run()
method called. This is fired after to the run call has executed
everything except returning. This recieves the SubprocSpec object as
spec that triggered the event, allowing the handler to modify the spec
if needed. Note that because of the way process pipelines and specs work
in xonsh, the command will have started running, but won’t necessarily have
completed. This is because SubprocSpec.run() does not block.
For example, if we wanted to get any spec after a command has started running,
we could write:
@events.on_post_spec_run
def print_while_ls(spec=None, **kwargs):
print("A command is running")
on_post_spec_run_<cmd-name>(spec: SubprocSpec) -> None¶
This event fires whenever a command with a give name (<cmd-name>)
has its SubprocSpec.run() method called. This is fired
after to the run call has executed everything except returning. This recieves the
SubprocSpec object as spec that triggered the event, allowing
the handler to modify the spec if needed. Note that because of the
way process pipelines and specs work in xonsh, the command will have
started running, but won’t necessarily have completed. This is because
SubprocSpec.run() does not block.
For example, if we wanted to get an ls spec after ls has started running,
we could write:
@events.on_post_spec_run_ls
def print_while_ls(spec=None, **kwargs):
print("Mom! I'm listing!")