buildmytasks¶
-
buildmytasks
()¶ An executable application included within the casashell module for creating custom CASA tasks
- Description
How to create your own CASA tasks using the
buildmytasks
executable included alongside the casashell environmentWarning
This prescription for writing and incorporating tasks in CASA is for the power-user. This procedure may also change in future releases.
The Basics
It is possible to write your own task and have it appear in CASA. For example, if you want to create a task named yourtask, then must create two files, yourtask.xml and a task_yourtask.py. The .*xml file is use to describe the interface to the task and the task_yourtask.py does the actual work. The argument names must be the same in both the yourtask.xml and task_yourtask.py file. The yourtask.xml file is used to generate all the interface files so **yourtask* will appear in the CASA system. It is easiest to start from one of the existing tasks when constructing these. You would make the name of the function in the yourtask.py be yourtask in this example.
We have provided the buildmytasks command in order to assemble your Python and XML into a loadable Python file. The steps you need to execute (again for an example task named “yourtask”):
Create python code for task as task_yourtask.py
Create XML for task as yourtask.xml
Execute buildmytasks
Import your new task into CASA
We will work through these steps now with the assumption that you already have your XML file and task implementation. If you need to create these from scratch, the documentation below will provide help.
The first thing that you need to do is add the bin directory for CASA to your path:
#Setup your environment for Linux -bash$ cd casa-6.2.0-94/bin -bash$ PATH=`pwd`:$PATH
If your XML file is from CASA 5, then it needs to be updated for CASA 6:
#Upgrading the XML in <your-development-path> -bash$ cd <your-development-path> -bash$ buildmytasks --upgrade yourtask.xml upgrading yourtask.xml -bash$
This step only needs to be done once. The old version is stored in yourtask.xml.bak. The update is done with an XML processor which modifies the XML without changing the content. However, if you had large sections of comments you should copy these from yourtask.xml.bak back into the updated yourtask.xml since these comments are not retained in the conversion. A discussion of XML changes between CASA 5 and CASA 6 can be found in the casatools bitbucket page.
In CASA 6, buildmytasks generates tasks that are designed to be inside of a Python package. You should decide what you want your package to be called, create it, and copy your XML file into it:
#Create a package -bash$ mkdir -p yourpkg/private -bash$ cp yourtask.xml yourpkg -bash$ cp task_yourtask.py yourpkg/private -bash$ cd yourpkg
Now buildmytask can be used to create yourtask along with the code needed to support inp/go/etc:
#Generate task -bash$ buildmytasks --module yourpkg yourtask.xml generating task for yourtask.xml generating 'go task' for yourtask.xml -bash$
This adds yourtask to the yourpkg package, but you still have to export yourtask to allow it to be accessible by users:
#Export task -bash$ echo '__name__ = "yourpkg"' > __init__.py -bash$ echo '__all__ = [ "yourtask" ]' >> __init__.py -bash$ echo 'from .yourtask import yourtask' >> __init__.py
At this point, you should find a yourtask.py in the current directory and a gotasks subdirectory with the inp/go implementation inside it. The commands we just executed created a minimal initialization file for yourpkg, and we can now test our new task:
#Test new task -bash$ cd .. -bash$ ls -p yourpkg gotasks/ yourtask.py yourtask.xml __init__.py private/ -bash$ casa CASA <1>: sys.path.insert(0,'.') CASA <2>: from yourpkg.gotasks.yourtask import yourtask CASA <3>: inp(yourtask)
This should display the help and inputs for yourtask inside CASA. Now you can set the parameters with inp, reset the defaults with default, save and restore parameters with tput and tget and run the task with go. The location of yourpkg must be in your PYTHONPATH; the first CASA <1> command added the current directory to the path used for imports.
If you have other tasks, you can put their XML files in yourpkg. Generate the bindings with buildmytasks, and then edit __init__.py to export any that you want the user to have available.
The XML file
The key to getting your task into CASA is constructing a task interface description XML file.
Some XML basics, an xml element begins with <element> and ends with </element>. If an XML element contains no other XML element you may specify it via <element/>. An XML element may have zero or more attributes which are specified by attribute="attribute value". You must put the attribute value in quotes, i.e. <element myattribute="attribute value">.
All task xml files must start with this header information.
<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" ?> <casaxml xmlns="http://casa.nrao.edu/schema/psetTypes.html" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://casa.nrao.edu/schema/casa.xsd file:///opt/casa/code/xmlcasa/xml/casa.xsd">
and the file must have the end tag
</casaxml>
Inside a <task> tags you will need to specify the following elements:
<task> Attributes type required, allowed value is "function" name required Subelements shortdescription required description required input optional output optional returns optional constraints optional <shortdescription> - required by <task>; A short one-line description describing your task Attributes None Subelements None <description> - required] by <task>, Also used by <param>; A longer description describing your task with multiple lines Attributes None Subelements None <input> - optional element used by <task>; An input block specifies which parameters are used for input Attributes None Subelements <param> - optional <output> - optional An output element that contains a list of parameters that are "returned" by the task. Attributes None Subelements <param> - optional <returns> - optional Value returned by the task Attributes type optional; as specified in <param> Subelements <description> - optional <constraints> - optional A constraints element that lets you constrain params based on the values of other params. Attributes None Subelements <when> - required. <param> - optional The input and output elements consist of param elements. Attributes type - required; allowed values are record, variant, string int, double, bool, intArray, doubleArray, boolArray, stringArray name - required; subparam - optional; allowed values True, False, Yes or No. kind - optional; mustexist - optional; allowed values True, False, Yes or No. All param elements require name and type attributes. Subelements <description> - required; <value> - optional; <allowed> - optional; <value> - optional Value returned by the task Attributes type - required; as specified in <param> attributes. Subelements <value> - optional <allowed> - optional; Block of allowed values Attributes enum - required; maybe enum or range. If specified as enum only specific values are allowed If specified as range then the value tags may have min and max attributes. Subelements <value> - optional <when> - optional When blocks allow value specific handling for parameters Attributes param - required; Specifies special handling for a <param> Subelements <equals> - optional <notequals> - optional <equals> - optional Reset parameters if equal to the specified value Attributes value - required; the value of the parameter Subelements <default> - required <notequals> - optional Reset specified parameters if not equal to the specified value Attributes value - required; The value of the parameter Subelements <default> - optional <default> - optional Resets default values for specified parameters Attributes param - required; Name of the <param> to be reset. Subelements <value> - required, the revised value of the <param>. <example> - optional An example block, typically in python Attributes lang optional; specifies the language of the example, defaults to python. Subelements None
The task yourtask.py file
You must write the python code that does the actual work. The
task_*.py
file function call sequence must be the same as specified in the XML file. We may relax the requirement that the function call sequence exactly match the sequence in the XML file in a future release.