Python API

Significant portions of Razen are accessible programmatically via a Python API. This API can be divided into two main components:

  • The UI API, which enables manipulation of the Razen user interface
  • The Project API, which allows for creation and modification of objects in a Project or Part.

Entry Points

The Python API can be accessed in 3 different ways from within Razen:

  • The simplest method is by entering python at the Prompt.
  • For slightly more complex scripts, a Custom Script can be executed.
  • And for Importers, Exporters, Part Generators, and other complex API uses, a Plugin may be implemented

Prompt

The python prompt allows for single line Python commands to be executed. See the Command Prompt section of the interface documentation for an overview of its behaviour.

Custom Script

Custom scripts are python scripts with a main function that accepts a Project instance.

A simple example script is as follows:

def main(proj):
  proj.layout.text((0,0), "Hello World", 1, Layers.NameTop)

This will add the text “Hello World” to the current project’s layout.

See the Project for API details.

Plugin

Plugins are used to implement file import/export functionality, as well as for general scripting. A plugin consists of a directory in the plugin directory of the Razen distribution with at least one python file, with the same name as the directory.

A minimal plugin implementation consists of (in plugin/script/hello/hello.py):

from rzn.api import Plugin

class HelloWorldPlugin(Plugin):
  def __init__(self):
    Plugin.__init__(self, "Hello World", Plugin.SCRIPT)

  def main(self, ui):
    print "Hello World from plugin"

See the Plugin for API details.

Reference

UI

The UI API allows for basic scripting of the Razen user interface. The UI is based around Tabs - each tab holds a project (a design or part). The project is displayed in two views: schematic/layout or symbol/footprint respectively.

The UI API is passed to the main method of Plugin instances, as well as the command-prompt.

class rzn.api.ui.UI(win, bridgeclient)

UI API

actions()

Return a list of all available UI actions

currentTab()

Return the current Tab

doAction(actionName)

Triggers the UI action named ‘actionName’ as if the associated menu or button was pressed

libraryManager()

Returns the LibraryManager instance

logMessage(msg)

Log a message to the prompt and log file

newTab()

Creates and returns a new empty Tab

showOpenFileDialog(title, formatfilter='')

Show a file chooser dialog

showScriptOptionForm(options, presets=[])

Show a simple form dialog for script configuration

Return type:a dictionary mapping short option names to option values, or None

if the form was cancelled.

Parameters:
  • options – a list of tuples of (Pretty option name, short option name, Option instance)
  • presets – a list of tuples of (preset name, [option1 value, option2 value ..])

Script Form Options

class rzn.api.pluginoption.Option(default, typ)

Base option class

class rzn.api.pluginoption.IntOption(default=None)

Integer option class

class rzn.api.pluginoption.FloatOption(default=None)

Float option class

class rzn.api.pluginoption.BoolOption(default=True)

Boolean option class

class rzn.api.pluginoption.ListOption(values=[])

List-of-strings option class

Tab

Tabs are returned from currentTab() and newTab(). Each tab holds a project.

class rzn.api.ui.Tab(bridge, tabid)

Design Tab

close()

Close this tab

currentView()

Return the current View

load(filename, revision=None)

Load a design into this tab

project()

Return the current Project

save(message=None)

Save this tab

Parameters:message – log message to use on commit
saveAs(filename, message=None)

Save this tab to filename

Parameters:
  • filename – path to save this tab to
  • message – log message to use on commit
showView(viewname)

Switch to a view

Parameters:viewname – the view to show - ‘schematic’ or ‘layout’

View

Each tab has 2 views - Schematic and Layout - returned by currentView().

class rzn.api.ui.View(bridge, tabid, viewname)

Design View

currentTool()

Return the current tool in use in this view

getLayerVisible(layer)

Return a layer’s visibility

getToolOption(option)

Get the value of the option for the current tool

gridAlignPoint(pt)

Return a point aligned to the current view grid

name()

Return this view’s name (‘layout’ or ‘schematic’)

pan(dx, dy)

Pan (scroll) the current view

projectView()

Return this view on the project (Layout or Schematic)

select(objs)

Set the selection to the design objects objs

selection()

Return the objects in the current selection

setGridSpacing(um)

Set grid spacing dimensions (in um)

setLayerVisible(layer, visible=True)

Set a layer’s visibility

setToolOption(option, value)

Set the value of the option for the current tool

toggleLayerVisible(layer)

Toggle a layer’s visibility

Library

Parts libraries are accessible via the LibraryManger:

class rzn.api.library.LibraryManager

Library Manager

library(libName, userName=None)

Returns the Library named libName. If userName is not specified will user username configured in general.py. Returns library if it exists, otherwise None

newLibrary(libName, userName=None, readmeText='')

Create and initialise a new library

Return type:

a Library

Parameters:
  • libName – Library name
  • userName – User name. If not specified uses username from general.py
  • readmeText – option text to initialise the README.md file with

Libraries are repositories of parts.

class rzn.api.library.Library(name)

Library

part(name)

Returns a Part named name from this library Returns part if it exists, otherwise None

partNames()

Returns a list of names for the parts in this library

path()

Returns the path to this library

rev()

Returns the latest revision of this library

class rzn.api.library.Part(name, lib)

Part

path()

Returns the absolute path to this part

project()

Return the project for this part

rev()

Returns the latest revision of this part

Project

The Project API provides an interface to the core objects of a design. Each project has a schematic and layout member providing access to the respective views of the current design (part or project).

class rzn.api.Project(proj=None)

Project

copperlayers()

Return the number of copper layers in this project

dependencies()

