API Reference
QuartusTcl
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 launchingquartus_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
quartustcl.TclError
(*args)Base class for errors raised in this module.
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.
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.