cpl.ui

CPL UI submodule

This module provides the features to implement data processing modules (recipes) which can be executed using the ESO data processing environments. It provides the plugin API needed to implement these modules as well as the data types to pass data and configuration parameters to these modules.

exception cpl.ui.RecipeNotFoundException
class cpl.ui.AbstractRecipe

Abstract Base Class to be used by PyRecipe

class cpl.ui.CRecipe

Interface for initialising and executing compiled CPL recipes written in C. The default recipe dir is set on installation as the esopipes-plugin directory in the configured CPLDIR/lib directory.

Modifying any parameters stored in the the recipe’s parameters property will not have any effect on execution. Any settings from the default parameters must be passed to the settings parameter in the run method.

run(self: cpl.ui.CRecipe, input_frames: cpl.ui.FrameSet, settings: Dict[str, float | bool | str | int] = {}) → cpl.ui.FrameSet

Execute a recipe. As the parameters property is just a copy, custom parameter settings should be set in this method call.

Parameters:

  • input_frames (cpl.ui.FrameSet) – Input FrameSet for the recipe to use as inputs

  • settings (dict) – {parameter_name : value} pairs for configuring recipe parameters for execution.

Returns:

A FrameSet of all frames with cpl.ui.Frame.FrameGroup.PRODUCT, indicating them as the recipe’s output

Return type:

cpl.ui.FrameSet

Raises:

RuntimeError – if a recipe error occurs.

Notes

All files generated during execution are saved in ./products/(recipe_name)_(folder_no) relative to the current working directory. After running, these files will not be deleted by PyCPL if not deleted by the recipe binaries themselves and remain on disk for the user to manage themselves for their own uses.

property author

Name of the recipe’s author

property copyright

Recipe’s license and copyright information. Must be compatible with that of CPL.

property email

Author’s contact information

property name

Unique name of the Recipe

property parameters

A list of recipe parameters and their defaults. This is a copy, not a reference.

property synopsis

Detailed description of a plugin.

property version

Recipe version number

class cpl.ui.Frame

A frame is a container for descriptive attributes related to a data file. The attributes are related to a data file through the file name member of the frame type. Among the attributes which may be assigned to a data file is an attribute identifying the type of the data stored in the file (image or table data), a classification tag indicating the kind of data the file contains and an attribute denoting to which group the data file belongs (raw, processed or calibration file). For processed data a processing level indicates whether the product is an temporary, intermediate or final product.

class FrameGroup

Members:

NONE

CALIB

PRODUCT

RAW

property name
class FrameLevel

Members:

NONE

TEMPORARY

INTERMEDIATE

FINAL

property name
class FrameType

Members:

NONE

MATRIX

IMAGE

PAF

TABLE

ANY

property name
as_ccddata(self: cpl.ui.Frame, **kwargs) → object

Wrapper function of astropy’s astropy.nddata.read constructor to convert the frame to astropy CCDData object. Refer to the documentation of astropy.nddata.read for more details

as_hdulist(self: cpl.ui.Frame, **kwargs) → object

Convenience function to convert the frame to astropy HDUList object. Any kwargs passed to this function is passed down to astropy.io.fits.open. Refer to the documentation of astropy.io.fits.open for more details

