.. _contextmanager:

.. _PyJAMAS: https://bitbucket.org/rfg_lab/pyjamas/src/master/

===================================
Using PyJAMAS_ as a context manager
===================================

When developing PyJAMAS_ plugins, or when using the PyJAMAS_ API in your code, it can be convenient to use/create a PyJAMAS_ instance that iterates over multiple images and/or annotation files. In that case, PyJAMAS_ can be used as a context manager in a **with** block. This means that, when the **with** block ends, the state of the PyJAMAS_ instance (including the open image, annotations, classifier, etc.) will be restored to what it was *before* the **with** block.

This code block illustrates how to use PyJAMAS_ as a context manager that loops over a list of images, applies a Gaussian filter, and saves the resulting image.

.. code-block:: python

 from pyjamas.rplugins.base import PJSPluginABC
 from pyjamas.pjscore import PyJAMAS

 apjs = PyJAMAS()
 old_image = apjs.slices.copy()

 # here we assume that a list of paths exists in list_of_image_paths.
 with apjs:
     for an_image_path in list_of_image_paths:
        apjs.io.cbLoadTimeSeries(an_image_path)  # load the image.
        apjs.image.cbGaussianImage(sigma=2.0)  # apply Gaussian filter.
        apjs.io.cbSaveTimeSeries(an_image_path + "_gaussian")  # save the image.

 # here, apjs will be restored to its state prior to the with block, and thus, this assertion should be True.
 assert apjs.slices == old_image