Last modified: August 2013

URL: https://cxc.cfa.harvard.edu/chips/ahelp/chips_decorators.html
AHELP for CIAO 4.11 ChIPS v1

chips_decorators

Context: contrib

Synopsis

Python decorators for ChIPS

Syntax

import chips_contrib.decorators as decorators
decorators.add_chips_undo_buffer
decorators.hide_chips_commands

Description

This module provides Python decorators for ChIPS. These decorators allow you to write routines that call multiple ChIPS commands and make the changes appear all at once.

Loading the routines

The module can be loaded into ChIPS, Sherpa or Python scripts by saying:

import chips_contrib.decorators as decorators

Contents

This module currenly provides two routines: add_chips_undo_buffer and hide_chips_commands.

Routine Overview
add_chips_undo_buffer The decorated function is run within a ChIPS undo buffer so that the results are only seen at the end of the routine, the ChIPS changes made by the routine can be undone with a single undo call, and any error within the function means that no ChIPS changes are made.
hide_chips_commands The decorated function is run with the window display setting changed to False, so that no changes are seen until the function ends, at which time the display is changed to True.

Example

The following code:

from pychips import *
from chips_contrib.decorators import add_chips_undo_buffer

@add_chips_undo_buffer()
def set_labels(xlabel=None, ylabel=None, title=None, size=18):
    "Sets the x, y and title labels, if set"

    if xlabel != None:
        set_plot_xlabel(xlabel)
        set_xaxis(['label.size', size])
    if ylabel != None:
        set_plot_ylabel(ylabel)
        set_yaxis(['label.size', size])
    if title != None:
        set_plot_title(title)
        set_plot(['title.size', size])

can be used in ChIPS (or a script) so that the calls appear to be made at once, and undo/redo treat set_labels as if it were a single ChIPS command:

chips> set_labels('X axis', 'Y axis', 'Plot title')
chips> undo()
chips> redo()

If the hide_chips_command decorator had been used instead, the changes would also appear as one, but the undo and redo commands would not behave as above, but instead you would step through all the changes made in the function.


Notes for the add_chips_undo_buffer decorator

This decorator should not be nested, i.e. do not apply it to a function that calls another function that uses it.

Notes for the hide_chips_commands decorator

This decorator is only designed for routines that work with a single window. It will work when no window exists, but it will not work if a window exists but the routine calls add_window to create a new window.

The window display is only set back to True at the end of the decorated routine if either the window existed when the routine started and its display value at that time was True, or if no window existed and the window.display preference setting was 'true'.

Changes in the scripts 4.5.4 (August 2013) release

The chips_contrib.decorators module is new in this release.

About Contributed Software

This module is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.