#
# KiCad python module for interpreting generic netlists which can be used
# to generate Bills of materials, etc.
#
# No string formatting is used on purpose as the only string formatting that
# is current compatible with python 2.4+ to 3.0+ is the '%' method, and that
# is due to be deprecated in 3.0+ soon
#
import sys
import xml.sax as sax
class component():
"""Class for a set of component information"""
def __init__(self, element):
self.element = element
self.libpart = None
# Set to true when this component is included in a component group
self.grouped = False
def __eq__(self, other):
"""Equlivalency operator, remember this can be easily overloaded"""
result = False
if self.getValue() == other.getValue():
if self.getLib() == other.getLib():
if self.getPart() == other.getPart():
result = True
return result
def setPart(self, part):
self.libpart = part
def setValue(self, value):
"""Set the value of this component"""
v = self.element.getChild("value")
if v:
v.setChars(value)
def getValue(self):
return self.element.get("value")
def getRef(self):
return self.element.get("comp", "ref")
def getFootprint(self):
return self.element.get("footprint")
def getDatasheet(self):
return self.element.get("datasheet")
def getLib(self):
return self.element.get("libsource", "lib")
def getPart(self):
return self.element.get("libsource", "part")
def getTimestamp(self):
return self.element.get("tstamp")
def getDescription(self):
# When attempting to access the part, we must take care in case the part
# cannot be found in the netlist
try:
d = self.libpart.getDescription()
except AttributeError:
d = ""
return d
def getDatasheet(self):
# When attempting to access the part, we must take care in case the part
# cannot be found in the netlist
try:
d = self.libpart.getDatasheet()
except AttributeError:
d = ""
return d
def getField(self, name):
"""Return the value of a field named name. The component is first
checked for the field, and then the components library part is checked
for the field. If the field doesn't exist in either, an empty string is
returned
Keywords:
name -- The name of the field to return the value for
"""
field = self.element.get("field", "name", name)
if field == "":
try:
field = self.libpart.getField(name)
except AttributeError:
field = ""
return field
class netlistElement():
"""Generic netlist element. All elements for a netlist tree which can be
used to easily generate various output formats by propogating format
requests to all children
"""
def __init__(self, name, parent=None):
self.name = name
self.attributes = {}
self.parent = parent
self.chars = ""
self.children = []
self.indent = ""
def __str__(self):
"""String representation of this netlist element
"""
return (self.name + "[" + self.chars + "]" + " attr:" +
str(len(self.attributes[a])))
def formatXML(self, amChild=False):
"""Return this element formatted as XML
Keywords:
amChild -- If set to True, the start of document is not returned
"""
s = ""
if not amChild:
s = "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
s += self.indent + "<" + self.name
for a in self.attributes:
s += " " + a + "=\"" + self.attributes[a] + "\""
if (len(self.chars) == 0) and (len(self.children) == 0):
s += "/>"
else:
s += ">" + self.chars
for c in self.children:
c.indent += self.indent + " "
s += "\n"
s += c.formatXML(True)
if (len(self.children) > 0):
s += "\n" + self.indent
if (len(self.children) > 0) or (len(self.chars) > 0):
s += "</" + self.name + ">"
return s
def formatHTML(self, amChild=False):
"""Return this element formatted as HTML
Keywords:
amChild -- If set to True, the start of document is not returned
"""
s = ""
if not amChild:
s = """<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title></title>
</head>
<body>
<table>
"""
s += "<tr><td><b>" + self.name + "</b><br>" + self.chars + "</td><td><ul>"
for a in self.attributes:
s += "<li>" + a + " = " + self.attributes[a] + "</li>"
s += "</ul></td></tr>\n"
for c in self.children:
s += c.formatHTML(True)
if not amChild:
s += """</table>
</body>
</html>"""
return s
def addAttribute(self, attr, value):
"""Add an attribute to this element"""
self.attributes[attr] = value
def setChars(self, chars):
"""Set the characters for this element"""
self.chars = chars
def addChars(self, chars):
"""Add characters (textual value) to this element"""
self.chars += chars
def addChild(self, child):
"""Add a child element to this element"""
self.children.append(child)
return self.children[len(self.children) - 1]
def getParent(self):
"""Get the parent of this element (Could be None)"""
return self.parent
def setAttribute(self, attr, value):
"""Set an attributes value - in fact does the same thing as add
attribute
"""
self.attributes[attr] = value
def getChild(self, name):
"""Returns a child element of name
Keywords:
name -- The name of the child element to return"""
for child in self.children:
if child.name == name:
return child
return None
def get(self, element, attribute="", attrmatch=""):
"""Return the data for either an attribute, or else an element"""
if (self.name == element):
if attribute != "":
if attrmatch != "":
if self.attributes[attribute] == attrmatch:
return self.chars
else:
return self.attributes[attribute]
else:
return self.chars
for child in self.children:
if child.get(element, attribute, attrmatch) != "":
return child.get(element, attribute, attrmatch)
return ""
class netlist():
""" Kicad generic netlist class. Generally loaded from a kicad generic
netlist file. Includes several helper functions to ease BOM creating
scripts
"""
def __init__(self, fname=""):
"""Initialiser for the genericNetlist class
Keywords:
fname -- The name of the generic netlist file to open (Optional)
"""
self.design = None
self.components = []
self.libparts = []
self.libraries = []
self.nets = []
# The entire tree is loaded into self.tree
self.tree = []
self._curr_element = None
if fname != "":
self.load(fname)
def addChars(self, content):
"""Add characters to the current element"""
self._curr_element.addChars(content)
def addElement(self, name):
"""Add a new kicad generic element to the list"""
if self._curr_element == None:
self.tree = netlistElement(name)
self._curr_element = self.tree
else:
self._curr_element = self._curr_element.addChild(
netlistElement(name, self._curr_element))
# If this element is a component, add it to the components list
if self._curr_element.name == "comp":
self.components.append(component(self._curr_element))
# Assign the design element
if self._curr_element.name == "design":
self.design = self._curr_element
# If this element is a library part, add it to the parts list
if self._curr_element.name == "libpart":
self.libparts.append(part(self._curr_element))
# If this element is a net, add it to the nets list
if self._curr_element.name == "net":
self.nets.append(self._curr_element)
# If this element is a library, add it to the libraries list
if self._curr_element.name == "library":
self.libraries.append(self._curr_element)
return self._curr_element
def endDocument(self):
"""Called when the netlist document has been fully parsed"""
# When the document is complete, the library parts must be linked to
# the components as they are seperate in the tree so as not to
# duplicate library part information for every component
for c in self.components:
for p in self.libparts:
if p.getPart() == c.getPart() and p.getLib() == c.getLib():
c.setPart(p)
def endElement(self):
"""End the current element and switch to its parent"""
self._curr_element = self._curr_element.getParent()
def getDate(self):
"""Return the date + time string generated by the tree creation tool"""
return self.design.get("date")
def getSource(self):
"""Return the source string for the design"""
return self.design.get("source")
def getTool(self):
"""Return the tool string which was used to create the netlist tree"""
return self.design.get("tool")
def groupComponents(self):
"""Return a list of component lists. Components are grouped together
when the value, library and part identifiers match
"""
groups = []
# Make sure to start off will all components ungrouped to begin with
for c in self.components:
c.grouped = False
# Group components based on the value, library and part identifiers
for c in self.components:
if c.grouped == False:
c.grouped = True
newgroup = []
newgroup.append(c)
# Check every other ungrouped component against this component
# and add to the group as necessary
for ci in self.components:
if ci.grouped == False and ci == c:
newgroup.append(ci)
ci.grouped = True
# Add the new component group to the groups list
groups.append(newgroup)
# Each group is a list of components, we need to sort each list first
# to get them in order as this makes for easier to read BOM's
for g in groups:
g = sorted(g, key=lambda g: g.getRef())
# Finally, sort the groups to order the references alphabetically
groups = sorted(groups, key=lambda group: group[0].getRef())
return groups
def formatXML(self):
"""Return the whole netlist formatted in XML"""
return self.tree.formatXML()
def formatHTML(self):
"""Return the whole netlist formatted in HTML"""
return self.tree.formatHTML()
def load(self, fname):
"""Load a kicad generic netlist
Keywords:
fname -- The name of the generic netlist file to open
"""
try:
self._reader = sax.make_parser()
self._reader.setContentHandler(_gNetReader(self))
self._reader.parse(fname)
except IOError as e:
print >> sys.stderr, __file__, ":", e
sys.exit(-1)
class part():
"""Class for a library part"""
def __init__(self, part):
# The part is a reference to a libpart generic netlist element
self.element = part
def __str__(self):
# simply print the generic netlist element associated with this part
return str(self.element)
def getDatasheet(self):
return self.element.get("docs")
def getLib(self):
return self.element.get("libpart", "lib")
def getPart(self):
return self.element.get("libpart", "part")
def getDescription(self):
return self.element.get("description")
def getField(self, name):
return self.element.get("field", "name", name)
class _gNetReader(sax.handler.ContentHandler):
"""SAX kicad generic netlist content handler - passes most of the work back
to the gNetlist class which builds a complete tree in RAM for the design
"""
def __init__(self, aParent):
self.parent = aParent
def startElement(self, name, attrs):
"""Start of a new XML element event"""
element = self.parent.addElement(name)
for name in attrs.getNames():
element.addAttribute(name, attrs.getValue(name))
def endElement(self, name):
self.parent.endElement()
def characters(self, content):
# Ignore erroneous white space - ignoreableWhitespace does not get rid
# of the need for this!
if not content.isspace():
self.parent.addChars(content)
def endDocument(self):
"""End of the XML document event"""
self.parent.endDocument()
