Sessions

In xal, sessions encapsulate implementation of resources APIs.

Quickstart

In order to use xal or related libraries:

1. Create session instance 3. Use session’s interfaces, a.k.a. Resources

>>> import xal
>>> session = xal.LocalSession()
>>> session.sh.run('echo -n "Hello"').stdout
'Hello'

In order to write xal-powered scripts or libraries:

  1. Receive session instance as an input argument
  2. Use session’s interfaces, a.k.a. Resources
  3. Users of your library will care of session initialization
>>> def hello(session):
...    return session.sh.run('echo -n "Hello"').stdout

>>> hello(session)
'Hello'

At the moment, xal provides two pre-configured session classes:

  • LocalSession for use on localhost. Basically uses Python builtins.

    Initialization method takes no arguments:

    >>> xal.LocalSession()  
    <xal.session.local.LocalSession object at 0x...>
    
  • FabricSession for use on remote SSH sessions. Uses Fabric and Fabtools.

    Client’s connect() method takes host argument. Other SSH configuration is (currently) taken from ssh_config:

    >>> xal.FabricSession(host='localhost')
    <xal.session.fabric.FabricSession object at 0x...>
    

Warning

Default pip install xal doesn’t install specific dependencies for SSH or local sessions. You need things like pip install xal[ssh]. See Installation for details.

Client

Client is a special provider for xal sessions. Its primary purpose it to encapsulate connection with the system. At initialization, session do an implicit call to the client’s connect() method.

What’s make “client” interface special is that the signature of connect() method is specific to providers.

See quickstart above for basic use cases and connection options.

Registry

Sessions hold a registry of providers. As an example, LocalSession().sh is mapped to LocalShProvider, which itself implements the API for sh resources.

In most situations, you don’t have to bother with registry, because session instance acts as a router to adequate item in registry.

>>> session.registry  # doctest: +ELLIPSIS
<xal.registry.Registry object at 0x...>
>>> sorted(session.registry.items.keys())
['client', 'dir', 'path', 'sh', 'sys']
>>> session.registry('sh')  # doctest: +ELLIPSIS
<xal.sh.local.LocalShProvider object at 0x...>
>>> session.sh is session.registry('sh')
True

xal_session attribute

At the moment, xal makes big use of a special xal_session attribute.

In most situations, you don’t have to bother with xal_session attribute.

But, if you are curious, here are some hints:

  • when providers are registered in session, they are assigned a reference to the session as xal_session attribute. It makes it possible, in providers’ implementation, to use other interfaces of the session.

    As an example, Fabric-based implementation of path API uses session’s sh API via self.xal_session.sh:

        def cwd(self):
            """Return resource representing current working directory."""
            local_path = self.xal_session.sh.run('pwd').stdout.strip()
            return self(str(local_path))
    
  • when providers instanciate a ressource, they assign a reference to the session as xal_session attribute. It makes it possible to have generic resource classes that take advantage of providers’ specific implementation.

    As an example, Path resource is generic, but most methods just redirect to self.xal_session.path with self as first argument:

        def chmod(self, mode):
            return self.xal_session.path.chmod(self, mode)