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:
- Receive session instance as an input argument
- Use session’s interfaces, a.k.a. Resources
- 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 takeshost
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
withself
as first argument:def chmod(self, mode): return self.xal_session.path.chmod(self, mode)