Return a list of (libname, revision) tuples for this project’s dependencies

filename()

Returns this project’s filename

grid(v)

Set grid scaling factor for added objects

load(fn, rev=None)

Load a project

netnames()

Return the names of all nets on the schematic

part(name, pos, libn, partn)

Add a part to the project

save(fn)

Save a project

script(fn)

Execute the Python script file fn on this project

Schematic

class rzn.api.project.Schematic(apiproj)

Schematic

arc(pos, pa, pb, width, layer)

Add an arc to the schematic

drc(elts=None)

Run project DRC rules on the schematic (or a subset of objects)

find(name, regexp=True)

Return all objects with names matching the regexp

findAtPoint(pt, objtype=None)

Return all objects at a point

line(pa, pb, width, layer)

Add a line to the schematic

objs(objtype=None)

Returns all the objects in the schematic

pin(pos)

Add a pin to the schematic

rectangle(topleft, bottomright, width, layer)

Add a rectangle to the schematic

text(pos, text, size, layer)

Add text to the schematic

viewBounds()

Return the bounds of the schematic pages as a tuple [minx,miny,maxx,maxy]

wire(pa, pb, width=0, layer=95, name=None)

Add a wire to the schematic

wires(name, *pts)

Add a sequence of wires to the schematic

Layout

class rzn.api.project.Layout(apiproj)

Layout

arc(pos, pa, pb, width, layer)

Add an arc to the layout

drc(elts=None)

Run project DRC rules on the layout (or a subset of objects)

drill(pos, drill)

Add a drill to the layout

find(name, regexp=True)

Return all objects with names matching the regexp

findAtPoint(pt, objtype=None)

Return all objects at a point

line(pa, pb, width, layer)

Add a line to the layout

objs(objtype=None)

Returns all the objects in the layout

pad(pos, width, height, shape='circle', drill=0)

Add a pad to the layout

polygon(pos, points)

Add a polygon to the layout

rectangle(topleft, bottomright, width, layer)

Add a rectangle to the layout

text(pos, text, size, layer)

Add text to the layout

trace(pa, pb, width, layer, name=None)

Add a trace to the layout

via(pos, diameter, drill=25000)

Add a via to the layout

viewBounds()

Return the bounds of the layout as a tuple [minx,miny,maxx,maxy]

Layers

class rzn.api.Layers

Layers

classmethod mirror(layer)

Return the mirror of the specified layer. For example Layers.mirror(Layers.OutlineTop) return Layers.OutlineBottom

Transforms

class rzn.api.Transform(mat)

2D Transform

flipx()

Flip horizontally and return as a new Transform

flipy()

Flip vertically and return as a new Transform

classmethod ident()

Creates a new identity transform

point(x, y)

Transform the provided point

points(pts)

Transform a sequence of points

rot(angle)

Rotate by angle degrees and return as a new Transform

scale(x, y)

Scale and return as a new Transform

trans(x, y)

Translate and return as a new Transform

Objects

class rzn.api.obj.Text(parent, base, pos=(0, 0), value='', props=None, ghost=False)

Text object

class rzn.api.obj.SubPart(parent, base, pos=(0, 0), lib='', part='', name='', props=None, ghost=False)

SubPart

class rzn.api.obj.Connector(parent, base, properties, ghost)

Connector

class rzn.api.obj.Pin(parent, base, pos=(0, 0), props=None, ghost=False)

Pin

class rzn.api.obj.Pad(parent, base, pos=(0, 0), props=None, ghost=False)

Pad

class rzn.api.obj.Segment(parent, base, pta=(0, 0), ptb=(0, 0), name=None, props=None, ghost=False)

Segment

class rzn.api.obj.Airwire(parent, base, name, oa, ob)

Airwire

class rzn.api.obj.Arc(parent, base, pos=(0, 0), ofsa=(0, 0), ofsb=(0, 0), props=None, ghost=False, name=None)

Arc

class rzn.api.obj.Drill(parent, base, pos=(0, 0), dia=254, props=None, ghost=False)

Drill

class rzn.api.obj.Via(parent, base, pos=(0, 0), props=None, ghost=False)

Via

class rzn.api.obj.Polygon(parent, base, pos=(0, 0), pts=, []props=None, ghost=False)

Polygon

Plugin

Base Classes

The base plugin class should be subclassed for all plugins:

class rzn.api.Plugin(name, group=2, flags=0)

Plugin base class

Create a new plugin

Parameters:
  • name – Name of the plugin as it will appear in menus
  • group – Plugin type can be one of IMPORT, EXPORT, SCRIPT.
  • flags – Plugin flags
batchMain(project, options)

Main plugin entry-point when called from Command-line (batch mode). Re-implement in subclass

loadConfig(name)

Load the plugin config named <confpath>/plugin/<name>.json

main(ui)

Main plugin entry-point when called from UI. Re-implement in subclass

A plugin class for part generator scripts:

class rzn.api.GeneratorPlugin(name, options=, []presets=[])

Part generator plugin base class

Create a new generator plugin

Parameters:
footprint(options)

Implement this function to generate the part footprint

symbol(options)

Implement this function to generate the part symbol

Groups

A plugin can belong to one of the following groups:

Plugin.EXPORT

An exporter (shown in the file->export menu)

Plugin.IMPORT

An importer (shown in the file->import menu)

Plugin.SCRIPT

A generic script (shown in the tools->script menu)

Flags

Plugins can be flagged as follows:

Plugin.FLAG_PART_ONLY

This plugin is only usable in Parts

Plugin.FLAG_PROJECT_ONLY

This plugin is only usable in Projects