API Reference

QuartusTcl

class quartustcl.QuartusTcl(args=[‘quartus_stp’, ‘-s’], debug=False)

A class for managing a Quartus Tcl interpreter as a subprocess.

Arguments

  • args - the Quartus Tcl subshell to launch, in a format suitable for subprocess.Popen. This defaults to launching quartus_stp.

  • debug - if True, write input and output of the subshell to stderr.

Usage

Communication with the subshell is done via methods. Some simple methods are provided, but methods not documented here are turned directly into Tcl commands. For example:

quartus.get_device_names(hardware_name="Foo Bar")

will result in running

get_device_names -hardware_name {Foo Bar}

All methods will return their result as a string. If the Tcl result is a list, you will need to use parse to turn it into a Python list.

Closing

The Tcl subprocess will be automatically closed when this object goes out of scope. For more explicit control, use the close method. This object can also be used as a context manager:

with quartustcl.QuartusTcl() as quartus:
    # … use quartus …

The Tcl subprocess will be closed automatically at the end of the block.

call(self, cmd, *args, **kwargs)

Run a Tcl command with the given arguments and optional arguments, then return the resulting string. If an error is raised, it is re-raised in Python as a TclEvalError.

cmd is a bare Tcl command. For example:

quartus.call('get_device_names', hardware_name="Foo Bar")

is equivalent to running

get_device_names -hardware_name {Foo Bar}
close(self, timeout=None)

Close the Tcl subprocess. After calling this, you will no longer be able to evaluate Tcl using this object.

If timeout is specified, determines how long to wait for the subprocess to exit.

This is safe to call multiple times.

eval(self, script, *args)

Write a script to the Tcl interpreter, and read the result out as a string. If the script raises an error, that Tcl error will be raised in Python as a TclEvalError.

script can be a format string, which will be filled out with the remaining arguments. If used this way, the remaining arguments are quoted using quote. For example:

quartus.eval("get_device_names -hardware_name {}", "Foo Bar")

is equivalent to running

get_device_names -hardware_name {Foo Bar}

in the Tcl interpreter subprocess. If you do not want this automatic quoting, you can use the usual format() method on strings.

parse(self, data, levels=1)

Parse a Tcl-formatted list into a Python list.

If levels is specified, this sets how many levels of the list to convert. If you know you are dealing with nested lists two levels deep, use levels=2 to parse both in one call.

If parsing fails, this will raise TclParseError.

quote(self, data)

Wrap a string in the Tcl necessary for it to evaluate to the original string. For example:

quartus.eval("puts " + quartus.quote("$var [{]"))

will result in printing the string “$var [{]” to standard out. This is required to work around reserved syntax in the Tcl language.

Exceptions

class quartustcl.TclError(*args)

Base class for errors raised in this module.

class quartustcl.TclEvalError(message, return_code, error_code, error_info)

This error is raised whenever the Tcl subprocess encounters an error. It exposes four attributes:

  • message - the cause of the error, as a human-friendly string

  • return_code - the Tcl return code of the command, as an integer

  • error_code - the cause of the error, as a machine-friendly list. This is parsed directly from $errorCode inside Tcl.

  • error_info - the cause of the error, as a longer human-friendly string. This is parsed directly from $errorInfo inside Tcl.

class quartustcl.TclParseError(value)

This error is raised by QuartusTcl.parse when Python attempts to parse something as a list that is not actually a list.