 |
 |
 |
The PyRAF Tutorial |  |
 |
|
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.
You may notice a great similarity between the PyRAF login banner and the IRAF login banner. That's because PyRAF reads your normal login.cl file and goes through exactly the same startup steps as IRAF when a session begins. If you have customized your login.cl or loginuser.cl 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 login.cl 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 login.cl 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,
or should you use other CL-style commands,
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.
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
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
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.
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 system.help 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:
print iraf.spy.getCode()
to see the code for the spy task)..
 | Questions or comments? Contact help@stsci.edu Documented updated on 2004 Jun 1 |