2 Starting and Using PyRAF Interactively

If PyRAF is installed (and your environment is properly configured), typing pyraf will start up PyRAF using the front-end interpreter. (There are a few command line options, described in §6, that can be listed using pyraf --help.) Here is an illustration of starting PyRAF and running some IRAF tasks using the CL emulation syntax.

% pyraf
setting terminal type to xterm...

    NOAO Sun/IRAF Revision 2.11.2 Wed Aug 11 13:24:18 MST 1999
    This is the EXPORT version of Sun/IRAF V2.11 for SunOS 4 and Solaris 2.7

    Welcome to IRAF.  To list the available commands, type ? or ??.  To get
    detailed information about a command, type `help command'.   To  run  a
    command  or  load  a  package,  type  its name.   Type  `bye' to exit a
    package, or `logout' to get out of the CL.   Type `news'  to  find  out
    what is new in the version of the system you are using.   The following
    commands or packages are currently defined:
--> imheader dev$pix long+
dev$pix[512,512][short]: m51  B  600s
No bad pixels, min=-1., max=19936.
Line storage mode, physdim [512,512], length of user area 1621 s.u.
Created Mon 23:54:13 31-Mar-1997, Last modified Mon 23:54:14 31-Mar-1997
Pixel file "HDR$pix.pix" [ok]
'KPNO-IRAF'           /
'31-03-97'            /
IRAF-MAX=           1.993600E4  /  DATA MAX
IRAF-MIN=          -1.000000E0  /  DATA MIN
IRAF-BPX=                   16  /  DATA BITS/PIXEL
IRAFTYPE= 'SHORT   '            /  PIXEL TYPE
HISTORY '24-04-87'
HISTORY 'KPNO-IRAF'           /
HISTORY '08-04-92'            /
--> imstat dev$pix
#               IMAGE      NPIX      MEAN    STDDEV       MIN       MAX
              dev$pix    261626     105.1     75.86       -1.     1000.
--> imcopy dev$pix mycopy.fits
dev$pix -> mycopy.fits
--> stsdas
      |       Space Telescope Science Data Analysis System         |
      |          STSDAS Version 2.1, September 29, 1999            |
      |                                                            |
      |   Space Telescope Science Institute, Baltimore, Maryland   |
      |         For help, send e-mail to            |
 analysis/      examples        hst_calib/      sobsolete/
 contrib/       fitsio/         playpen/        toolbox/
 describe       graphics/       problems
--> fitsio
--> catfits mycopy.fits

0     mycopy.fits                               512x512    16    m51  B  600s
--> imhead dev$pix long+ > devpix.header

You may notice a great similarity between the PyRAF login banner and the IRAF login banner. That's because PyRAF reads your normal file and goes through exactly the same startup steps as IRAF when a session begins. If you have customized your or files to load certain packages, define tasks, etc., then those customizations will also take effect in your PyRAF environment.

You can start up PyRAF from any directory; unlike the IRAF CL, you are not required to change to your IRAF home directory. PyRAF determines the location of your IRAF home directory by looking for your file, first in your current working directory and then in a directory named iraf in your home directory. So as long as your IRAF home directory is  /iraf, you can start up PyRAF from any working directory. (You can start from other directories as well, but without access to your IRAF environment will be only partly initialized. We expect to add a startup configuration file, .pyrafrc, that allows you customize your initial PyRAF configuration including your IRAF home directory.)

The first time you run PyRAF, it creates a pyraf directory in your IRAF home directory. At the moment all it stores there is a directory named clcache, which is used to save translated versions of your own custom CL scripts. (The files in that directory have cryptic names that actually encode the contents of the corresponding CL scripts, thus allowing the translation to be used regardless of the CL script name.)

Note that the task syntax shown above is identical to that of the IRAF CL. But there is no escaping that you are really running in a Python environment. Should you make a mistake typing a task name, for example,

--> imstart dev$pix
  File "<console>", line 1
    imstart dev$pix
SyntaxError: invalid syntax

or should you use other CL-style commands,

--> =cl.menus
  File "<console>", line 1
SyntaxError: invalid syntax

then you'll see a Python error message. At this stage, this is the most likely error you will see aside from IRAF-related ones. (We plan to improve some of these messages in the future to make them more self-explanatory for new PyRAF users.)

Aside from some noticeable delays (on startup, loading graphics modules, or in translating CL scripts not previously encountered), there should be little difference between running IRAF tasks in CL emulation mode and running them in the IRAF CL itself.

2.1 New Capabilities in PyRAF

