Core Events

The following events are defined by xonsh itself. For more information about events, see the events tutorial.

on_chdir

on_envvar_change

on_envvar_new

on_exit

on_import_post_create_module

on_import_post_exec_module

on_import_post_find_spec

on_import_pre_create_module

on_import_pre_exec_module

on_import_pre_find_spec

on_post_cmdloop

on_post_init

on_post_prompt

on_post_rc

on_postcommand

on_pre_cmdloop

on_pre_prompt

on_pre_rc

on_pre_spec_run_ls

on_precommand

on_ptk_create

on_transform_command

Listing

on_chdir(olddir: str, newdir: str) -> None

Fires when the current directory is changed for any reason.


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_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 (0 for success)

  • out: If xonsh stores command output, this is the output

  • ts: 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 the prompt is shown


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.

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_<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 recieves 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_<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!")