#6157·xonsh

refactor: Move all xonsh session related global objects to xonsh session object

Author: anki-codeCreated Mar 20, 2026Updated Jul 8, 2026
Labelsneeds-discussionbuiltins

Long term meta issue.

Motivation

We need to have clear split two worlds:

  1. xonsh session Python objects
  • with private XonshSession (__xonsh__/xonsh.built_ins.XS)
  • and with public XonshSessionHandler (@/XSH)
  1. subprocess commands that manage the xonsh session.

XonshSessionHandler is a python object (public @/XSH). If we want to modify xonsh session we're using @. in xonsh mode and XSH. in Python mode. If we want to have CLI we can create built-in some alias and use it e.g. jobs, xontrib. So following this logic we need to move aliases, events objects into session.

Current inconsistency:

  • jobs - command
  • aliases - object
  • @.env - object (sounds clear - "xonsh session env")
  • events - object with list in __repr__
  • xontrib - command

Implementation

Consequences

Before:

xsh
aliases['a'] = 'echo a'

@aliases.register
def _a():
    echo a

@events.on_chdir
def _source_env_xsh(olddir, newdir):
    pass

After:

xsh
@.aliases['a'] = 'echo a'
XSH.aliases['a'] = 'echo a'

@@.aliases.register
def _a():
    echo a

@XSH.aliases.register
def _a():
    echo a

@XSH.events.on_chdir
def _source_env_xsh(olddir, newdir):
    pass

For community

⬇️ Please click the reaction instead of leaving a +1 or comment