Session API reference

The “NICOS session” object is a singleton instance that provides all global operations to any shell or daemon that uses NICOS devices. Its functions include the management of

• setups: loading and unloading setups
• devices: creating and shutting down devices
• special devices: providing access to special device instances
• namespace:
• the execution mode: switching modes
• logging: handling the various NICOS loggers
• notifications: sending notifications from devices or user code

class nicos.sessions.Session(appname)

The Session class provides all low-level routines needed for NICOS operations and keeps the global state: devices, configuration, loggers.

Within one NICOS process, there is only one singleton session object that is always importable using

from nicos import session

There are several specialized subclasses of Session; one of them will always be used in concrete applications.

Global configuration

config

A singleton for settings read from nicos.conf. See nicosconf.

auto_modules

A list of modules with user commands to be imported in every setup. By default, all modules under nicos.commands are imported, but this can be overridden in subclasss that do not need user commands.

autocreate_devices

A boolean that determines if the session automatically creates all non-lowlevel devices in a setup (if true), or if devices are created on-demand by calls to getDevice (if false).

cache

The NICOS cache client.

Mode handling

mode

The current execution mode of the session.

setMode(mode)

Set a new mode for the session.

This raises ModeError if the new mode cannot be switched to at the moment (for example, if switching to master mode, but another master is already active).

Logging

log

This is the root logger object. All output that is not specific to a device should be emitted using this logger. (The commands in nicos.commands.output also use this logger.)

getLogger(name)

Return a new NICOS logger for the specified device name.

addLogHandler(handler)

Add a new logging handler to the list of handlers for all NICOS loggers.

logUnhandledException(exc_info=None, cut_frames=0, msg='')

Log an unhandled exception (occurred during user scripts).

The exception is logged using the originating device’s logger, if that information is available.

Setup handling

setSetupPath(path)

Set the path to the setup files.

Normally, the setup path is given in nicos.conf and does not need to be set explicitly.

getSetupPath()

Return the current setup path.

getSetupInfo()

Return information about all existing setups.

This is a dictionary mapping setup name to another dictionary. The keys of that dictionary are those present in the setup files: ‘description’, ‘group’, ‘sysconfig’, ‘includes’, ‘excludes’, ‘modules’, ‘devices’, ‘startupcode’, ‘extended’.

See Configuring NICOS: Setups.

loadSetup(setupnames, allow_special=False, raise_failed=False, autocreate_devices=None)

Load one or more setup modules given in setupnames and set up devices accordingly.

If allow_special is true, special setups (with group “special”) are allowed, otherwise ConfigurationError is raised. If raise_failed is true, errors when creating devices are re-raised (otherwise, they are reported as warnings).

unloadSetup()

Unload the current setup.

This shuts down all created devices and clears the NICOS namespace.

handleInitialSetup(setup, simulate)

Determine which setup to load, and try to become master.

Called by sessions during startup.

shutdown()

Shut down the session: unload the setup and give up master mode.

Namespace management

The NICOS namespace is the namespace in which user code should be executed. Objects exported into the NICOS namespace are protected from overwriting by the user.

export(name, obj)

Export an object obj into the NICOS namespace with given name.

unexport(name, warn=True)

Unexport the object with name from the NICOS namespace.

getExportedObjects()

Return an iterable of all objects exported to the NICOS namespace.

Devices

getDevice(dev, cls=None)

Return a device dev from the current setup.

If dev is a string, the corresponding device will be looked up or created, if necessary.

cls gives a class, or tuple of classes, that dev needs to be an instance of.

createDevice(devname, recreate=False, explicit=False)

Create device given by a device name.

If device exists and recreate is true, destroy and create it again. If explicit is true, the device is added to the list of “explicitly created devices”.

destroyDevice(devname)

Shutdown a device and remove it from the list of created devices.

Special devices

instrument

The instrument device configured for the current setup. An instance of (a subclass of) nicos.instrument.Instrument.

experiment

The experiment device configured for the current setup. An instance of (a subclass of) nicos.experiment.Experiment.

notifiers

The notifier devices configured for the current setup. A list of instances of nicos.notify.Notifier.

datasinks

The data sinks configured for the current setup. A list of instances of nicos.data.DataSink.

Notification support

notify(subject, body, what=None, short=None, important=True)

Send a notification unconditionally.

notifyConditionally(runtime, subject, body, what=None, short=None, important=True)

Send a notification if the current runtime exceeds the configured minimum runtimer for notifications.

Miscellaneous

commandHandler(command, compiler)

This method is called when the user executes a simple command. It should return a compiled code object that is then executed instead of the command.

Session-specific behavior

These methods should be overridden in subclasses.

breakpoint(level)

Allow breaking or stopping the script at a well-defined time.

level can be 1 to indicate a breakpoint “after current scan” or 2 to indicate a breakpoint “after current step”.

updateLiveData(tag, filename, dtype, nx, ny, nt, time, data)

Send new live data to clients.

The parameters are:

• tag - a string describing the type of data that is sent. It is used by clients to determine if they can display this data.
• filename - a string giving the filename of the data once measurement is finished. Can be empty.
• dtype - a string describing the data array in numpy style, if it is in array format.
• nx, ny, nt - three integers giving the dimensions of the data array, if it is in array format.
• time - the current measurement time, for determining count rate.
• data - the actual data as a byte string.

clearExperiment()

Reset experiment-specific data.

checkAccess(required)

Check if the current user fulfills the requirements given in the required dictionary. Raise AccessError if check failed.

This is called by the requires decorator.