Building the Swoop Library

GenerateSwoop.py generates the file Swoop.py, which contains a set of python classes for manipulating eagle files. The process relies on two bodies of information.

1. The contents of this file. It specifies the characteristic of each class that corresponds to a part of an eagle file. The file defines several classes (Attr, List, Map, Singleton, and TagClass) that specify how the Eagle classes should behave.

   This file describes a collections of classes that represent a “flattened” version of the XML format described in the Eagle DTD.

2. The contents of Swoop.jinja.py. This contains the template code for the classes, a base class for all the classes, and a class to represent eagle files, EagleFile.

The classes that this code generates each represent a part of an eagle file (class EagleFilePart). Instances of this class form a tree. The root of the tree is an instance of SchematicFile, BoardFile, or LibraryFile, all of which are subclasses of EagleFile.

Each EagleFilePart contains one or more attributes and one or more ‘collections’ (i.e., lists, maps, or singletons) of EagleFilePart objects. For instance, SchematicFile contains a collection that maps library names to Library objects, a list of Sheet objects, and a singleton Description instance.

This file defines the set of collections that each subclass of EagleFilePart contains. Each of these subclasses is represented by a TagClass object, which contains a list (called sections) of collections (represented by subclasses of Collection – namely Map, List, and Singleton). TagClass also includes a list of attributes (represented by Attr).

Each Attr, Map, List, and Singleton object includes information necessary to generate code for it. This includes mostly pedantic stuff like converting “-” to “_” in attribute names so they are valid python identifiers, dealing with eagle tag and attribute names that clash with python reserve words, and information about which attributes and tags are required and which are optional. There’s also some support for parsing values (e.g., converting “yes” to True).

The organization of the EagleFilePart hierarchy is similar to the structure of the eagle XML file. However, we make it easier to navigate by flattening it. For instance, in the eagle file layer defintions live in eagle/drawing/layers and sheets live in eagle/drawing/schematic/sheets. Our library “flattens” this hierarchy so that SchematicFile has a map of layers and a list of sheets.

To realize this flattened structure, we specify the contents of each collection using an xpath expression. All the elements that match the expression for Map, List, or Singleton will end up in that collection. The xpath expressions get passed the constructors for the Map, List, and Singleton.

The final stage is to generate the code. We use the jinja templating system for this. Swoop.jinja.py contains templates for the EagleFilePart subclasses. It generates code for the constructor, the from_et() method to convert for element tree to EagleFileParts, the get_et() method for the reverse conversion, a clone() function for copying EagleFileParts, and accessors for attributes (get_*() and set_*()) and collections (get_*() and add_*()).

Generating Extension to Swoop

You can also import GenerateSwoop as a module. In this case, it exposes the a map called tag that maps Eagle file XML tag names to Tag objects. You can then use this information however you would like to generate extensions to Swoop.

class Swoop.GenerateSwoop.Attr(name, required=False, parse=None, unparse=None, vtype=None, accessorName=None, xmlName=None, lookupEFP=None)

Class representing an attribute.

class Swoop.GenerateSwoop.Collection(name, xpath, accessorName=None, suppressAccessors=False, requireTag=False, containedTypes=None, dontsort=False)

Base class for collections.

class Swoop.GenerateSwoop.List(name, xpath, accessorName=None, suppressAccessors=False, requireTag=False, containedTypes=None)

Bases: Swoop.GenerateSwoop.Collection

Collection that is an ordered list

class Swoop.GenerateSwoop.Map(name, xpath, accessorName=None, suppressAccessors=False, requireTag=False, mapkey=None, containedTypes=None)

Bases: Swoop.GenerateSwoop.Collection

Collection that maps strings to items

class Swoop.GenerateSwoop.Singleton(name, xpath, accessorName=None, suppressAccessors=False, requireTag=False, containedTypes=None)

Bases: Swoop.GenerateSwoop.Collection

Collection with a single element

class Swoop.GenerateSwoop.TagClass(tag, baseclass=None, classname=None, customchild=False, preserveTextAs=None, attrs=None, sections=None, sortattr=None, dontsort=False)

Everything we need to know about an object that can hold the contents of a tag in order ot generate the classes for accessing it.