Several capabilities in the PyRAF interpreter make it very convenient for interactive use. The up-arrow key can be used to recall previous commands (no need to type ehis!), and once recalled the left and right arrow keys can be used to edit it. The control-R key does pattern-matching on the history. Just type part of the command (not necessarily at the beginning of the line) and you'll see the matched command echoed on the command line. Type ^R again to see other matches. Hit return to re-execute a command, or other line-editing keys (left/right arrow, ^E, ^A, etc.) to edit the recalled command. There are many other ways to search and manipulate the history - see the gnu readline documentation for more information.

The tab key can be used to complete commands, in a way familiar to users of tcsh and similar shells. At the start of the command line, type imhe<tab> and PyRAF fills in imheader. Then type part of a filename <tab> and PyRAF fills in the rest of the name (or fills in the unambiguous parts and prints a list of alternatives). This can be a great timesaver for those long HST filenames! You can also use tab to complete IRAF task keyword names (e.g., imheader lon<tab> fills in longheader, to which you can add =yes or something similar). And when using Python syntax (see below), tab can be used to complete Python variable names, object attributes, etc.

The function

saveToFile filename

saves the current state of your PyRAF session to a file (including package, task, and IRAF environment variable definitions and the current values of all task parameters.) The function

restoreFromFile filename

restores the state of your session from its previously saved state. A save filename can also be given as a Unix command line argument when starting up PyRAF, in which case PyRAF is initialized to the state given in that file. This can be a very useful way both to start up in just the state you want and to reduce the startup time.

2.2 Differences from the CL and Unimplemented CL Features

Some differences in behavior between PyRAF and the CL are worth noting. PyRAF uses its own interactive graphics kernel when the CL stdgraph variable is set to a device handled by the CL itself (e.g., xgterm). If stdgraph is set to other values (e.g. stdplot or the imd devices), the appropriate CL task is called to create non-interactive plots. Currently only the default PyRAF graphics window supports interactive graphics (so you can't do interactive graphics on image display plots, for example.) Graphics output redirection is not implemented at the moment. Both full interactive support of additional graphics devices and graphics redirection are being considered for future development.

Some IRAF CL commands have the same names as Python commands; when you use them in PyRAF, you get the Python version. The ones most likely to be encountered by users are print and del. If you want to use the IRAF print command (which should rarely be needed), use clPrint instead. If you want the IRAF delete command, just type more of the command (either dele or delete will work).

Another similar conflict is that when an IRAF task name is identical to a reserved keyword in Python (to see a list, do import keyword; print keyword.kwlist), then it is necessary to prepend a 'PY' (yes, in capital letters) to the IRAF task name. Such conflicts should be relatively rare, but note that 'lambda' and 'in' are both Python keywords.

The PyRAF help command is a little different than the IRAF version. If given a string argument, it looks up the CL help and uses it if available. For other Python argument types, help gives information on the variable. E.g., help(module) gives information on the contents of a module. There are some optional arguments that are useful in Python programs (type help(help) for more information). We plan further enhancements of the help system in the near future.

If you need to access the standard IRAF help command without the additional PyRAF features, use taskname options.

Note that the IRAF help pages are taken directly from IRAF and do not reflect the special characteristics of PyRAF. For example, if you say help while, you get help on the CL while loop rather than the Python while statement. The login message on startup also comes directly from IRAF and may mention features not available (or superseded) in PyRAF. We will eventually remove some of these inconsistencies, but for the moment users will occasionally encounter such conflicts.

There are a few features of the CL environment and CL scripts that are not yet implemented:

Packages cannot be unloaded.
Currently there is no way to unload a loaded IRAF package. The bye command exists but does not do anything; the keep command also does nothing (effectively all modifications to loaded tasks and IRAF environment variables are kept). This will be added in a future version, although we are also considering alternative ways to organize the namespace of tasks and packages that may be more ``Pythonic''.

No GOTO statements in CL scripts.
Python does not have a goto statement, so converting CL scripts that use goto's to Python is difficult. At the moment we have made no effort to do such a conversion, so CL scripts with GOTO's raise exceptions. GOTOs may not ever get implemented.

Background execution is not available.
Background execution in CL scripts is ignored. This will get added if there is sufficient demand.

Error tracebacks in CL scripts do not print CL line numbers.
When errors occur in CL scripts, the error message and traceback refer to the line number in the Python translation of the CL code, not to the original CL code. We plan to add the CL code itself to the error messages eventually. (If you want to see the Python equivalent to a CL task, use the getCode method - e.g. print iraf.spy.getCode() to see the code for the spy task)..

Questions or comments? Contact
Documented updated on 2004 Jun 1