dump(self: cpl.ui.Frame, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump the Frame contents to a file, stdout or a string.

This function is mainly intended for debug purposes.

Parameters:

  • filename (str, optional) – file path to dump frame contents to

  • mode (str, optional) – File mode to save the file, default ‘w’ overwrites contents.

  • show (bool, optional) – Send frame contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the frame contents.

Return type:

str

property file

filename of the frame

Type:

str

property group

The frame group data type.

Type:

cpl.ui.FrameGroup

property level

The frame processing level

Type:

cpl.ui.FrameLevel

property tag

Category tag for the frame

Type:

str

property type

The frame type data type.

Type:

cpl.ui.FrameType

class cpl.ui.FrameSet

Frames can be stored in a frame set and retrieved by index and sequential access. Frame sets can be created, filled and saved to a ‘set of frames’ file or loaded from such a file.

Framesets are intended to be used for passing fits file information to and from recipes.

Frames are accessed by index or iteration.

append(self: cpl.ui.FrameSet, frame: cpl.ui.Frame) → None

Insert a frame into the given frame set.

The function adds the frame frame to the frame set using the frame’s tag as key.

Parameters:

frame (cpl.ui.Frame) – The frame to insert.

dump(self: cpl.ui.FrameSet, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump the FrameSet contents to a file, stdout or a string.

This function is mainly intended for debug purposes.

Parameters:

  • filename (str, optional) – file path to dump frameset contents to

  • mode (str, optional) – File mode to save the file, default ‘w’ overwrites contents.

  • show (bool, optional) – Send frameset contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the frameset contents.

Return type:

str

sign_products(self: cpl.ui.FrameSet, compute_md5: bool = True, compute_checksum: bool = True) → None

Update DFS and DICB required header information of frames in the frameset

Parameters:

  • compute_md5 (bool, optional) – Boolean Flag to compute the DATAMD5 hash and add to the product header

  • compute_checksum (bool, optional) – Flag to compute the standard FITS checksums

Return type:

None

Notes

The function takes all frames marked as products from the input frameset.

update_product_header(self: cpl.ui.FrameSet) → None

Perform any DFS-compliancy required actions (DATAMD5/PIPEFILE update) on the frames in the framest

Return type:

None

Raises:

Notes

Each product frame must correspond to a FITS file created with a CPL FITS saving function.

class cpl.ui.Parameter

Parameters provide a standard way to pass, for instance, command line information to different components of an application.

The fundamental parts of a parameter are its name, a context to which it belongs (a specific component of an application for instance), its current value and a default value.

The implementation supports three classes of parameters:

  • A plain value (cpl.ui.ParameterValue)

  • A range of values (cpl.ui.ParameterRange)

  • An enumeration value (cpl.ui.ParameterEnum)

cpl.ui.Parameter is the base class for the three parameter classes.

When a parameter is created it is created for a particular value type. The type of a parameter’s current and default value may be:

  • cpl.core.Type.BOOL

  • cpl.core.Type.INT

  • cpl.core.Type.DOUBLE

  • cpl.core.Type.STRING

These types are inferred upon Parameter creation.

(NOTE: as of writing the validation of parameter values on assignment is not yet implemented in CPL. PyCPL does not intend to layer this feature over CPL and thus will not include validation until CPL itself does.)

class ParameterMode

Members:

CLI

ENV

CFG

property name
property context

The context in which the parameter belongs to

property data_type

CPL data type of the parameter

property description

comment or description describing the parameter

property help

description on how the parameter is used and its effects

property name

The read-only unique name of the parameter

property tag

user definable tag

class cpl.ui.ParameterEnum

Enumeration parameter. On construction expects the default value, followed by the list of the possible enumeration values. Note that the default value must be a member of the list of possible enumeration. values.

CPL data type is inferred on default value given.

Inherits all properties in cpl.ui.ParameterValue and cpl.ui.Parameter

Parameters:

  • name (str) – The unique name of the parameter

  • description (str) – comment or description describing the parameter

  • context (str) – The context in which the parameter belongs to

  • default (int, float or str) – The default and initialised value of the parameter

  • alternatives (list of int, float or str) – list of enumeration alternatives, including the default value. Must be of the same type as default.

dump(self: cpl.ui.ParameterEnum, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump a parameter contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

  • filename (str, optional) – File to dump parameter contents to

  • mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).

  • show (bool, optional) – Send parameter contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the parameter contents.

Return type:

str

property alternatives

possible enumeration alternatives value can be

class cpl.ui.ParameterList

Container type for cpl.ui.Parameter.

It provides a convenient way to pass a set of parameters to various functions e.g. recipes.

Parameters are accessed by index or iteration.

append(self: cpl.ui.ParameterList, param: cpl.ui.Parameter) → None

Append a parameter to the end of a ParameterList.

Parameters:

param (cpl.ui.Parameter) – parameter to insert

dump(self: cpl.ui.ParameterList, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump a parameter list contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

  • filename (str, optional) – File to dump parameter list contents to

  • mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).

  • show (bool, optional) – Send parameter list contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the parameter list contents.

Return type:

str

class cpl.ui.ParameterRange

Range parameter. On construction expects the default value, followed by the minimum value and the maximum value. CPL data type is inferred on default value given.

Inherits all properties in cpl.ui.ParameterValue and cpl.ui.Parameter

Parameters:

  • name (str) – The unique name of the parameter

  • description (str) – comment or description describing the parameter

  • context (str) – The context in which the parameter belongs to

  • default (int or float) – The default and initialised value of the parameter

  • min (int or float) – Minimum value of the parameter. Must be of the same data type as default.

  • max (int or float) – Maximum value of the parameter. Must be of the same data type as default.

dump(self: cpl.ui.ParameterRange, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump a parameter contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

  • filename (str, optional) – File to dump parameter contents to

  • mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).

  • show (bool, optional) – Send parameter contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the parameter contents.

Return type:

str

property default

Default value of the parameter

property max

Maximum value of the parameter

property min

Minimum value of the parameter

property value

Current value of the parameter

class cpl.ui.ParameterValue

Plain parameter value. Stores a single value with no boundaries. CPL data type is inferred on default value given.

Inherits all properties in cpl.ui.Parameter

Parameters:

  • name (str) – The unique name of the parameter

  • description (str) – comment or description describing the parameter

  • context (str) – The context in which the parameter belongs to

  • default (bool, int, float or str) – The default and initialised value of the parameter

dump(self: cpl.ui.ParameterValue, filename: str | None = '', mode: str | None = 'w', show: bool | None = True) → str

Dump a parameter contents to a file, stdout or a string.

Each element is preceded by its index number (starting with 1!) and written on a single line.

Comment lines start with the hash character.

Parameters:

  • filename (str, optional) – File to dump parameter contents to

  • mode (str, optional) – Mode to open the file with. Defaults to “w” (write, overwriting the contents of the file if it already exists), but can also be set to “a” (append, creating the file if it does not already exist or appending to the end of it if it does).

  • show (bool, optional) – Send parameter contents to stdout. Defaults to True.

Returns:

Multiline string containing the dump of the parameter contents.

Return type:

str

property cfg_alias

named used to identify the parameter being set in a .cfg file

property cli_alias

named used to identify the parameter being set as a the command line parameter

property data_type

CPL data type of the parameter

property default

default value of the parameter

property env_alias

named used to identify the parameter being set as an environment variable

property presence

flag to indicate if the parameter has been changed from its default

property value

current value of the parameter

class cpl.ui.PyRecipe

PyRecipe base class for the implementation of custom Python recipes.

When inheriting this class the following members are expected to be overwitten:

  • _name

  • _author

  • _copyright

  • _description

  • _email

  • _synopsis

  • _version

  • run(frameset,settings)

It is also recommended that new recipes include their own docstrings. New __init__ and __del__ methods can be written to handle data before/after execution.