EagleFilePart and Its Subclasses

EagleFilePart is the core of Swoop.

Eagle files are stored as XML and are, therefore, tree-structured. The Swoop data structures are trees of EagleFilePart objects that closely resemble the Eagle file’s structure. However, the tree structure of the file formats has been flattened to make them easier to use. For instance, in the Eagle file layer definitions live in eagle/drawing/layers and sheets live in eagle/drawing/schematic/sheets. Swoop flattens this hierarchy so that a SchematicFile object has a map of layers and a list of sheets.

The EagleFilePart base class provides some simple functions for traversing and modifying the EagleFilePart tree (i.e., getting the parent and children and attaching and removing EagleFilePart objects).

There are subclasses of EagleFilePart that represent all the component of an Eagle file, and each EagleFilePart subclass corresponds to a XML tag in the Eagle file. There is one subclass of EagleFilePart for each different XML elements that can exist in an Eagle file. Each subclass contains members that correspond to attributes of that element and the sub-elements the element contains (subject to the flattening describe above).

There are four broad categories of EagleFilePart subclasses:

1. The base class EagleFilePart is the baseclass for all other classes in the Swoop.
2. File classes SchematicFile , BoardFile , and LibraryFile represent the three file types. They share a common baseclass: EagleFile.
3. Container classes These include Library, Deviceset, Sheet , and many others classes that define high-level entities in an Eagle file.
4. Leaf classes These inlude Wire, Smd, Note and many others that represent the basic building blocks of the Eagle files.

The container subclasses contain multiple collections of sub-elements. These collections are stored either lists or maps. The order of the sub-elements in lists corresponds to their order in the Eagle file. For maps, the key is usually the sub-element’s name attribute. Subclasses may also contain singleton sub-elements and attributes (which correspond to attributes in the Eagle file format).

The Symbol class illustrates all of these possibilities. It includes a singleton Description sub-element, a list of DrawingElement sub-elements, and a map matching pin names to Pin sub-elements. It also includes a single attribute called name.

Subclasses provide a variety of methods to access, modify, and query sub-elements and attributes. These methods follow a consistent naming convention. Attributes and can be accessed or modified the methods end with _<attr> where <attr> is the attribute name. Singletons accessors are similar. For lists and maps, the methods end with _<subelement>s or _<subelement> or where <subelement> is the name of the list or map in question. For instance, Symbol.get_drawing_elements() returns the drawing elements of the Symbol object, and Symbol.get_pin() finds the Pin object given its name.

Each of the standard accessors and mutators is described below after the documentation for EagleFilePart itself. For details on specific subclasses, see the documentation for those classes.

EagleFilePart

class Swoop.EagleFilePart

Bases: object

Base class for all eagle tag objects. It provides fallback implementations of core features, facilities for navagating the part tree, and provides the parent attribute.

check_sanity()

Perform a (recursive) sanity check on this EagleFilePart

Return type:None

clone()

Clone the EagleFilePart. It should be identical to the orginial, except that the parent should be None.

Return type:EagleFilePart

detach()

Remove this :class:’EagleFilePart` from its parent.

Returns:self Return type:EagleFilePart

get_children()

Return a list of all the EagleFilePart children of this EagleFilePart

Return type:List of EagleFilePart objects

get_et()

Generate an element tree that represents the EagleFilePart.

Return type:etree.ElementTree

get_file()

Get the EagleFile containing this object.

Return type:EagleFile

get_parent()

Get this object’s parent.

Returns:The object’s parent. Return type:EagleFilePart

get_root()

Find the root of this EagleFilePart tree.

Return type:EagleFilePart

make_from()

Create a a From object containing this object.

Returns:From object containing this object. Return type:From

with_type(t)

Filter this EagleFilePart object based on its type. For use in combination with From objects.

Return self if self is an instance of type t and None otherwise. This is useful in combination with From object.

Parameters:t – The type to check for. Returns:self if self is an instance of type t and None otherwise. Return type:EagelFilePart or None

Accessor Methods

<subclass>.get_<sub-element/attr>()

For attributes and singletons.

Returns:The singleton object or attribute value. Return type:EagleFilePart

<subclass>.find_<attr>()

For some attributes.

Find the object refered to by this attribute. This is similar ot get_, except it returns the object instead of its name.

For example, consider these ways to query the libary that at Element refers to:

# e = some element
libname = e.get_library()    # Gets the name of the library
lib = e.find_library()       # Gets the library object.

Returns:The object Return type:EagleFilePart

<subclass>.get_<sub-element>(key)

For maps.

Lookup and return the sub-element corresponding to key from this object.

Parameters:key – A str to use for the lookup. Returns:The EagleFilePart object corresponding to key or None, if there is no such item. Return type:EagleFilePart

<subclass>.get_<sub-elements>(attrs=None, type=None)

For maps and lists.

Return (and possibly filter) items in the the <sub-elements> for this object. The order of elements in maps in arbitrary.

This functions provides a mechanism for filtering the items as well. The keys in attrs are taken as attributes names and the values are requested values. If the attributes and values match for an sub-element, it will be included in the returned list.

A if type is not None, the item will match if it is an instance of the type provided.

For instance:

# s = a symbol
s.get_drawing_elements(type=Swoop.Wire, attrs={"width" : 0.1})

Will return the wires in s with a width of 0.1 mm.

Parameters:

• attrs – A set of key-value pairs that represent a filter to apply to the item’s attributes.
• type – A type to filter on. Only items that are an instance of this type will be returned.

Returns:

The list of objects that match the query, if provided

Return type:

List of objects

<subclass>.EagleFilePart.get_children(efp)

Returns:A list of all children of this object. Return type:List of EagleFilePart objects

Mutator Methods

<subclass>.set_<attr/singleton>(value)

For attributes and singletons.

Set the value of the attr attribute of this object.

For example, to set the size of a hole to 1mm:

hole.set_drill(1.0)

Parameters:value – New value Returns:The object. Return type:EagleFilePart

<subclass>.clear_<sub-element>()

For maps and lists.

Remove all the children in the map or list.

:returns : self :rtype EagleFilePart

<subclass>.remove_<sub-element>()

For maps and lists.

Remove a EagleFilePart from this object.

Parameters:efp – The object to remove. Returns:self Return type:EagleFilePart

<subclass>.EagleFilePart.remove_child(efp)

For maps and lists

Remove efp as a child of this object, regardless of type.

Returns:self Return type:EagleFilePart

<subclass>.add_<subelement>(new_child)

For maps and lists.

Add a :code:’<subelement>’ to this object.

Parameters:s – The EagleFilePart object to add. Returns:self Return type:EagleFilePart

<subclass>.get_nth_<subelement>(index)

For maps and lists.

Return the index <subelement> of this object. For maps, the ordering of the items in the list is arbitrary, but will be consistent across calls if the contents of the map has not changed.

Parameters:index – The index of the subelement to access. Returns:The EagleFilePart object Return type:EagleFilePart

Query Methods

<subclass>.with_<attr>(value)

For attributes.

Filter this EagleFilePart object based on the value of the attribute. For use in combination with From objects.

Return self if one of the following is true:

1. <attr> equals v
2. v`is callable and :code:`v(self.get_<attr>()) is True

For example, get Element objects from a board that come from the library named “KoalaBuild” or whose name starts with “Koala”:

From(brd).get_elements().with_library("KoalaBuild")
From(brd).get_elements().with_library(lambda x: re.match(x,"Koala.*") is not None)

Parameters:t – The value to check for or a callable object. Returns:self if the criteria above are met and None otherwise. Return type:EagelFilePart or None