KiCad File Format Classes

This section documents all KiCad-specific classes organized by file format and functionality.

Main File Format Classes

These classes represent complete KiCad file formats with from_file() and save_to_file() support.

kicadfiles.board_layout module

PCB board files (.kicad_pcb) including footprints, traces, zones, and board settings.

Board layout elements for KiCad S-expressions - PCB/board design and routing.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class BoardArc(start=<factory>, mid=<factory>, end=<factory>, width=<factory>, layer=<factory>, net=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Board arc track segment definition.

The ‘arc’ token defines an arc-shaped track segment in the format:

(arc
    (start X Y)
    (mid X Y)
    (end X Y)
    (width WIDTH)
    (layer LAYER)
    (net NET_NUMBER)
    (uuid UUID)
)

Parameters:

start (Start) – Start point of the arc
mid (Mid) – Mid point of the arc
end (End) – End point of the arc
width (NamedFloat) – Track width
layer (NamedString) – Layer name
net (NamedInt) – Net number
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, width=<factory>, layer=<factory>, net=<factory>, uuid=<factory>)

class BoardLayers(layer_defs=<factory>)[source]

Bases: NamedObject

Board layer definitions for kicad_pcb files.

Stores layer definitions as raw lists:

(layers (0 "F.Cu" signal) (2 "B.Cu" signal) ...)

Use get_layer(index) to parse a specific layer as LayerDefinition if needed.

__init__(layer_defs=<factory>)

to_sexpr()[source]

Convert to S-expression format.

class End(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

End point definition token.

The ‘end’ token defines an end point in the format:

(end X Y)

Parameters:

x (float) – Horizontal position of the end point
y (float) – Vertical position of the end point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Footprint(library_link=None, version=<factory>, generator=<factory>, generator_version=<factory>, locked=<factory>, placed=<factory>, layer=<factory>, tedit=<factory>, uuid=None, at=None, descr=<factory>, tags=<factory>, properties=<factory>, path=None, sheetname=<factory>, sheetfile=<factory>, attr=<factory>, autoplace_cost90=None, autoplace_cost180=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=<factory>, solder_paste_ratio=None, clearance=<factory>, zone_connect=None, thermal_width=<factory>, thermal_gap=<factory>, private_layers=<factory>, net_tie_pad_groups=<factory>, pads=<factory>, models=<factory>, fp_elements=<factory>, embedded_fonts=<factory>, embedded_files=<factory>)[source]

Bases: NamedObject

Footprint definition token that defines a complete footprint.

The ‘footprint’ token defines a footprint with all its elements in the format:

(footprint
    ["LIBRARY_LINK"]
    [locked]
    [placed]
    (layer LAYER_DEFINITIONS)
    (tedit TIME_STAMP)
    [(uuid UUID)]
    [POSITION_IDENTIFIER]
    [(descr "DESCRIPTION")]
    [(tags "NAME")]
    [(property "KEY" "VALUE") ...]
    (path "PATH")
    [(autoplace_cost90 COST)]
    [(autoplace_cost180 COST)]
    [(solder_mask_margin MARGIN)]
    [(solder_paste_margin MARGIN)]
    [(solder_paste_ratio RATIO)]
    [(clearance CLEARANCE)]
    [(zone_connect CONNECTION_TYPE)]
    [(thermal_width WIDTH)]
    [(thermal_gap DISTANCE)]
    [ATTRIBUTES]
    [(private_layers LAYER_DEFINITIONS)]
    [(net_tie_pad_groups PAD_GROUP_DEFINITIONS)]
    GRAPHIC_ITEMS...
    PADS...
    ZONES...
    GROUPS...
    3D_MODEL
)

Parameters:

library_link (str | None) – Link to footprint library (optional)
version (NamedInt) – File format version (optional)
generator (NamedString) – Generator application (optional)
generator_version (NamedString) – Generator version (optional)
locked (TokenFlag) – Whether the footprint cannot be edited (optional)
placed (TokenFlag) – Whether the footprint has been placed (optional)
layer (Layer) – Layer the footprint is placed on
tedit (NamedString) – Last edit timestamp (optional)
uuid (Uuid | None) – Unique identifier for board footprints (optional)
at (At | None) – Position and rotation coordinates (optional)
descr (NamedString) – Description of the footprint (optional)
tags (NamedString) – Search tags for the footprint (optional)
properties (List[Property] | None) – List of footprint properties (optional)
path (str | None) – Hierarchical path of linked schematic symbol (optional)
sheetname (NamedString) – Schematic sheet name (optional)
sheetfile (NamedString) – Schematic sheet file (optional)
attr (Attr) – Footprint attributes (optional)
autoplace_cost90 (int | None) – Vertical cost for automatic placement (optional)
autoplace_cost180 (int | None) – Horizontal cost for automatic placement (optional)
solder_mask_margin (float | None) – Solder mask distance from pads (optional)
solder_paste_margin (float | None) – Solder paste distance from pads (optional)
solder_paste_margin_ratio (NamedFloat) – Solder paste margin ratio (optional)
solder_paste_ratio (float | None) – Percentage of pad size for solder paste (optional)
clearance (NamedFloat) – Clearance to board copper objects (optional)
zone_connect (int | None) – How pads connect to filled zones (optional)
thermal_width (NamedFloat) – Thermal relief spoke width (optional)
thermal_gap (NamedFloat) – Distance from pad to zone for thermal relief (optional)
private_layers (List[str] | None) – List of private layers (optional)
net_tie_pad_groups (NetTiePadGroups) – Net tie pad groups (optional)
pads (List[Pad] | None) – List of pads (optional)
models (List[Model] | None) – List of 3D models (optional)
fp_elements (List[FpArc | FpCircle | FpCurve | FpLine | FpPoly | FpRect | FpText] | None) – List of footprint graphical elements (optional)
embedded_fonts (TokenFlag) – Embedded fonts settings (optional)
embedded_files (EmbeddedFiles) – Embedded files container (optional)

__init__(library_link=None, version=<factory>, generator=<factory>, generator_version=<factory>, locked=<factory>, placed=<factory>, layer=<factory>, tedit=<factory>, uuid=None, at=None, descr=<factory>, tags=<factory>, properties=<factory>, path=None, sheetname=<factory>, sheetfile=<factory>, attr=<factory>, autoplace_cost90=None, autoplace_cost180=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=<factory>, solder_paste_ratio=None, clearance=<factory>, zone_connect=None, thermal_width=<factory>, thermal_gap=<factory>, private_layers=<factory>, net_tie_pad_groups=<factory>, pads=<factory>, models=<factory>, fp_elements=<factory>, embedded_fonts=<factory>, embedded_files=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for footprint operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_mod file format.

Parameters:

file_path (str) – Path to write the .kicad_mod file
encoding (str) – File encoding (default: utf-8)

class General(thickness=<factory>, legacy_teardrops=<factory>)[source]

Bases: NamedObject

General board settings definition token.

The ‘general’ token defines general board settings in the format:

(general
    (thickness THICKNESS)
    [(legacy_teardrops yes|no)]
)

Parameters:

thickness (NamedFloat) – Board thickness
legacy_teardrops (TokenFlag) – Whether to use legacy teardrops (optional)

__init__(thickness=<factory>, legacy_teardrops=<factory>)

class GrArc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Graphical arc definition token.

The ‘gr_arc’ token defines an arc graphic object in the format:

(gr_arc
    (start X Y)
    (mid X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

start (Start) – Start point coordinates
mid (Mid) – Mid point coordinates
end (End) – End point coordinates
stroke (Stroke) – Stroke definition (optional)
layer (Layer) – Layer definition (optional)
width (NamedFloat) – Line width (deprecated, use stroke) (optional)
uuid (Uuid) – Unique identifier

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)

class GrLine(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: FpLine

Graphical line derived from footprint line.

Inherits all fields from FpLine but uses ‘gr_line’ token.

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)

class GrPoly(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: FpPoly

Graphical polygon derived from footprint polygon.

Inherits all fields from FpPoly but uses ‘gr_poly’ token.

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class GrText(text='', at=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>)[source]

Bases: NamedObject

Graphical text definition token.

The ‘gr_text’ token defines text graphic objects in the format:

(gr_text
    "TEXT"
    POSITION_IDENTIFIER
    (layer LAYER_DEFINITION [knockout])
    (uuid UUID)
    (effects TEXT_EFFECTS)
)

Parameters:

text (str) – Text content
at (At) – Position and rotation coordinates
layer (Layer) – Layer definition
uuid (Uuid) – Unique identifier
effects (Effects) – Text effects

__init__(text='', at=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>)

class Group(name='', uuid=None, members=None)[source]

Bases: NamedObject

Group definition token.

The ‘group’ token defines a group of objects in the format:

(group
    "NAME"
    (uuid UUID)
    (members UUID1 ... UUIDN)
)

Parameters:

name (str) – Group name
uuid (Uuid | None) – Group unique identifier (optional)
members (Members | None) – List of member UUIDs (optional)

__init__(name='', uuid=None, members=None)

class KicadPcb(version=<factory>, generator=<factory>, generator_version=<factory>, general=<factory>, page=<factory>, paper=<factory>, layers=<factory>, setup=<factory>, embedded_fonts=<factory>, properties=<factory>, nets=<factory>, footprints=<factory>, gr_elements=<factory>, arcs=<factory>, groups=<factory>, segments=<factory>, vias=<factory>, zones=<factory>)[source]

Bases: NamedObject

KiCad PCB board file definition.

The ‘kicad_pcb’ token defines a complete PCB board file in the format:

(kicad_pcb
    (version VERSION)
    (generator GENERATOR)
    (general ...)
    (paper "SIZE")
    (page ...)
    (layers ...)
    (setup ...)
    [(property ...)]
    [(net ...)]
    [(footprint ...)]
    [(gr_text ...)]
    [(segment ...)]
    [(via ...)]
    [(zone ...)]
)

Parameters:

version (NamedInt) – File format version
generator (NamedString) – Generator application
generator_version (NamedString) – Generator version (optional)
general (General | None) – General board settings (optional)
page (NamedString) – Page settings (optional)
paper (NamedString) – Paper size specification (optional)
layers (BoardLayers | None) – Layer definitions (optional)
setup (Setup | None) – Board setup (optional)
embedded_fonts (NamedString) – Whether fonts are embedded (yes/no) (optional)
properties (List[Property]) – Board properties
nets (List[Net]) – Net definitions
footprints (List[Footprint]) – Footprint instances
gr_elements (List[GrText | GrLine | GrArc | GrPoly] | None) – List of board graphical elements (optional)
arcs (List[BoardArc]) – Arc track segments
groups (List[Group]) – Group definitions
segments (List[Segment]) – Track segments
vias (List[Via]) – Via definitions
zones (List[Zone]) – Zone definitions

__init__(version=<factory>, generator=<factory>, generator_version=<factory>, general=<factory>, page=<factory>, paper=<factory>, layers=<factory>, setup=<factory>, embedded_fonts=<factory>, properties=<factory>, nets=<factory>, footprints=<factory>, gr_elements=<factory>, arcs=<factory>, groups=<factory>, segments=<factory>, vias=<factory>, zones=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for PCB operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_pcb file format.

Parameters:

file_path (str) – Path to write the .kicad_pcb file
encoding (str) – File encoding (default: utf-8)

class Layer(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)[source]

Bases: NamedObject

Layer definition token.

The ‘layer’ token defines layer information in the format:

(layer "NAME" | dielectric NUMBER (type "DESCRIPTION")
       [(color "COLOR")] [(thickness THICKNESS)]
       [(material "MATERIAL")] [(epsilon_r VALUE)]
       [(loss_tangent VALUE)])

For simple layer references:: (layer “LAYER_NAME”)

Parameters:

name (str) – Layer name or ‘dielectric’
number (int | None) – Layer stack number (optional)
type (str | None) – Layer type description (optional)
color (str | None) – Layer color as string (optional)
thickness (float | None) – Layer thickness value (optional)
material (str | None) – Material name (optional)
epsilon_r (float | None) – Dielectric constant value (optional)
loss_tangent (float | None) – Loss tangent value (optional)

__init__(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)

class Layers(layers=<factory>)[source]

Bases: NamedObject

Layer list definition token.

The ‘layers’ token defines a list of layer names in the format:

(layers "F.Cu" "F.Paste" "F.Mask")
(layers "*.Cu" "*.Mask" "F.SilkS")

Used for pad layers, via layers, and other layer specifications.

layers

List of layer names

Type:: List[str]

Parameters:: layers (List[str]) – List of layer names

__init__(layers=<factory>)

class Mid(x=0.0, y=0.0)[source]

Bases: NamedObject

Mid point definition token.

The ‘mid’ token defines a mid point in the format:

(mid X Y)

Parameters:

x (float) – Horizontal position of the mid point
y (float) – Vertical position of the mid point

__init__(x=0.0, y=0.0)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Net(number=0, name='')[source]

Bases: NamedObject

Net connection definition token.

The ‘net’ token defines the net connection in the format:

(net ORDINAL "NET_NAME")

Parameters:

number (int) – Net number
name (str) – Net name

__init__(number=0, name='')

class Nets(net_definitions=<factory>)[source]

Bases: NamedObject

Nets section definition token.

The ‘nets’ token defines nets for the board in the format:

(net
    ORDINAL
    "NET_NAME"
)

Parameters:: net_definitions (List[tuple[Any, ...]]) – List of net definitions (ordinal, net_name)

__init__(net_definitions=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class PcbPlotParams(layerselection=<factory>, plot_on_all_layers_selection=<factory>, disableapertmacros=<factory>, usegerberextensions=<factory>, usegerberattributes=<factory>, usegerberadvancedattributes=<factory>, creategerberjobfile=<factory>, dashed_line_dash_ratio=<factory>, dashed_line_gap_ratio=<factory>, svgprecision=<factory>, plotframeref=<factory>, mode=<factory>, useauxorigin=<factory>, hpglpennumber=<factory>, hpglpenspeed=<factory>, hpglpendiameter=<factory>, pdf_front_fp_property_popups=<factory>, pdf_back_fp_property_popups=<factory>, pdf_metadata=<factory>, pdf_single_document=<factory>, dxfpolygonmode=<factory>, dxfimperialunits=<factory>, dxfusepcbnewfont=<factory>, psnegative=<factory>, psa4output=<factory>, plot_black_and_white=<factory>, plotinvisibletext=<factory>, sketchpadsonfab=<factory>, plotpadnumbers=<factory>, hidednponfab=<factory>, sketchdnponfab=<factory>, crossoutdnponfab=<factory>, subtractmaskfromsilk=<factory>, outputformat=<factory>, mirror=<factory>, drillshape=<factory>, scaleselection=<factory>, outputdirectory=<factory>)[source]

Bases: NamedObject

PCB plot parameters - stores all plotting settings.

Parameters:

layerselection (NamedString) – Layer selection hex mask (optional)
plot_on_all_layers_selection (NamedString) – Plot on all layers selection (optional)
disableapertmacros (TokenFlag) – Disable aperture macros (optional)
usegerberextensions (TokenFlag) – Use gerber extensions (optional)
usegerberattributes (TokenFlag) – Use gerber attributes (optional)
usegerberadvancedattributes (TokenFlag) – Use gerber advanced attributes (optional)
creategerberjobfile (TokenFlag) – Create gerber job file (optional)
dashed_line_dash_ratio (NamedFloat) – Dashed line dash ratio (optional)
dashed_line_gap_ratio (NamedFloat) – Dashed line gap ratio (optional)
svgprecision (NamedInt) – SVG precision (optional)
plotframeref (TokenFlag) – Plot frame reference (optional)
mode (NamedInt) – Plot mode (optional)
useauxorigin (TokenFlag) – Use auxiliary origin (optional)
hpglpennumber (NamedInt) – HPGL pen number (optional)
hpglpenspeed (NamedInt) – HPGL pen speed (optional)
hpglpendiameter (NamedFloat) – HPGL pen diameter (optional)
pdf_front_fp_property_popups (TokenFlag) – PDF front footprint property popups (optional)
pdf_back_fp_property_popups (TokenFlag) – PDF back footprint property popups (optional)
pdf_metadata (TokenFlag) – PDF metadata (optional)
pdf_single_document (TokenFlag) – PDF single document (optional)
dxfpolygonmode (TokenFlag) – DXF polygon mode (optional)
dxfimperialunits (TokenFlag) – DXF imperial units (optional)
dxfusepcbnewfont (TokenFlag) – DXF use pcbnew font (optional)
psnegative (TokenFlag) – PS negative (optional)
psa4output (TokenFlag) – PS A4 output (optional)
plot_black_and_white (TokenFlag) – Plot black and white (optional)
plotinvisibletext (TokenFlag) – Plot invisible text (optional)
sketchpadsonfab (TokenFlag) – Sketch pads on fab (optional)
plotpadnumbers (TokenFlag) – Plot pad numbers (optional)
hidednponfab (TokenFlag) – Hide DNP on fab (optional)
sketchdnponfab (TokenFlag) – Sketch DNP on fab (optional)
crossoutdnponfab (TokenFlag) – Cross out DNP on fab (optional)
subtractmaskfromsilk (TokenFlag) – Subtract mask from silk (optional)
outputformat (NamedInt) – Output format (optional)
mirror (TokenFlag) – Mirror (optional)
drillshape (NamedInt) – Drill shape (optional)
scaleselection (NamedInt) – Scale selection (optional)
outputdirectory (NamedString) – Output directory (optional)

__init__(layerselection=<factory>, plot_on_all_layers_selection=<factory>, disableapertmacros=<factory>, usegerberextensions=<factory>, usegerberattributes=<factory>, usegerberadvancedattributes=<factory>, creategerberjobfile=<factory>, dashed_line_dash_ratio=<factory>, dashed_line_gap_ratio=<factory>, svgprecision=<factory>, plotframeref=<factory>, mode=<factory>, useauxorigin=<factory>, hpglpennumber=<factory>, hpglpenspeed=<factory>, hpglpendiameter=<factory>, pdf_front_fp_property_popups=<factory>, pdf_back_fp_property_popups=<factory>, pdf_metadata=<factory>, pdf_single_document=<factory>, dxfpolygonmode=<factory>, dxfimperialunits=<factory>, dxfusepcbnewfont=<factory>, psnegative=<factory>, psa4output=<factory>, plot_black_and_white=<factory>, plotinvisibletext=<factory>, sketchpadsonfab=<factory>, plotpadnumbers=<factory>, hidednponfab=<factory>, sketchdnponfab=<factory>, crossoutdnponfab=<factory>, subtractmaskfromsilk=<factory>, outputformat=<factory>, mirror=<factory>, drillshape=<factory>, scaleselection=<factory>, outputdirectory=<factory>)

class PrivateLayers(layers=<factory>)[source]

Bases: NamedObject

Private layers definition token.

The ‘private_layers’ token defines layers private to specific elements in the format:

(private_layers "LAYER_LIST")

Parameters:: layers (List[str]) – List of private layer names

__init__(layers=<factory>)

class Property(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)[source]

Bases: NamedObject

Property definition token.

The ‘property’ token defines properties in two formats:

General properties::

(property “KEY” “VALUE”)

Symbol properties::

(property: “KEY” “VALUE” (id N) POSITION_IDENTIFIER TEXT_EFFECTS

)

Parameters:

key (str) – Property key name (must be unique)
value (str) – Property value
id (NamedString) – Property ID (optional)
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
unlocked (TokenFlag) – Whether property is unlocked (optional)
layer (Layer) – Layer assignment (optional)
uuid (Uuid) – Unique identifier (optional)
hide (TokenFlag) – Hide property flag (optional)

__init__(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)

class Segment(start=<factory>, end=<factory>, width=<factory>, layer=<factory>, locked=<factory>, net=<factory>, tstamp=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Track segment definition token.

The ‘segment’ token defines a track segment in the format:

(segment
    (start X Y)
    (end X Y)
    (width WIDTH)
    (layer LAYER_DEFINITION)
    [(locked)]
    (net NET_NUMBER)
    (tstamp UUID)
)

Parameters:

start (Start) – Coordinates of the beginning of the line
end (End) – Coordinates of the end of the line
width (NamedFloat) – Line width
layer (Layer) – Layer the track segment resides on
locked (TokenFlag) – Whether the line cannot be edited (optional)
net (NamedInt) – Net ordinal number from net section
tstamp (NamedString) – Unique identifier of the line object (optional)
uuid (Uuid | None) – Unique identifier

__init__(start=<factory>, end=<factory>, width=<factory>, layer=<factory>, locked=<factory>, net=<factory>, tstamp=<factory>, uuid=<factory>)

class Setup(stackup=<factory>, pad_to_mask_clearance=<factory>, allow_soldermask_bridges_in_footprints=<factory>, tenting=<factory>, pcbplotparams=<factory>)[source]

Bases: NamedObject

Board setup definition token.

The ‘setup’ token stores current settings and options used by the board in the format:

(setup
    [(STACK_UP_SETTINGS)]
    (pad_to_mask_clearance CLEARANCE)
    [(solder_mask_min_width MINIMUM_WIDTH)]
    [(pad_to_paste_clearance CLEARANCE)]
    [(pad_to_paste_clearance_ratio RATIO)]
    [(aux_axis_origin X Y)]
    [(grid_origin X Y)]
    (PLOT_SETTINGS)
)

Parameters:

stackup (Stackup) – Stackup configuration (optional)
pad_to_mask_clearance (NamedFloat) – Pad to mask clearance (optional)
allow_soldermask_bridges_in_footprints (TokenFlag) – Allow soldermask bridges in footprints (optional)
tenting (Tenting) – Tenting configuration (optional)
pcbplotparams (PcbPlotParams) – PCB plot parameters (optional)

__init__(stackup=<factory>, pad_to_mask_clearance=<factory>, allow_soldermask_bridges_in_footprints=<factory>, tenting=<factory>, pcbplotparams=<factory>)

class Stackup(layers=<factory>, copper_finish=<factory>, dielectric_constraints=<factory>)[source]

Bases: NamedObject

PCB stackup configuration.

Parameters:

layers (List[StackupLayer]) – List of stackup layers
copper_finish (NamedString) – Copper finish specification (optional)
dielectric_constraints (TokenFlag) – Dielectric constraints flag (optional)

__init__(layers=<factory>, copper_finish=<factory>, dielectric_constraints=<factory>)

class StackupLayer(name='', type=<factory>, color=<factory>, thickness=<factory>, material=<factory>, epsilon_r=<factory>, loss_tangent=<factory>)[source]

Bases: NamedObject

A single layer in the stackup configuration.

Parameters:

name (str) – Layer name
type (NamedString) – Layer type (optional)
color (NamedString) – Layer color (optional)
thickness (NamedFloat) – Layer thickness (optional)
material (NamedString) – Material name (optional)
epsilon_r (NamedFloat) – Relative permittivity (optional)
loss_tangent (NamedFloat) – Loss tangent (optional)

__init__(name='', type=<factory>, color=<factory>, thickness=<factory>, material=<factory>, epsilon_r=<factory>, loss_tangent=<factory>)

class Start(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

Start point definition token.

The ‘start’ token defines a start point in the format: (start X Y)

Parameters:

x (float) – Horizontal position of the start point
y (float) – Vertical position of the start point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Tenting(sides=<factory>)[source]

Bases: NamedObject

Tenting configuration for front/back sides.

Parameters:: sides (List[str]) – List of sides (front/back)

__init__(sides=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Tracks(segments=<factory>)[source]

Bases: NamedObject

Tracks container definition token.

The ‘tracks’ token defines a container for track segments in the format:

(tracks
    (segment ...)
    ...
)

Parameters:: segments (List[Segment]) – List of track segments

__init__(segments=<factory>)

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class Via(type=None, locked=<factory>, at=<factory>, size=<factory>, drill=<factory>, layers=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, free=<factory>, net=<factory>, tstamp=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Via definition token.

The ‘via’ token defines a track via in the format:

(via
    [TYPE]
    [(locked)]
    (at X Y)
    (size DIAMETER)
    (drill DIAMETER)
    (layers LAYER1 LAYER2)
    [(remove_unused_layers)]
    [(keep_end_layers)]
    [(free)]
    (net NET_NUMBER)
    (tstamp UUID)
)

Parameters:

type (str | None) – Via type (blind | micro) (optional)
locked (TokenFlag) – Whether the line cannot be edited (optional)
at (At) – Coordinates of the center of the via
size (NamedFloat) – Diameter of the via annular ring
drill (NamedFloat) – Drill diameter of the via
layers (Layers) – Layer set the via connects
remove_unused_layers (TokenFlag) – Remove unused layers flag (optional)
keep_end_layers (TokenFlag) – Keep end layers flag (optional)
free (TokenFlag) – Whether via is free to move outside assigned net (optional)
net (NamedInt) – Net ordinal number from net section
tstamp (NamedString) – Unique identifier of the line object (optional)
uuid (Uuid | None) – Unique identifier

__init__(type=None, locked=<factory>, at=<factory>, size=<factory>, drill=<factory>, layers=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, free=<factory>, net=<factory>, tstamp=<factory>, uuid=<factory>)

class Vias(vias=<factory>)[source]

Bases: NamedObject

Vias container definition token.

The ‘vias’ token defines a container for vias in the format:

(vias
    (via ...)
    ...
)

Parameters:: vias (List[Via]) – List of vias

__init__(vias=<factory>)

class Zone(hatch=<factory>, connect_pads=<factory>, fill=<factory>, polygon=<factory>, net=<factory>, net_name=<factory>, layer=<factory>, uuid=<factory>, min_thickness=<factory>, name=None, priority=None, filled_areas_thickness=<factory>, keepout=<factory>, filled_polygons=<factory>, filled_segments=<factory>)[source]

Bases: NamedObject

Zone definition token.

The ‘zone’ token defines a zone on the board or footprint in the format:

(zone
    (net NET_NUMBER)
    (net_name "NET_NAME")
    (layer LAYER_DEFINITION)
    (uuid UUID)
    [(name "NAME")]
    (hatch STYLE PITCH)
    [(priority PRIORITY)]
    (connect_pads [CONNECTION_TYPE] (clearance CLEARANCE))
    (min_thickness THICKNESS)
    [(filled_areas_thickness no)]
    [ZONE_KEEPOUT_SETTINGS]
    ZONE_FILL_SETTINGS
    (polygon COORDINATE_POINT_LIST)
    [ZONE_FILL_POLYGONS...]
    [ZONE_FILL_SEGMENTS...]
)

Parameters:

hatch (Hatch) – Hatch settings
connect_pads (ConnectPads) – Pad connection settings
fill (ZoneFill) – Fill settings
polygon (Polygon) – Zone outline polygon
net (NamedInt) – Net number
net_name (NamedString) – Net name
layer (NamedString) – Layer name
uuid (Uuid) – Unique identifier
min_thickness (NamedFloat) – Minimum thickness
name (str | None) – Zone name (optional)
priority (int | None) – Zone priority (optional)
filled_areas_thickness (TokenFlag) – Filled areas thickness flag (optional)
keepout (Keepout | None) – Keepout settings (optional)
filled_polygons (List[FilledPolygon] | None) – List of fill polygons (optional)
filled_segments (List[FilledSegments] | None) – List of fill segments (optional)

__init__(hatch=<factory>, connect_pads=<factory>, fill=<factory>, polygon=<factory>, net=<factory>, net_name=<factory>, layer=<factory>, uuid=<factory>, min_thickness=<factory>, name=None, priority=None, filled_areas_thickness=<factory>, keepout=<factory>, filled_polygons=<factory>, filled_segments=<factory>)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.schematic_system module

Schematic files (.kicad_sch) including wires, symbols, labels, and connections.

Schematic system elements for KiCad S-expressions - schematic drawing and connectivity.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class Arc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Arc definition token.

The ‘arc’ token defines a graphical arc in a symbol definition in the format:

(arc
    (start X Y)
    (mid X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
    (uuid UUID)
)

Parameters:

start (Start) – Start point of the arc
mid (Mid | None) – Mid point of the arc (optional)
end (End) – End point of the arc
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class AtXY(x=0.0, y=0.0)[source]

Bases: NamedObject

Position identifier token for elements that only use X and Y coordinates.

The ‘at’ token defines positional coordinates in the format:: (at X Y)

Used for elements like junctions that don’t have rotation.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object

__init__(x=0.0, y=0.0)

xy(x, y)[source]

Set X and Y coordinates.

Parameters:

x (float) – Horizontal position
y (float) – Vertical position

Returns:

Self (for method chaining)

Return type:

AtXY

class Bezier(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)[source]

Bases: NamedObject

Bezier curve definition token.

The ‘bezier’ token defines a graphic Cubic Bezier curve in the format:

(bezier
    COORDINATE_POINT_LIST
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

pts (Pts) – List of X/Y coordinates of the four points of the curve
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition for filling (optional)
width (NamedFloat) – Line width of the curve (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)

class Bus(pts=<factory>, stroke=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Bus definition token.

The ‘bus’ token defines buses in the schematic in the format:

(bus
    COORDINATE_POINT_LIST
    STROKE_DEFINITION
    UNIQUE_IDENTIFIER
)

Parameters:

pts (Pts) – Bus connection points
stroke (Stroke) – Stroke definition
uuid (Uuid) – Unique identifier

__init__(pts=<factory>, stroke=<factory>, uuid=<factory>)

class BusEntry(at=<factory>, size=<factory>, stroke=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Bus entry definition token.

The ‘bus_entry’ token defines a bus entry in the schematic in the format:

(bus_entry
    POSITION_IDENTIFIER
    (size X Y)
    STROKE_DEFINITION
    UNIQUE_IDENTIFIER
)

Parameters:

at (AtXY) – Position
size (Size) – Entry size
stroke (Stroke) – Stroke definition
uuid (Uuid) – Unique identifier

__init__(at=<factory>, size=<factory>, stroke=<factory>, uuid=<factory>)

class Cells(cells=<factory>)[source]

Bases: NamedObject

Table cells container token.

The ‘cells’ token contains a list of table_cell objects in the format::

(cells: (table_cell …) (table_cell …) …

)

Parameters:: cells (List[TableCell]) – List of table cell objects

__init__(cells=<factory>)

class Circle(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Circle definition token.

The ‘circle’ token defines a graphical circle in a symbol definition in the format:

(circle
    (center X Y)
    (radius RADIUS)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

center (Center) – Center point of the circle
radius (NamedFloat) – Radius length of the circle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class Color(r=0, g=0, b=0, a=0)[source]

Bases: NamedObject

Color definition token.

The ‘color’ token defines color values in the format:

(color R G B A)

Parameters:

r (int) – Red color component (0-255)
g (int) – Green color component (0-255)
b (int) – Blue color component (0-255)
a (int) – Alpha component (0-255)

__init__(r=0, g=0, b=0, a=0)

class ColumnWidths(widths=<factory>)[source]

Bases: NamedObject

Column widths definition token.

The ‘column_widths’ token defines column width values in the format::: (column_widths WIDTH1 WIDTH2 …)

Parameters:: widths (List[float]) – List of column width values

__init__(widths=<factory>)

class Effects(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)[source]

Bases: NamedObject

Text effects definition token.

The ‘effects’ token defines text formatting effects in the format:

(effects
    (font [size SIZE] [thickness THICKNESS] [bold] [italic])
    [(justify JUSTIFY)]
    [hide]
)

Parameters:

font (Font) – Font definition (optional)
justify (Justify) – Text justification (optional)
hide (TokenFlag) – Whether text is hidden (optional)
href (NamedString) – Hyperlink reference (optional)

__init__(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)

class Fill(type=<factory>, color=<factory>)[source]

Bases: NamedObject

Fill definition token.

The ‘fill’ token defines how schematic and symbol library graphical items are filled in the format: (fill

(type none | outline | background) (color R G B A)

)

This represents the nested structure exactly as it appears in the S-expression files.

Parameters:

type (Type) – Fill type specification (optional)
color (Color) – Fill color specification (optional)

__init__(type=<factory>, color=<factory>)

class Font(face=<factory>, size=<factory>, thickness=<factory>, bold=<factory>, italic=<factory>, color=<factory>)[source]

Bases: NamedObject

Font definition token.

The ‘font’ token defines font properties in the format: (font [face “FONT_NAME”] [size WIDTH HEIGHT] [thickness THICKNESS] [bold] [italic])

Parameters:

face (NamedString) – Font face specification (optional)
size (Size | None) – Font size (optional)
thickness (NamedFloat) – Font thickness (optional)
bold (TokenFlag) – Bold flag (optional)
italic (TokenFlag) – Italic flag (optional)
color (Color) – Font color (optional)

__init__(face=<factory>, size=<factory>, thickness=<factory>, bold=<factory>, italic=<factory>, color=<factory>)

class GlobalLabel(text='', shape=<factory>, fields_autoplaced=<factory>, at=<factory>, effects=<factory>, uuid=<factory>, properties=<factory>)[source]

Bases: NamedObject

Global label definition token.

The ‘global_label’ token defines a label visible across all schematics in the format:

(global_label
    "TEXT"
    (shape SHAPE)
    [(fields_autoplaced)]
    POSITION_IDENTIFIER
    TEXT_EFFECTS
    UNIQUE_IDENTIFIER
    PROPERTIES
)

Parameters:

text (str) – Global label text
shape (NamedString) – Way the global label is drawn (optional)
fields_autoplaced (TokenFlag) – Whether properties are placed automatically (optional)
at (At) – X and Y coordinates and rotation angle
effects (Effects | None) – How the global label text is drawn (optional)
uuid (Uuid) – Universally unique identifier
properties (List[Property] | None) – Properties of the global label (optional)

__init__(text='', shape=<factory>, fields_autoplaced=<factory>, at=<factory>, effects=<factory>, uuid=<factory>, properties=<factory>)

class HierarchicalLabel(text='', shape=None, at=<factory>, effects=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Hierarchical label definition token.

The ‘hierarchical_label’ token defines hierarchical labels in schematics.

Parameters:

text (str) – Label text
shape (LabelShape | None) – Label shape (optional)
at (At | None) – Position (optional)
effects (Effects | None) – Text effects (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(text='', shape=None, at=<factory>, effects=<factory>, uuid=<factory>)

class Image(at=<factory>, scale=<factory>, uuid=None, data=<factory>, locked=<factory>)[source]

Bases: NamedObject

Image definition token.

The ‘image’ token defines an image object in PCB files in the format:

(image (at X Y) (scale FACTOR) (uuid UUID) (data ...))

Parameters:

at (AtXY) – Position
scale (NamedFloat) – Scale factor (optional)
uuid (Uuid | None) – Unique identifier (optional)
data (Data) – Image data (optional)
locked (TokenFlag) – Whether image is locked (optional)

__init__(at=<factory>, scale=<factory>, uuid=None, data=<factory>, locked=<factory>)

class Junction(at=<factory>, diameter=<factory>, color=None, uuid=<factory>)[source]

Bases: NamedObject

Junction definition token.

The ‘junction’ token defines a junction in the schematic in the format:

(junction
    POSITION_IDENTIFIER
    (diameter DIAMETER)
    (color R G B A)
    UNIQUE_IDENTIFIER
)

Parameters:

at (AtXY) – Position
diameter (NamedFloat) – Junction diameter
color (Color | None) – Junction color (optional)
uuid (Uuid) – Unique identifier

__init__(at=<factory>, diameter=<factory>, color=None, uuid=<factory>)

class Justify(left=<factory>, right=<factory>, top=<factory>, bottom=<factory>, center=<factory>, mirror=<factory>)[source]

Bases: NamedObject

Text justification definition token.

The ‘justify’ token defines text alignment and mirroring in the format:

(justify [left | right | center] [top | bottom | center] [mirror])

Parameters:

left (TokenFlag) – Left horizontal justification flag (optional)
right (TokenFlag) – Right horizontal justification flag (optional)
top (TokenFlag) – Top vertical justification flag (optional)
bottom (TokenFlag) – Bottom vertical justification flag (optional)
center (TokenFlag) – Center justification flag (horizontal or vertical) (optional)
mirror (TokenFlag) – Mirror text flag (optional)

__init__(left=<factory>, right=<factory>, top=<factory>, bottom=<factory>, center=<factory>, mirror=<factory>)

class KicadSch(version=<factory>, generator=<factory>, generator_version=<factory>, uuid=<factory>, paper=<factory>, title_block=<factory>, lib_symbols=<factory>, junctions=<factory>, no_connects=<factory>, bus_entries=<factory>, wires=<factory>, buses=<factory>, labels=<factory>, global_labels=<factory>, sheets=<factory>, instances=<factory>, graphic_items=<factory>, tables=<factory>, hierarchical_labels=<factory>, rule_areas=<factory>, netclass_flags=<factory>, symbols=<factory>, text=<factory>, images=<factory>, sheet_instances=<factory>, embedded_fonts=<factory>)[source]

Bases: NamedObject

KiCad schematic file definition.

The ‘kicad_sch’ token defines a complete schematic file in the format:

(kicad_sch
    (version VERSION)
    (generator GENERATOR)
    (uuid UNIQUE_IDENTIFIER)
    (lib_symbols ...)
    ;; schematic elements...
)

Parameters:

version (NamedInt) – File format version
generator (NamedString) – Generator application name
generator_version (NamedString) – Generator version (optional)
uuid (Uuid) – Universally unique identifier for the schematic
paper (Paper) – Paper settings (optional)
title_block (TitleBlock) – Title block (optional)
lib_symbols (LibSymbols) – Symbol library container (optional)
junctions (List[Junction] | None) – List of junctions (optional)
no_connects (List[NoConnect] | None) – List of no connect markers (optional)
bus_entries (List[BusEntry] | None) – List of bus entries (optional)
wires (List[Wire] | None) – List of wires (optional)
buses (List[Bus] | None) – List of buses (optional)
labels (List[Label] | None) – List of labels (optional)
global_labels (List[GlobalLabel] | None) – List of global labels (optional)
sheets (List[Sheet] | None) – List of hierarchical sheets (optional)
instances (List[Any] | None) – List of symbol instances (optional)
graphic_items (List[Arc | Bezier | Circle | Line | Polygon | Polyline | Rectangle] | None) – List of graphical items (optional)
tables (List[Table] | None) – List of tables (optional)
hierarchical_labels (List[HierarchicalLabel] | None) – List of hierarchical labels (optional)
rule_areas (List[RuleArea] | None) – List of rule areas (optional)
netclass_flags (List[NetclassFlag] | None) – List of netclass flags (optional)
symbols (List[SchematicSymbol] | None) – List of symbol instances (optional)
text (List[Text] | None) – List of text elements (optional)
images (List[Image] | None) – List of image elements (optional)
sheet_instances (SheetInstances) – Sheet instances (optional)
embedded_fonts (TokenFlag) – Embedded fonts setting (optional)

__init__(version=<factory>, generator=<factory>, generator_version=<factory>, uuid=<factory>, paper=<factory>, title_block=<factory>, lib_symbols=<factory>, junctions=<factory>, no_connects=<factory>, bus_entries=<factory>, wires=<factory>, buses=<factory>, labels=<factory>, global_labels=<factory>, sheets=<factory>, instances=<factory>, graphic_items=<factory>, tables=<factory>, hierarchical_labels=<factory>, rule_areas=<factory>, netclass_flags=<factory>, symbols=<factory>, text=<factory>, images=<factory>, sheet_instances=<factory>, embedded_fonts=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for schematic operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_sch file format.

Parameters:

file_path (str) – Path to write the .kicad_sch file
encoding (str) – File encoding (default: utf-8)

class Label(text='', at=<factory>, fields_autoplaced=<factory>, effects=None, uuid=<factory>)[source]

Bases: NamedObject

Local label definition token.

The ‘label’ token defines a local label in the format:

(label
    "TEXT"
    (at X Y ANGLE)
    (fields_autoplaced)
    (effects EFFECTS)
    (uuid UUID)
)

Parameters:

text (str) – Label text
at (At) – Position and rotation
fields_autoplaced (TokenFlag) – Whether fields are autoplaced (optional)
effects (Effects | None) – Text effects (optional)
uuid (Uuid) – Unique identifier

__init__(text='', at=<factory>, fields_autoplaced=<factory>, effects=None, uuid=<factory>)

class LabelShape(*values)[source]

Bases: Enum

Label and pin shapes for global labels, hierarchical labels, and sheet pins.

BIDIRECTIONAL = 'bidirectional'

INPUT = 'input'

OUTPUT = 'output'

PASSIVE = 'passive'

TRI_STATE = 'tri_state'

class LibSymbols(symbols=<factory>)[source]

Bases: NamedObject

Library symbols container token.

The ‘lib_symbols’ token defines a symbol library containing all symbols used in the schematic in the format:

(lib_symbols
    SYMBOL_DEFINITIONS...
)

Parameters:: symbols (List[Symbol]) – List of symbols

__init__(symbols=<factory>)

class Line(start=<factory>, end=<factory>, uuid=None)[source]

Bases: NamedObject

Line definition token.

The ‘line’ token defines a basic line geometry in the format:

(line (start X Y) (end X Y) (uuid UUID))

Parameters:

start (Start) – Start point of the line
end (End) – End point of the line
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, uuid=None)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class NetclassFlag(name='', length=None, shape=None, at=None, fields_autoplaced=<factory>, effects=None, uuid=None, properties=<factory>)[source]

Bases: NamedObject

Netclass flag definition token.

The ‘netclass_flag’ token defines netclass flags in schematics.

Parameters:

name (str) – Netclass name
length (float | None) – Flag length (optional)
shape (str | None) – Flag shape (optional)
at (At | None) – Position (optional)
fields_autoplaced (TokenFlag) – Whether fields are auto-placed (optional)
effects (Effects | None) – Text effects (optional)
uuid (Uuid | None) – Unique identifier (optional)
properties (List[Property] | None) – Properties of the netclass flag (optional)

__init__(name='', length=None, shape=None, at=None, fields_autoplaced=<factory>, effects=None, uuid=None, properties=<factory>)

class NoConnect(at=<factory>, uuid=<factory>)[source]

Bases: NamedObject

No connect definition token.

The ‘no_connect’ token defines a no-connect symbol in the format:

(no_connect
    (at X Y)
    (uuid UUID)
)

Parameters:

at (AtXY) – Position
uuid (Uuid) – Unique identifier

__init__(at=<factory>, uuid=<factory>)

class Paper(size=None, width=None, height=None, portrait=<factory>)[source]

Bases: NamedObject

Paper settings definition token.

The ‘paper’ token defines paper size and orientation in the format:

(paper PAPER_SIZE | WIDTH HEIGHT [portrait])

Where PAPER_SIZE can be: A0, A1, A2, A3, A4, A5, A, B, C, D, E.

Parameters:

size (str | None) – Standard paper size (optional)
width (float | None) – Custom paper width (optional)
height (float | None) – Custom paper height (optional)
portrait (TokenFlag) – Whether paper is in portrait mode (optional)

__init__(size=None, width=None, height=None, portrait=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class Path(value='', reference=<factory>, unit=<factory>, page=<factory>)[source]

Bases: NamedObject

Path definition token.

The ‘path’ token defines a hierarchical path in the format::

(path “PATH”: (reference “REF”) (unit NUMBER)

)

Parameters:

value (str) – Path value
reference (NamedString) – Component reference (optional)
unit (NamedInt) – Unit number (optional)
page (NamedString) – Page number (optional)

__init__(value='', reference=<factory>, unit=<factory>, page=<factory>)

class PinRef(number='', uuid=None)[source]

Bases: NamedObject

Pin reference definition token for schematic symbols.

The ‘pin’ token in schematic symbols references a pin by number in the format::

(pin “NUMBER”: (uuid UUID)

)

Parameters:

number (str) – Pin number
uuid (Uuid | None) – Unique identifier (optional)

__init__(number='', uuid=None)

class Polygon(pts=<factory>, uuid=None)[source]

Bases: NamedObject

Polygon definition token.

The ‘polygon’ token defines a polygon with multiple points in the format:

(polygon (pts (xy X Y) (xy X Y) ...) (uuid UUID))

Parameters:

pts (Pts) – Polygon vertex points
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, uuid=None)

class Polyline(pts=<factory>, stroke=None, fill=None, uuid=None)[source]

Bases: NamedObject

Polyline definition token.

The ‘polyline’ token defines a connected series of line segments in the format:

(polyline
    (pts (xy X Y) (xy X Y) ...)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

pts (Pts) – Polyline connection points
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=None, fill=None, uuid=None)

class Project(name='', path=<factory>)[source]

Bases: NamedObject

Project definition token.

The ‘project’ token defines a project instance in the format::

(project “PROJECT_NAME”

(path “PATH”: (reference “REF”) (unit NUMBER)

)

Parameters:

name (str) – Project name
path (Path) – Hierarchical path (optional)

__init__(name='', path=<factory>)

class Property(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)[source]

Bases: NamedObject

Property definition token.

The ‘property’ token defines properties in two formats:

General properties::

(property “KEY” “VALUE”)

Symbol properties::

(property: “KEY” “VALUE” (id N) POSITION_IDENTIFIER TEXT_EFFECTS

)

Parameters:

key (str) – Property key name (must be unique)
value (str) – Property value
id (NamedString) – Property ID (optional)
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
unlocked (TokenFlag) – Whether property is unlocked (optional)
layer (Layer) – Layer assignment (optional)
uuid (Uuid) – Unique identifier (optional)
hide (TokenFlag) – Hide property flag (optional)

__init__(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)

class Pts(points=<factory>)[source]

Bases: NamedObject

Coordinate point list definition token.

The ‘pts’ token defines a list of coordinate points in the format: (pts

(xy X Y) … (xy X Y)

)

Where each xy token defines a single X and Y coordinate pair. The number of points is determined by the object type.

Parameters:: points (List[Xy]) – List of 2D coordinate points

__init__(points=<factory>)

xy(x, y)[source]

Add a coordinate point to the list.

Parameters:

x (float) – X coordinate
y (float) – Y coordinate

Returns:

Self (for method chaining)

Return type:

Pts

class Rectangle(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Rectangle definition token (symbol form).

The ‘rectangle’ token defines a graphical rectangle in a symbol definition in the format:

(rectangle
    (start X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

start (Start) – Start point of the rectangle
end (End) – End point of the rectangle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class RowHeights(heights=<factory>)[source]

Bases: NamedObject

Row heights definition token.

The ‘row_heights’ token defines row height values in the format::: (row_heights HEIGHT1 HEIGHT2 …)

Parameters:: heights (List[float]) – List of row height values

__init__(heights=<factory>)

class RuleArea(polylines=<factory>)[source]

Bases: NamedObject

Rule area definition token.

The ‘rule_area’ token defines rule areas in schematics.

Parameters:: polylines (List[Polyline] | None) – Polylines defining area (optional)

__init__(polylines=<factory>)

class SchematicSymbol(lib_name=None, lib_id=<factory>, at=None, mirror=<factory>, unit=<factory>, exclude_from_sim=<factory>, in_bom=<factory>, on_board=<factory>, dnp=<factory>, fields_autoplaced=<factory>, uuid=None, properties=<factory>, pins=<factory>, text=<factory>, instances=<factory>)[source]

Bases: NamedObject

Schematic symbol instance definition token.

References a symbol definition via lib_id and adds instance-specific properties.

The ‘symbol’ token in schematics defines symbol instances in the format::

(symbol: (lib_id “LIBRARY:SYMBOL”) (at X Y ANGLE) (unit NUMBER) (exclude_from_sim BOOLEAN) (in_bom BOOLEAN) (on_board BOOLEAN) (dnp BOOLEAN) (fields_autoplaced BOOLEAN) (uuid UUID) PROPERTIES… PINS… (instances …)

)

Parameters:

lib_name (str | None) – Library name (optional)
lib_id (NamedString) – Library identifier referencing symbol definition (optional)
at (At | None) – Position and rotation (optional)
mirror (NamedString) – Mirror transformation (optional)
unit (NamedInt) – Unit number (optional)
exclude_from_sim (TokenFlag) – Whether to exclude from simulation (optional)
in_bom (TokenFlag) – Whether to include in BOM (optional)
on_board (TokenFlag) – Whether to place on board (optional)
dnp (TokenFlag) – Do not populate flag (optional)
fields_autoplaced (TokenFlag) – Whether fields are auto-placed (optional)
uuid (Uuid | None) – Unique identifier (optional)
properties (List[Property] | None) – List of properties (optional)
pins (List[PinRef] | None) – List of pin references (optional)
text (List[Text] | None) – List of text elements (optional)
instances (SymbolInstances) – Symbol instances (optional)

__init__(lib_name=None, lib_id=<factory>, at=None, mirror=<factory>, unit=<factory>, exclude_from_sim=<factory>, in_bom=<factory>, on_board=<factory>, dnp=<factory>, fields_autoplaced=<factory>, uuid=None, properties=<factory>, pins=<factory>, text=<factory>, instances=<factory>)

class Sheet(at=<factory>, size=<factory>, fields_autoplaced=<factory>, stroke=None, fill=None, uuid=<factory>, properties=<factory>, pins=<factory>, exclude_from_sim=<factory>, in_bom=<factory>, on_board=<factory>, dnp=<factory>, rectangles=<factory>, instances=<factory>)[source]

Bases: NamedObject

Hierarchical sheet definition token.

The ‘sheet’ token defines a hierarchical sheet in the format:

(sheet
    (at X Y)
    (size WIDTH HEIGHT)
    (fields_autoplaced)
    (stroke STROKE_DEFINITION)
    (fill FILL)
    (uuid UUID)
    (property "Sheetname" "NAME")
    (property "Sheetfile" "FILE")
    (pin "NAME" SHAPE (at X Y ANGLE) (effects EFFECTS) (uuid UUID))
    ...
)

Parameters:

at (AtXY) – Position
size (Size) – Sheet size
fields_autoplaced (TokenFlag) – Whether fields are autoplaced (optional)
stroke (Stroke | None) – Stroke definition (optional)
fill (Fill | None) – Fill definition (optional)
uuid (Uuid) – Unique identifier
properties (List[Property]) – List of properties
pins (List[SheetPin] | None) – List of sheet pins (optional)
exclude_from_sim (TokenFlag) – Whether sheet is excluded from simulation (optional)
in_bom (TokenFlag) – Whether sheet appears in BOM (optional)
on_board (TokenFlag) – Whether sheet is exported to PCB (optional)
dnp (TokenFlag) – Do not populate flag (optional)
rectangles (List[Rectangle] | None) – List of rectangle graphical items (optional)
instances (SheetLocalInstances) – Sheet local instances (optional)

__init__(at=<factory>, size=<factory>, fields_autoplaced=<factory>, stroke=None, fill=None, uuid=<factory>, properties=<factory>, pins=<factory>, exclude_from_sim=<factory>, in_bom=<factory>, on_board=<factory>, dnp=<factory>, rectangles=<factory>, instances=<factory>)

class SheetInstance(path='', page=<factory>)[source]

Bases: NamedObject

Sheet instance definition token.

The ‘path’ token defines a sheet instance in the format:

(path "PATH_STRING"
    (page "PAGE_NUMBER")
)

Parameters:

path (str) – Hierarchical path string
page (NamedString) – Page object

__init__(path='', page=<factory>)

class SheetInstances(sheet_instances=<factory>)[source]

Bases: NamedObject

Sheet instances container definition token.

The ‘sheet_instances’ token defines sheet instances in the format:

(sheet_instances
    (path "PATH1" (page "PAGE1"))
    (path "PATH2" (page "PAGE2"))
    ...
)

Parameters:: sheet_instances (List[SheetInstance]) – List of sheet instances

__init__(sheet_instances=<factory>)

class SheetLocalInstances(project=<factory>)[source]

Bases: NamedObject

Sheet local instances definition token.

The ‘instances’ token defines local sheet instances in the format:

(instances
    (project "PROJECT_NAME"
        (path "/PATH" (page "PAGE"))
    )
)

Parameters:: project (List[Project]) – List of project data

__init__(project=<factory>)

class SheetPin(name='', shape=LabelShape.INPUT, at=<factory>, effects=None, uuid=<factory>)[source]

Bases: NamedObject

Sheet pin definition token.

The ‘pin’ token defines a hierarchical sheet pin in the format:

(pin "NAME" SHAPE (at X Y ANGLE) (effects EFFECTS) (uuid UUID))

Parameters:

name (str) – Pin name string
shape (LabelShape) – Pin shape/direction
at (At) – Position and angle
effects (Effects | None) – Text effects (optional)
uuid (Uuid) – Unique identifier

__init__(name='', shape=LabelShape.INPUT, at=<factory>, effects=None, uuid=<factory>)

class Size(width=0.0, height=0.0)[source]

Bases: NamedObject

Size definition token.

The ‘size’ token defines width and height dimensions in the format: (size WIDTH HEIGHT)

Parameters:

width (float) – Width dimension
height (float) – Height dimension

__init__(width=0.0, height=0.0)

class Stroke(width=<factory>, type=<factory>, color=<factory>)[source]

Bases: NamedObject

Stroke definition token.

The ‘stroke’ token defines how the outlines of graphical objects are drawn in the format: (stroke

(width WIDTH) (type TYPE) (color R G B A)

)

This represents the nested structure exactly as it appears in the S-expression files.

Parameters:

width (NamedFloat) – Line width specification
type (Type) – Stroke line style specification
color (Color) – Line color specification (optional)

__init__(width=<factory>, type=<factory>, color=<factory>)

class SymbolInstances(projects=<factory>)[source]

Bases: NamedObject

Symbol instances definition token.

The ‘instances’ token defines symbol instance data in the format::

(instances

(project “PROJECT_NAME”

(path “PATH”: (reference “REF”) (unit NUMBER)

)

Parameters:: projects (List[Project]) – List of project instances

__init__(projects=<factory>)

class Table(column_count=None, border=<factory>, separators=<factory>, column_widths=<factory>, row_heights=<factory>, cells=<factory>)[source]

Bases: NamedObject

Table definition token for schematics.

The ‘table’ token defines tables in schematics. This is a basic implementation for parsing support.

Parameters:

column_count (int | None) – Number of columns (optional)
border (TableBorder) – Border configuration (optional)
separators (TableSeparators) – Separator configuration (optional)
column_widths (ColumnWidths) – Column width values (optional)
row_heights (RowHeights) – Row height values (optional)
cells (Cells) – Table cells (optional)

__init__(column_count=None, border=<factory>, separators=<factory>, column_widths=<factory>, row_heights=<factory>, cells=<factory>)

class TableBorder(external=<factory>, header=<factory>, stroke=<factory>)[source]

Bases: NamedObject

Table border definition token.

The ‘border’ token defines border configuration for tables in the format::: (border (external yes) (header yes) (stroke (width WIDTH) (type TYPE)))

Parameters:

external (TokenFlag) – Whether external border is shown (optional)
header (TokenFlag) – Whether header border is shown (optional)
stroke (Stroke) – Stroke definition for border lines (optional)

__init__(external=<factory>, header=<factory>, stroke=<factory>)

class TableCell(text='', exclude_from_sim=<factory>, at=<factory>, size=<factory>, margins=<factory>, span=<factory>, fill=<factory>, effects=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Table cell definition token.

The ‘table_cell’ token defines individual table cells in the format::

(table_cell “TEXT”: (exclude_from_sim BOOLEAN) (at X Y ANGLE) (size WIDTH HEIGHT) (margins LEFT TOP RIGHT BOTTOM) (span COLS ROWS) (fill FILL_DEF) (effects EFFECTS_DEF) (uuid UUID)

)

Parameters:

text (str) – Cell text content
exclude_from_sim (TokenFlag) – Whether to exclude from simulation (optional)
at (At) – Position and rotation (optional)
size (Size) – Cell size (optional)
margins (TableMargins) – Cell margins (optional)
span (TableSpan) – Cell span (optional)
fill (Fill) – Fill definition (optional)
effects (Effects) – Text effects (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(text='', exclude_from_sim=<factory>, at=<factory>, size=<factory>, margins=<factory>, span=<factory>, fill=<factory>, effects=<factory>, uuid=<factory>)

class TableMargins(left=0.0, top=0.0, right=0.0, bottom=0.0)[source]

Bases: NamedObject

Table margins definition token.

The ‘margins’ token defines cell margins in the format::: (margins LEFT TOP RIGHT BOTTOM)

Parameters:

left (float) – Left margin
top (float) – Top margin
right (float) – Right margin
bottom (float) – Bottom margin

__init__(left=0.0, top=0.0, right=0.0, bottom=0.0)

class TableSeparators(rows=<factory>, cols=<factory>, stroke=<factory>)[source]

Bases: NamedObject

Table separators definition token.

The ‘separators’ token defines separator configuration for tables in the format::: (separators (rows yes) (cols yes) (stroke (width WIDTH) (type TYPE)))

Parameters:

rows (TokenFlag) – Whether row separators are shown (optional)
cols (TokenFlag) – Whether column separators are shown (optional)
stroke (Stroke) – Stroke definition for separator lines (optional)

__init__(rows=<factory>, cols=<factory>, stroke=<factory>)

class TableSpan(cols=1, rows=1)[source]

Bases: NamedObject

Table span definition token.

The ‘span’ token defines cell span in the format::: (span COLS ROWS)

Parameters:

cols (int) – Number of columns to span
rows (int) – Number of rows to span

__init__(cols=1, rows=1)

class Text(content='', at=<factory>, effects=<factory>, exclude_from_sim=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Text content definition token.

The ‘text’ token defines text content in the format: (text “TEXT_CONTENT”

(at X Y [ANGLE]) (effects EFFECTS)

)

Parameters:

content (str) – Text content
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
exclude_from_sim (TokenFlag) – Whether to exclude from simulation (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(content='', at=<factory>, effects=<factory>, exclude_from_sim=<factory>, uuid=<factory>)

class TitleBlock(title=<factory>, date=<factory>, rev=<factory>, company=<factory>, comments=<factory>)[source]

Bases: NamedObject

Title block definition token.

The ‘title_block’ token defines the document title block in the format:

(title_block
    (title "TITLE")
    (date "DATE")
    (rev "REVISION")
    (company "COMPANY_NAME")
    (comment N "COMMENT")
)

Parameters:

title (NamedString) – Document title (optional)
date (NamedString) – Document date (optional)
rev (NamedString) – Document revision (optional)
company (NamedString) – Company name (optional)
comments (List[Comment] | None) – List of comments (optional)

__init__(title=<factory>, date=<factory>, rev=<factory>, company=<factory>, comments=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class Wire(pts=<factory>, stroke=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Wire definition token.

The ‘wire’ token defines wires in the schematic in the format:

(wire
    COORDINATE_POINT_LIST
    STROKE_DEFINITION
    UNIQUE_IDENTIFIER
)

Parameters:

pts (Pts) – Wire connection points
stroke (Stroke) – Stroke definition
uuid (Uuid) – Unique identifier

__init__(pts=<factory>, stroke=<factory>, uuid=<factory>)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.symbol_library module

Symbol library files (.kicad_sym) for schematic components.

Symbol library elements for KiCad S-expressions - schematic symbol definitions.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class Arc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Arc definition token.

The ‘arc’ token defines a graphical arc in a symbol definition in the format:

(arc
    (start X Y)
    (mid X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
    (uuid UUID)
)

Parameters:

start (Start) – Start point of the arc
mid (Mid | None) – Mid point of the arc (optional)
end (End) – End point of the arc
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class Bezier(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)[source]

Bases: NamedObject

Bezier curve definition token.

The ‘bezier’ token defines a graphic Cubic Bezier curve in the format:

(bezier
    COORDINATE_POINT_LIST
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

pts (Pts) – List of X/Y coordinates of the four points of the curve
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition for filling (optional)
width (NamedFloat) – Line width of the curve (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)

class Circle(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Circle definition token.

The ‘circle’ token defines a graphical circle in a symbol definition in the format:

(circle
    (center X Y)
    (radius RADIUS)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

center (Center) – Center point of the circle
radius (NamedFloat) – Radius length of the circle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class Effects(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)[source]

Bases: NamedObject

Text effects definition token.

The ‘effects’ token defines text formatting effects in the format:

(effects
    (font [size SIZE] [thickness THICKNESS] [bold] [italic])
    [(justify JUSTIFY)]
    [hide]
)

Parameters:

font (Font) – Font definition (optional)
justify (Justify) – Text justification (optional)
hide (TokenFlag) – Whether text is hidden (optional)
href (NamedString) – Hyperlink reference (optional)

__init__(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)

class Instances(instances=<factory>)[source]

Bases: NamedObject

Symbol instances definition token.

The ‘instances’ token defines symbol instances in a schematic in the format:

(instances
    (project "PROJECT_NAME"
        (path "/PATH" (reference "REF") (unit N) (value "VALUE") (footprint "FOOTPRINT"))
    )
)

Parameters:: instances (List[Any]) – List of instance data

__init__(instances=<factory>)

class KicadSymbolLib(version=<factory>, generator=<factory>, generator_version=<factory>, symbols=<factory>)[source]

Bases: NamedObject

KiCad symbol library file definition.

The ‘kicad_symbol_lib’ token defines a complete symbol library file in the format:

(kicad_symbol_lib
    (version VERSION)
    (generator GENERATOR)
    ;; symbol definitions...
)

Parameters:

version (NamedInt) – File format version
generator (NamedString) – Generator application name
generator_version (NamedString) – Generator version (optional)
symbols (List[Symbol] | None) – List of symbol definitions (optional)

__init__(version=<factory>, generator=<factory>, generator_version=<factory>, symbols=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for symbol library operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_sym file format.

Parameters:

file_path (str) – Path to write the .kicad_sym file
encoding (str) – File encoding (default: utf-8)

class LibSymbols(symbols=<factory>)[source]

Bases: NamedObject

Library symbols container token.

The ‘lib_symbols’ token defines a symbol library containing all symbols used in the schematic in the format:

(lib_symbols
    SYMBOL_DEFINITIONS...
)

Parameters:: symbols (List[Symbol]) – List of symbols

__init__(symbols=<factory>)

class Line(start=<factory>, end=<factory>, uuid=None)[source]

Bases: NamedObject

Line definition token.

The ‘line’ token defines a basic line geometry in the format:

(line (start X Y) (end X Y) (uuid UUID))

Parameters:

start (Start) – Start point of the line
end (End) – End point of the line
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, uuid=None)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Number(number='', effects=<factory>)[source]

Bases: NamedObject

Pin number definition token.

The ‘number’ token defines a pin number with text effects in the format:

(number "NUMBER" TEXT_EFFECTS)

Parameters:

number (str) – Pin number string
effects (Effects) – Text effects (optional)

__init__(number='', effects=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class Pin(electrical_type=PinElectricalType.PASSIVE, graphic_style=PinGraphicStyle.LINE, at=<factory>, length=<factory>, name=<factory>, number=<factory>, hide=<factory>)[source]

Bases: NamedObject

Symbol pin definition token.

The ‘pin’ token defines a symbol pin in the format:

(pin
    PIN_ELECTRICAL_TYPE
    PIN_GRAPHIC_STYLE
    POSITION_IDENTIFIER
    (length LENGTH)
    (name "NAME" TEXT_EFFECTS)
    (number "NUMBER" TEXT_EFFECTS)
)

Parameters:

electrical_type (PinElectricalType) – Pin electrical type
graphic_style (PinGraphicStyle) – Pin graphic style
at (At) – Position and rotation
length (NamedFloat) – Pin length
name (PinName) – Pin name (optional)
number (Number) – Pin number (optional)
hide (TokenFlag) – Whether pin is hidden (optional)

__init__(electrical_type=PinElectricalType.PASSIVE, graphic_style=PinGraphicStyle.LINE, at=<factory>, length=<factory>, name=<factory>, number=<factory>, hide=<factory>)

class PinElectricalType(*values)[source]

Bases: Enum

Pin electrical types for symbols.

BIDIRECTIONAL = 'bidirectional'

FREE = 'free'

INPUT = 'input'

NO_CONNECT = 'no_connect'

OPEN_COLLECTOR = 'open_collector'

OPEN_EMITTER = 'open_emitter'

OUTPUT = 'output'

PASSIVE = 'passive'

POWER_IN = 'power_in'

POWER_OUT = 'power_out'

TRI_STATE = 'tri_state'

UNSPECIFIED = 'unspecified'

class PinGraphicStyle(*values)[source]

Bases: Enum

Pin graphical styles for symbols.

CLOCK = 'clock'

CLOCK_LOW = 'clock_low'

EDGE_CLOCK_HIGH = 'edge_clock_high'

INPUT_LOW = 'input_low'

INVERTED = 'inverted'

INVERTED_CLOCK = 'inverted_clock'

LINE = 'line'

NON_LOGIC = 'non_logic'

OUTPUT_LOW = 'output_low'

class PinName(name='', effects=<factory>)[source]

Bases: NamedObject

Pin name definition token.

The ‘name’ token defines a pin name with text effects in the format:

(name "NAME" TEXT_EFFECTS)

Parameters:

name (str) – Pin name string
effects (Effects) – Text effects (optional)

__init__(name='', effects=<factory>)

class PinNames(offset=None, hide=<factory>)[source]

Bases: NamedObject

Pin names attributes definition token.

The ‘pin_names’ token defines attributes for all pin names of a symbol in the format:

(pin_names [(offset OFFSET)] [hide])

Parameters:

offset (float | None) – Pin name offset (optional)
hide (TokenFlag) – Whether pin names are hidden (optional)

__init__(offset=None, hide=<factory>)

class PinNumbers(hide=<factory>)[source]

Bases: NamedObject

Pin numbers visibility definition token.

The ‘pin_numbers’ token defines visibility of pin numbers for a symbol in the format:

(pin_numbers [hide])

Parameters:: hide (TokenFlag) – Whether pin numbers are hidden (optional)

__init__(hide=<factory>)

class Pintype(type=PinElectricalType.PASSIVE)[source]

Bases: NamedObject

Pin type definition token.

The ‘pintype’ token defines the electrical type for a pin in the format:

(pintype "TYPE")

Where TYPE can be: input, output, bidirectional, tri_state, passive, free, unspecified, power_in, power_out, open_collector, open_emitter, no_connect

Parameters:: type (PinElectricalType) – Pin electrical type

__init__(type=PinElectricalType.PASSIVE)

class Polygon(pts=<factory>, uuid=None)[source]

Bases: NamedObject

Polygon definition token.

The ‘polygon’ token defines a polygon with multiple points in the format:

(polygon (pts (xy X Y) (xy X Y) ...) (uuid UUID))

Parameters:

pts (Pts) – Polygon vertex points
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, uuid=None)

class Polyline(pts=<factory>, stroke=None, fill=None, uuid=None)[source]

Bases: NamedObject

Polyline definition token.

The ‘polyline’ token defines a connected series of line segments in the format:

(polyline
    (pts (xy X Y) (xy X Y) ...)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

pts (Pts) – Polyline connection points
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=None, fill=None, uuid=None)

class Property(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)[source]

Bases: NamedObject

Property definition token.

The ‘property’ token defines properties in two formats:

General properties::

(property “KEY” “VALUE”)

Symbol properties::

(property: “KEY” “VALUE” (id N) POSITION_IDENTIFIER TEXT_EFFECTS

)

Parameters:

key (str) – Property key name (must be unique)
value (str) – Property value
id (NamedString) – Property ID (optional)
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
unlocked (TokenFlag) – Whether property is unlocked (optional)
layer (Layer) – Layer assignment (optional)
uuid (Uuid) – Unique identifier (optional)
hide (TokenFlag) – Hide property flag (optional)

__init__(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)

class Rectangle(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Rectangle definition token (symbol form).

The ‘rectangle’ token defines a graphical rectangle in a symbol definition in the format:

(rectangle
    (start X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

start (Start) – Start point of the rectangle
end (End) – End point of the rectangle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class Symbol(library_id='', extends=None, pin_numbers=None, pin_names=None, in_bom=<factory>, on_board=<factory>, exclude_from_sim=<factory>, power=<factory>, properties=<factory>, graphic_items=<factory>, text=<factory>, pins=<factory>, units=<factory>, unit_name=None, embedded_fonts=<factory>)[source]

Bases: NamedObject

Symbol definition token.

The ‘symbol’ token defines a complete schematic symbol in the format:

(symbol "LIBRARY_ID"
    [(extends "LIBRARY_ID")]
    [(pin_numbers hide)]
    [(pin_names [(offset OFFSET)] hide)]
    (in_bom yes | no)
    (on_board yes | no)
    SYMBOL_PROPERTIES...
    GRAPHIC_ITEMS...
    PINS...
    UNITS...
    [(unit_name "UNIT_NAME")]
)

Parameters:

library_id (str) – Unique library identifier or unit ID
extends (str | None) – Parent library ID for derived symbols (optional)
pin_numbers (PinNumbers | None) – Pin numbers visibility settings (optional)
pin_names (PinNames | None) – Pin names attributes (optional)
in_bom (TokenFlag) – Whether symbol appears in BOM (optional)
on_board (TokenFlag) – Whether symbol is exported to PCB (yes/no) (optional)
exclude_from_sim (TokenFlag) – Whether symbol is excluded from simulation (optional)
power (TokenFlag) – Whether symbol is a power symbol (optional)
properties (List[Property] | None) – List of symbol properties (optional)
graphic_items (List[Arc | Bezier | Circle | Line | Polygon | Polyline | Rectangle] | None) – List of graphical items (optional)
text (List[Text] | None) – List of text elements (optional)
pins (List[Pin] | None) – List of symbol pins (optional)
units (List[Symbol] | None) – List of child symbol units (optional)
unit_name (str | None) – Display name for subunits (optional)
embedded_fonts (TokenFlag) – Whether embedded fonts are used (optional)

__init__(library_id='', extends=None, pin_numbers=None, pin_names=None, in_bom=<factory>, on_board=<factory>, exclude_from_sim=<factory>, power=<factory>, properties=<factory>, graphic_items=<factory>, text=<factory>, pins=<factory>, units=<factory>, unit_name=None, embedded_fonts=<factory>)

class Text(content='', at=<factory>, effects=<factory>, exclude_from_sim=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Text content definition token.

The ‘text’ token defines text content in the format: (text “TEXT_CONTENT”

(at X Y [ANGLE]) (effects EFFECTS)

)

Parameters:

content (str) – Text content
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
exclude_from_sim (TokenFlag) – Whether to exclude from simulation (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(content='', at=<factory>, effects=<factory>, exclude_from_sim=<factory>, uuid=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.footprint_library module

Footprint files (.kicad_mod) for PCB component footprints.

Footprint library elements for KiCad S-expressions - footprint management and properties.

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class Attr(type='', board_only=<factory>, exclude_from_pos_files=<factory>, exclude_from_bom=<factory>, allow_soldermask_bridges=<factory>)[source]

Bases: NamedObject

Footprint attributes definition token.

The ‘attr’ token defines footprint attributes in the format:

(attr
    TYPE
    [board_only]
    [exclude_from_pos_files]
    [exclude_from_bom]
)

Parameters:

type (str) – Footprint type (smd | through_hole)
board_only (TokenFlag) – Whether footprint is only defined in board (optional)
exclude_from_pos_files (TokenFlag) – Whether to exclude from position files (optional)
exclude_from_bom (TokenFlag) – Whether to exclude from BOM files (optional)
allow_soldermask_bridges (TokenFlag) – Whether to allow soldermask bridges (optional)

__init__(type='', board_only=<factory>, exclude_from_pos_files=<factory>, exclude_from_bom=<factory>, allow_soldermask_bridges=<factory>)

class EmbeddedFile(name=<factory>, type=<factory>, data=<factory>, checksum=<factory>)[source]

Bases: NamedObject

Embedded file definition token.

The ‘file’ token defines an embedded file in the format:

(file
    (name "FILENAME")
    (type TYPE)
    [(data |DATA|)]
    [(checksum "CHECKSUM")]
)

Parameters:

name (NamedString) – File name token
type (NamedString) – File type token
data (FileData) – Base64 encoded file data token (optional)
checksum (NamedString) – File checksum token (optional)

__init__(name=<factory>, type=<factory>, data=<factory>, checksum=<factory>)

class EmbeddedFiles(files=<factory>)[source]

Bases: NamedObject

Embedded files container definition token.

The ‘embedded_files’ token defines a container for embedded files in the format:

(embedded_files
    (file ...)
    ...
)

Parameters:: files (List[EmbeddedFile]) – List of embedded files

__init__(files=<factory>)

class FileData(lines=<factory>)[source]

Bases: NamedObject

Data definition token for embedded files.

The ‘data’ token defines base64 encoded file data in the format:

(data |DATA_LINE1|
      |DATA_LINE2|
      ...)

Parameters:: lines (List[str]) – List of base64 encoded data lines

__init__(lines=<factory>)

class Footprint(library_link=None, version=<factory>, generator=<factory>, generator_version=<factory>, locked=<factory>, placed=<factory>, layer=<factory>, tedit=<factory>, uuid=None, at=None, descr=<factory>, tags=<factory>, properties=<factory>, path=None, sheetname=<factory>, sheetfile=<factory>, attr=<factory>, autoplace_cost90=None, autoplace_cost180=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=<factory>, solder_paste_ratio=None, clearance=<factory>, zone_connect=None, thermal_width=<factory>, thermal_gap=<factory>, private_layers=<factory>, net_tie_pad_groups=<factory>, pads=<factory>, models=<factory>, fp_elements=<factory>, embedded_fonts=<factory>, embedded_files=<factory>)[source]

Bases: NamedObject

Footprint definition token that defines a complete footprint.

The ‘footprint’ token defines a footprint with all its elements in the format:

(footprint
    ["LIBRARY_LINK"]
    [locked]
    [placed]
    (layer LAYER_DEFINITIONS)
    (tedit TIME_STAMP)
    [(uuid UUID)]
    [POSITION_IDENTIFIER]
    [(descr "DESCRIPTION")]
    [(tags "NAME")]
    [(property "KEY" "VALUE") ...]
    (path "PATH")
    [(autoplace_cost90 COST)]
    [(autoplace_cost180 COST)]
    [(solder_mask_margin MARGIN)]
    [(solder_paste_margin MARGIN)]
    [(solder_paste_ratio RATIO)]
    [(clearance CLEARANCE)]
    [(zone_connect CONNECTION_TYPE)]
    [(thermal_width WIDTH)]
    [(thermal_gap DISTANCE)]
    [ATTRIBUTES]
    [(private_layers LAYER_DEFINITIONS)]
    [(net_tie_pad_groups PAD_GROUP_DEFINITIONS)]
    GRAPHIC_ITEMS...
    PADS...
    ZONES...
    GROUPS...
    3D_MODEL
)

Parameters:

library_link (str | None) – Link to footprint library (optional)
version (NamedInt) – File format version (optional)
generator (NamedString) – Generator application (optional)
generator_version (NamedString) – Generator version (optional)
locked (TokenFlag) – Whether the footprint cannot be edited (optional)
placed (TokenFlag) – Whether the footprint has been placed (optional)
layer (Layer) – Layer the footprint is placed on
tedit (NamedString) – Last edit timestamp (optional)
uuid (Uuid | None) – Unique identifier for board footprints (optional)
at (At | None) – Position and rotation coordinates (optional)
descr (NamedString) – Description of the footprint (optional)
tags (NamedString) – Search tags for the footprint (optional)
properties (List[Property] | None) – List of footprint properties (optional)
path (str | None) – Hierarchical path of linked schematic symbol (optional)
sheetname (NamedString) – Schematic sheet name (optional)
sheetfile (NamedString) – Schematic sheet file (optional)
attr (Attr) – Footprint attributes (optional)
autoplace_cost90 (int | None) – Vertical cost for automatic placement (optional)
autoplace_cost180 (int | None) – Horizontal cost for automatic placement (optional)
solder_mask_margin (float | None) – Solder mask distance from pads (optional)
solder_paste_margin (float | None) – Solder paste distance from pads (optional)
solder_paste_margin_ratio (NamedFloat) – Solder paste margin ratio (optional)
solder_paste_ratio (float | None) – Percentage of pad size for solder paste (optional)
clearance (NamedFloat) – Clearance to board copper objects (optional)
zone_connect (int | None) – How pads connect to filled zones (optional)
thermal_width (NamedFloat) – Thermal relief spoke width (optional)
thermal_gap (NamedFloat) – Distance from pad to zone for thermal relief (optional)
private_layers (List[str] | None) – List of private layers (optional)
net_tie_pad_groups (NetTiePadGroups) – Net tie pad groups (optional)
pads (List[Pad] | None) – List of pads (optional)
models (List[Model] | None) – List of 3D models (optional)
fp_elements (List[FpArc | FpCircle | FpCurve | FpLine | FpPoly | FpRect | FpText] | None) – List of footprint graphical elements (optional)
embedded_fonts (TokenFlag) – Embedded fonts settings (optional)
embedded_files (EmbeddedFiles) – Embedded files container (optional)

__init__(library_link=None, version=<factory>, generator=<factory>, generator_version=<factory>, locked=<factory>, placed=<factory>, layer=<factory>, tedit=<factory>, uuid=None, at=None, descr=<factory>, tags=<factory>, properties=<factory>, path=None, sheetname=<factory>, sheetfile=<factory>, attr=<factory>, autoplace_cost90=None, autoplace_cost180=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=<factory>, solder_paste_ratio=None, clearance=<factory>, zone_connect=None, thermal_width=<factory>, thermal_gap=<factory>, private_layers=<factory>, net_tie_pad_groups=<factory>, pads=<factory>, models=<factory>, fp_elements=<factory>, embedded_fonts=<factory>, embedded_files=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for footprint operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_mod file format.

Parameters:

file_path (str) – Path to write the .kicad_mod file
encoding (str) – File encoding (default: utf-8)

class Footprints(footprints=<factory>)[source]

Bases: NamedObject

Footprints container token.

The ‘footprints’ token defines a container for multiple footprints in the format:

(footprints
    (footprint ...)
    ...
)

Parameters:: footprints (List[Footprint]) – List of footprints

__init__(footprints=<factory>)

class FpArc(start=<factory>, mid=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, locked=<factory>, angle=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint arc definition token.

The ‘fp_arc’ token defines an arc in a footprint in the format:

(fp_arc
    (start X Y)
    [(mid X Y)]
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    [STROKE_DEFINITION]
    [(locked)]
    [(uuid UUID)]
    [(angle ANGLE)]
)

Parameters:

start (Start) – Start point coordinates
mid (Mid) – Mid point coordinates (optional)
end (End) – End point coordinates
layer (Layer) – Layer definition
width (NamedFloat) – Line width (prior to version 7) (optional)
stroke (Stroke) – Stroke definition (from version 7) (optional)
locked (TokenFlag) – Whether the arc is locked (optional)
angle (NamedFloat) – Arc angle in degrees (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, locked=<factory>, angle=<factory>, uuid=<factory>)

class FpCircle(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint circle definition token.

The ‘fp_circle’ token defines a circle in a footprint in the format:

(fp_circle
    (center X Y)
    (end X Y)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

center (Center) – Center point
end (End) – End point
layer (Layer) – Layer definition
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
uuid (Uuid) – Unique identifier (optional)
stroke (Stroke) – Stroke definition (optional)
fill (TokenFlag) – Fill definition (optional)
locked (TokenFlag) – Whether the circle is locked (optional)

__init__(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>)

class FpCurve(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint curve definition token.

The ‘fp_curve’ token defines a Bezier curve in a footprint in the format:

(fp_curve
    (pts (xy X Y) (xy X Y) (xy X Y) (xy X Y))
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

pts (Pts) – Control points
layer (Layer) – Layer definition
width (NamedFloat) – Line width
tstamp (NamedString) – Timestamp UUID (optional)
stroke (Stroke) – Stroke definition (optional)
locked (TokenFlag) – Whether the curve is locked (optional)

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)

class FpLine(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint line definition token.

The ‘fp_line’ token defines a line in a footprint in the format:

(fp_line
    (start X Y)
    (end X Y)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

start (Start) – Start point
end (End) – End point
layer (Layer) – Layer definition
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
uuid (Uuid) – Unique identifier (optional)
stroke (Stroke) – Stroke definition (optional)
locked (TokenFlag) – Whether the line is locked (optional)

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)

class FpPoly(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint polygon definition token.

The ‘fp_poly’ token defines a polygon in a footprint in the format:

(fp_poly
    (pts (xy X Y) ...)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

pts (Pts) – Polygon points
layer (Layer) – Layer definition (optional)
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
stroke (Stroke) – Stroke definition (optional)
fill (TokenFlag) – Fill definition (optional)
locked (TokenFlag) – Whether thepolygon is locked (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class FpRect(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint rectangle definition token.

The ‘fp_rect’ token defines a graphic rectangle in a footprint definition in the format:

(fp_rect
    (start X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    STROKE_DEFINITION
    [(fill yes | no)]
    [(locked)]
    (uuid UUID)
)

Parameters:

start (Start) – Coordinates of the upper left corner
end (End) – Coordinates of the lower right corner
layer (Layer) – Layer definition
width (NamedFloat) – Line width (prior to version 7) (optional)
stroke (Stroke) – Stroke definition (from version 7) (optional)
fill (TokenFlag) – Whether the rectangle is filled (yes/no) (optional)
locked (TokenFlag) – Whether the rectangle cannot be edited (optional)
uuid (Uuid) – Unique identifier

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class FpText(type='', text='', at=<factory>, unlocked=<factory>, layer=<factory>, hide=<factory>, effects=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint text definition token.

The ‘fp_text’ token defines text in a footprint in the format:

(fp_text
    TYPE
    "TEXT"
    POSITION_IDENTIFIER
    [unlocked]
    (layer LAYER_DEFINITION)
    [hide]
    (effects TEXT_EFFECTS)
    (uuid UUID)
)

Parameters:

type (str) – Text type (reference | value | user)
text (str) – Text content
at (FpTextAt) – Position and rotation coordinates
unlocked (TokenFlag) – Whether text orientation can be other than upright (optional)
layer (Layer) – Layer definition
hide (TokenFlag) – Whether text is hidden (optional)
effects (Effects) – Text effects
uuid (Uuid) – Unique identifier

__init__(type='', text='', at=<factory>, unlocked=<factory>, layer=<factory>, hide=<factory>, effects=<factory>, uuid=<factory>)

class Layer(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)[source]

Bases: NamedObject

Layer definition token.

The ‘layer’ token defines layer information in the format:

(layer "NAME" | dielectric NUMBER (type "DESCRIPTION")
       [(color "COLOR")] [(thickness THICKNESS)]
       [(material "MATERIAL")] [(epsilon_r VALUE)]
       [(loss_tangent VALUE)])

For simple layer references:: (layer “LAYER_NAME”)

Parameters:

name (str) – Layer name or ‘dielectric’
number (int | None) – Layer stack number (optional)
type (str | None) – Layer type description (optional)
color (str | None) – Layer color as string (optional)
thickness (float | None) – Layer thickness value (optional)
material (str | None) – Material name (optional)
epsilon_r (float | None) – Dielectric constant value (optional)
loss_tangent (float | None) – Loss tangent value (optional)

__init__(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)

class Model(path='', at=<factory>, scale=<factory>, rotate=<factory>, offset=<factory>, hide=<factory>)[source]

Bases: NamedObject

3D model definition token for footprints.

The ‘model’ token defines a 3D model associated with a footprint in the format:

(model
    "3D_MODEL_FILE"
    (at (xyz X Y Z))
    (scale (xyz X Y Z))
    (rotate (xyz X Y Z))
)

Parameters:

path (str) – Path and file name of the 3D model
at (ModelAt) – 3D position coordinates relative to the footprint (optional)
scale (ModelScale) – Model scale factor for each 3D axis (optional)
rotate (ModelRotate) – Model rotation for each 3D axis relative to the footprint (optional)
offset (ModelOffset) – Model offset coordinates (optional)
hide (TokenFlag) – Whether the 3D model is hidden (optional)

__init__(path='', at=<factory>, scale=<factory>, rotate=<factory>, offset=<factory>, hide=<factory>)

class ModelAt(xyz=<factory>)[source]

Bases: NamedObject

3D model position definition token.

The ‘at’ token for 3D models in the format: (at (xyz X Y Z))

Parameters:: xyz (Xyz) – 3D coordinates for model position

__init__(xyz=<factory>)

class ModelOffset(xyz=<factory>)[source]

Bases: NamedObject

3D model offset definition token.

The ‘offset’ token for 3D models in the format: (offset (xyz X Y Z))

Parameters:: xyz (Xyz) – 3D offset coordinates for model

__init__(xyz=<factory>)

class ModelRotate(xyz=<factory>)[source]

Bases: NamedObject

3D model rotation definition token.

The ‘rotate’ token for 3D models in the format: (rotate (xyz X Y Z))

Parameters:: xyz (Xyz) – 3D rotation angles for model

__init__(xyz=<factory>)

class ModelScale(xyz=<factory>)[source]

Bases: NamedObject

3D model scale definition token.

The ‘scale’ token for 3D models in the format: (scale (xyz X Y Z))

Parameters:: xyz (Xyz) – 3D scale factors for model

__init__(xyz=<factory>)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class NetTiePadGroups(groups=<factory>)[source]

Bases: NamedObject

Net tie pad groups definition token.

The ‘net_tie_pad_groups’ token defines groups of pads that are connected in the format:

(net_tie_pad_groups "PAD_LIST" "PAD_LIST" ...)

Parameters:: groups (List[str]) – List of pad group strings

__init__(groups=<factory>)

class Pad(number='', type=PadType.THRU_HOLE, shape=PadShape.CIRCLE, at=<factory>, size=<factory>, layers=<factory>, drill=<factory>, property=None, locked=<factory>, remove_unused_layer=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, roundrect_rratio=<factory>, chamfer_ratio=None, chamfer=<factory>, net=<factory>, uuid=None, pinfunction=None, pintype=None, die_length=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=None, clearance=None, zone_connect=None, thermal_width=None, thermal_bridge_width=<factory>, thermal_gap=None, options=<factory>, primitives=<factory>, teardrops=<factory>)[source]

Bases: NamedObject

Footprint pad definition token.

The ‘pad’ token defines a pad in a footprint with comprehensive properties in the format:

(pad "NUMBER" TYPE SHAPE POSITION_IDENTIFIER [(locked)] (size X Y)
     [(drill DRILL_DEFINITION)] (layers "CANONICAL_LAYER_LIST") ...)

Note

Field order follows KiCad documentation, not dataclass conventions. Required fields after optional fields violate dataclass ordering.

Parameters:

number (str) – Pad number or name
type (PadType) – Pad type
shape (PadShape) – Pad shape
at (At) – Position and rotation
size (Size) – Pad dimensions
layers (Layers) – Layer list
drill (Drill) – Drill definition (optional)
property (str | None) – Pad property (optional)
locked (TokenFlag) – Whether pad is locked (optional)
remove_unused_layer (TokenFlag) – Remove unused layers flag (optional)
remove_unused_layers (TokenFlag) – Remove unused layers flag (newer format) (optional)
keep_end_layers (TokenFlag) – Keep end layers flag (optional)
roundrect_rratio (NamedFloat) – Round rectangle corner ratio (optional)
chamfer_ratio (float | None) – Chamfer ratio (optional)
chamfer (List[str] | None) – Chamfer corners (optional)
net (Net) – Net connection (optional)
uuid (Uuid | None) – Unique identifier (optional)
pinfunction (str | None) – Pin function name (optional)
pintype (str | None) – Pin type (optional)
die_length (float | None) – Die length (optional)
solder_mask_margin (float | None) – Solder mask margin (optional)
solder_paste_margin (float | None) – Solder paste margin (optional)
solder_paste_margin_ratio (float | None) – Solder paste margin ratio (optional)
clearance (float | None) – Clearance value (optional)
zone_connect (ZoneConnection | None) – Zone connection type (optional)
thermal_width (float | None) – Thermal width (optional)
thermal_bridge_width (NamedFloat) – Thermal bridge width (optional)
thermal_gap (float | None) – Thermal gap (optional)
options (Options) – Custom pad options (optional)
primitives (Primitives) – Custom pad primitives (optional)
teardrops (Teardrops) – Teardrop settings (optional)

__init__(number='', type=PadType.THRU_HOLE, shape=PadShape.CIRCLE, at=<factory>, size=<factory>, layers=<factory>, drill=<factory>, property=None, locked=<factory>, remove_unused_layer=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, roundrect_rratio=<factory>, chamfer_ratio=None, chamfer=<factory>, net=<factory>, uuid=None, pinfunction=None, pintype=None, die_length=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=None, clearance=None, zone_connect=None, thermal_width=None, thermal_bridge_width=<factory>, thermal_gap=None, options=<factory>, primitives=<factory>, teardrops=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class Property(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)[source]

Bases: NamedObject

Property definition token.

The ‘property’ token defines properties in two formats:

General properties::

(property “KEY” “VALUE”)

Symbol properties::

(property: “KEY” “VALUE” (id N) POSITION_IDENTIFIER TEXT_EFFECTS

)

Parameters:

key (str) – Property key name (must be unique)
value (str) – Property value
id (NamedString) – Property ID (optional)
at (At) – Position and rotation (optional)
effects (Effects) – Text effects (optional)
unlocked (TokenFlag) – Whether property is unlocked (optional)
layer (Layer) – Layer assignment (optional)
uuid (Uuid) – Unique identifier (optional)
hide (TokenFlag) – Hide property flag (optional)

__init__(key='', value='', id=<factory>, at=<factory>, effects=<factory>, unlocked=<factory>, layer=<factory>, uuid=<factory>, hide=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class Xyz(x=0.0, y=0.0, z=0.0)[source]

Bases: NamedObject

3D coordinate definition token.

The ‘xyz’ token defines 3D coordinates in the format: (xyz X Y Z)

Parameters:

x (float) – X coordinate
y (float) – Y coordinate
z (float) – Z coordinate

__init__(x=0.0, y=0.0, z=0.0)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.project_settings module

Project files (.kicad_pro) with project-wide settings (JSON format).

Project settings elements for KiCad JSON project files - .kicad_pro format.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class BoardDefaults(apply_defaults_to_fp_fields=None, apply_defaults_to_fp_shapes=None, apply_defaults_to_fp_text=None, board_outline_line_width=None, copper_line_width=None, copper_text_italic=None, copper_text_size_h=None, copper_text_size_v=None, copper_text_thickness=None, copper_text_upright=None, courtyard_line_width=None, dimension_precision=None, dimension_units=None, dimensions=None, fab_line_width=None, fab_text_italic=None, fab_text_size_h=None, fab_text_size_v=None, fab_text_thickness=None, fab_text_upright=None, other_line_width=None, other_text_italic=None, other_text_size_h=None, other_text_size_v=None, other_text_thickness=None, other_text_upright=None, pads=None, silk_line_width=None, silk_text_italic=None, silk_text_size_h=None, silk_text_size_v=None, silk_text_thickness=None, silk_text_upright=None, zones=None)[source]

Bases: JsonObject

Board design defaults settings.

In the standard KiCad.kicad_pro file, this is an empty object {}, so all fields are optional and represent extended configurations.

__init__(apply_defaults_to_fp_fields=None, apply_defaults_to_fp_shapes=None, apply_defaults_to_fp_text=None, board_outline_line_width=None, copper_line_width=None, copper_text_italic=None, copper_text_size_h=None, copper_text_size_v=None, copper_text_thickness=None, copper_text_upright=None, courtyard_line_width=None, dimension_precision=None, dimension_units=None, dimensions=None, fab_line_width=None, fab_text_italic=None, fab_text_size_h=None, fab_text_size_v=None, fab_text_thickness=None, fab_text_upright=None, other_line_width=None, other_text_italic=None, other_text_size_h=None, other_text_size_v=None, other_text_thickness=None, other_text_upright=None, pads=None, silk_line_width=None, silk_text_italic=None, silk_text_size_h=None, silk_text_size_v=None, silk_text_thickness=None, silk_text_upright=None, zones=None)

class BoardSettings(design_settings=<factory>, ipc2581=<factory>, layer_pairs=<factory>, layer_presets=<factory>, viewports=<factory>, threeD_viewports=<factory>)[source]

Bases: JsonObject

Board-specific settings.

Based on standard KiCad.kicad_pro structure.

__init__(design_settings=<factory>, ipc2581=<factory>, layer_pairs=<factory>, layer_presets=<factory>, viewports=<factory>, threeD_viewports=<factory>)

class CvpcbSettings(equivalence_files=<factory>)[source]

Bases: JsonObject

Component-Footprint assignment tool settings.

__init__(equivalence_files=<factory>)

class DesignSettings(defaults=<factory>, diff_pair_dimensions=<factory>, drc_exclusions=<factory>, rules=<factory>, track_widths=<factory>, via_dimensions=<factory>, meta=None, rule_severities=None, teardrop_options=None, teardrop_parameters=None, tuning_pattern_settings=None, zones_allow_external_fillets=None, zones_use_no_outline=None)[source]

Bases: JsonObject

Board design settings.

Based on standard KiCad.kicad_pro structure.

__init__(defaults=<factory>, diff_pair_dimensions=<factory>, drc_exclusions=<factory>, rules=<factory>, track_widths=<factory>, via_dimensions=<factory>, meta=None, rule_severities=None, teardrop_options=None, teardrop_parameters=None, tuning_pattern_settings=None, zones_allow_external_fillets=None, zones_use_no_outline=None)

class ERCSettings(erc_exclusions=None, meta=None, pin_map=None, rule_severities=None)[source]

Bases: JsonObject

ERC (Electrical Rules Check) settings.

Not present in standard KiCad.kicad_pro, so all fields are optional.

__init__(erc_exclusions=None, meta=None, pin_map=None, rule_severities=None)

class IPC2581Settings(dist='', distpn='', internal_id='', mfg='', mpn='')[source]

Bases: JsonObject

IPC2581 export settings.

__init__(dist='', distpn='', internal_id='', mfg='', mpn='')

class JsonObject[source]

Bases: ABC

Base class for JSON-based KiCad objects.

This class provides similar functionality to NamedObject but for JSON format files like .kicad_pro project files. It automatically handles serialization/deserialization based on dataclass field definitions.

Features: - Automatic JSON parsing based on dataclass field definitions - Round-trip preservation with preserve_original option - Type-aware serialization/deserialization for nested objects - File I/O methods with extension validation and encoding support - Recursive handling of Optional, List, and nested JsonObject types

Usage:

@dataclass class MyKiCadFile(JsonObject):

version: int = 1 data: Optional[Dict[str, Any]] = None

# Parse from file obj = MyKiCadFile.from_file(“file.json”)

# Parse from dictionary obj = MyKiCadFile.from_dict({“version”: 2, “data”: {…}})

# Export with exact round-trip preservation data = obj.to_dict(preserve_original=True)

__init__()

classmethod from_dict(data)[source]

Create instance from dictionary data.

Parameters:: data (Dict[str, Any]) – Dictionary containing the data
Returns:: Instance of the class
Return type:: T

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from JSON file.

Parameters:

file_path (str) – Path to JSON file
strictness (ParseStrictness) – Parse strictness level (not used for JSON, kept for compatibility)
encoding (str) – File encoding (default: utf-8)

Returns:

Instance of the class

Raises:

FileNotFoundError – If the file doesn’t exist
ValueError – If the file contains invalid JSON
UnicodeDecodeError – If the file encoding is incorrect

Return type:

T

classmethod from_str(json_string, strictness=ParseStrictness.STRICT)[source]

Parse from JSON string.

Parameters:

json_string (str) – JSON content as string
strictness (ParseStrictness) – Parse strictness level (not used for JSON, kept for compatibility)

Returns:

Instance of the class

Raises:

ValueError – If the JSON string is invalid

Return type:

T

save_to_file(file_path, encoding='utf-8', preserve_original=False)[source]

Save to JSON file format.

Parameters:

file_path (str) – Path to write the JSON file
encoding (str) – File encoding (default: utf-8)
preserve_original (bool) – Whether to preserve original structure

to_dict(preserve_original=False)[source]

Convert to dictionary format.

Parameters:: preserve_original (bool) – If True and original data exists, return updated original data preserving the exact structure
Returns:: Dictionary representation
Return type:: Dict[str, Any]

to_json_str(pretty_print=True, preserve_original=False)[source]

Convert to JSON string format.

Parameters:

pretty_print (bool) – Whether to format JSON with indentation
preserve_original (bool) – If True, preserve original structure for exact round-trip

Returns:

JSON string representation

Return type:

str

class KicadProject(board=<factory>, boards=<factory>, cvpcb=<factory>, libraries=<factory>, meta=<factory>, net_settings=<factory>, pcbnew=<factory>, schematic=<factory>, sheets=<factory>, text_variables=<factory>, erc=<factory>)[source]

Bases: JsonObject

KiCad project file definition (.kicad_pro format).

The .kicad_pro file is a JSON format file that contains project configuration and settings for KiCad projects.

Based on the standard KiCad.kicad_pro structure with all standard fields and optional extended fields for more complex projects.

Parameters:

board (BoardSettings) – Board-specific settings
boards (List[str]) – List of board files in project
cvpcb (CvpcbSettings) – Component-Footprint assignment settings
libraries (LibrarySettings) – Library configuration
meta (ProjectMeta) – Project metadata
net_settings (NetSettings) – Network classes and settings
pcbnew (PcbnewSettings) – PCB editor settings
schematic (SchematicSettings) – Schematic-specific settings
sheets (List[Dict[str, Any]]) – List of schematic sheets
text_variables (Dict[str, str]) – Project text variables
erc (ERCSettings | None) – ERC settings (optional, not in standard file)
_original_data – Internal storage of original input data for exact round-trip

__init__(board=<factory>, boards=<factory>, cvpcb=<factory>, libraries=<factory>, meta=<factory>, net_settings=<factory>, pcbnew=<factory>, schematic=<factory>, sheets=<factory>, text_variables=<factory>, erc=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from JSON file - convenience method for project operations.

Parameters:

file_path (str) – Path to .kicad_pro file
strictness (ParseStrictness) – Parse strictness level (not used for JSON)
encoding (str) – File encoding (default: utf-8)

Returns:

KicadProject instance

Return type:

KicadProject

save_to_file(file_path, encoding='utf-8', preserve_original=False)[source]

Save to .kicad_pro file format.

Parameters:

file_path (str) – Path to write the .kicad_pro file
encoding (str) – File encoding (default: utf-8)
preserve_original (bool) – Whether to preserve original structure

class LibrarySettings(pinned_footprint_libs=<factory>, pinned_symbol_libs=<factory>)[source]

Bases: JsonObject

Library settings configuration.

__init__(pinned_footprint_libs=<factory>, pinned_symbol_libs=<factory>)

class NetClass(name='Default', bus_width=12.0, clearance=0.2, diff_pair_gap=0.25, diff_pair_via_gap=0.25, diff_pair_width=0.2, line_style=0, microvia_diameter=0.3, microvia_drill=0.1, pcb_color='rgba(0, 0, 0, 0.000)', priority=2147483647, schematic_color='rgba(0, 0, 0, 0.000)', track_width=0.2, via_diameter=0.6, via_drill=0.3, wire_width=6.0)[source]

Bases: JsonObject

Network class definition.

Values from standard KiCad.kicad_pro file.

__init__(name='Default', bus_width=12.0, clearance=0.2, diff_pair_gap=0.25, diff_pair_via_gap=0.25, diff_pair_width=0.2, line_style=0, microvia_diameter=0.3, microvia_drill=0.1, pcb_color='rgba(0, 0, 0, 0.000)', priority=2147483647, schematic_color='rgba(0, 0, 0, 0.000)', track_width=0.2, via_diameter=0.6, via_drill=0.3, wire_width=6.0)

class NetSettings(classes=<factory>, meta=<factory>, net_colors=None, netclass_assignments=None, netclass_patterns=<factory>)[source]

Bases: JsonObject

Network settings configuration.

Based on standard KiCad.kicad_pro structure.

__init__(classes=<factory>, meta=<factory>, net_colors=None, netclass_assignments=None, netclass_patterns=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class PcbnewSettings(last_paths=<factory>, page_layout_descr_file='')[source]

Bases: JsonObject

PCB editor specific settings.

Based on standard KiCad.kicad_pro structure.

__init__(last_paths=<factory>, page_layout_descr_file='')

class ProjectMeta(filename='KiCad.kicad_pro', version=3)[source]

Bases: JsonObject

Project metadata.

Based on standard KiCad.kicad_pro values.

__init__(filename='KiCad.kicad_pro', version=3)

class SchematicBOMSettings(annotate_start_num=None, bom_export_filename=None, bom_fmt_presets=None, bom_fmt_settings=None, bom_presets=None, bom_settings=None, connection_grid_size=None, drawing=None, net_format_name=None, ngspice=None, page_layout_descr_file=None, plot_directory=None, space_save_all_events=None, spice_adjust_passive_values=None, spice_current_sheet_as_root=None, spice_external_command=None, spice_model_current_sheet_as_root=None, spice_save_all_currents=None, spice_save_all_dissipations=None, spice_save_all_voltages=None, subpart_first_id=None, subpart_id_separator=None)[source]

Bases: JsonObject

BOM (Bill of Materials) settings.

Not present in standard KiCad.kicad_pro, so all fields are optional.

__init__(annotate_start_num=None, bom_export_filename=None, bom_fmt_presets=None, bom_fmt_settings=None, bom_presets=None, bom_settings=None, connection_grid_size=None, drawing=None, net_format_name=None, ngspice=None, page_layout_descr_file=None, plot_directory=None, space_save_all_events=None, spice_adjust_passive_values=None, spice_current_sheet_as_root=None, spice_external_command=None, spice_model_current_sheet_as_root=None, spice_save_all_currents=None, spice_save_all_dissipations=None, spice_save_all_voltages=None, subpart_first_id=None, subpart_id_separator=None)

class SchematicSettings(legacy_lib_dir='', legacy_lib_list=<factory>, meta=None)[source]

Bases: JsonObject

Schematic-specific settings.

Based on standard KiCad.kicad_pro structure.

__init__(legacy_lib_dir='', legacy_lib_list=<factory>, meta=None)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.text_and_documents module

Worksheet/template files (.kicad_wks) for title blocks and page layouts.

Text and document related elements for KiCad S-expressions.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class AtXY(x=0.0, y=0.0)[source]

Bases: NamedObject

Position identifier token for elements that only use X and Y coordinates.

The ‘at’ token defines positional coordinates in the format:: (at X Y)

Used for elements like junctions that don’t have rotation.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object

__init__(x=0.0, y=0.0)

xy(x, y)[source]

Set X and Y coordinates.

Parameters:

x (float) – Horizontal position
y (float) – Vertical position

Returns:

Self (for method chaining)

Return type:

AtXY

class Bitmap(name=<factory>, pos=<factory>, scale=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=None, pngdata=<factory>)[source]

Bases: NamedObject

Bitmap image definition token.

The ‘bitmap’ token defines a bitmap image in the format:

(bitmap
    (name "NAME")
    (pos X Y)
    (scale SCALAR)
    [(repeat COUNT)]
    [(incrx DISTANCE)]
    [(incry DISTANCE)]
    [(comment "COMMENT")]
    (pngdata IMAGE_DATA)
)

Parameters:

name (NamedString) – Image name
pos (Pos) – Position coordinates
scale (NamedFloat) – Scale factor
repeat (NamedInt) – Repeat count (optional)
incrx (NamedFloat) – X increment distance (optional)
incry (NamedFloat) – Y increment distance (optional)
comment (str | None) – Image comment (optional)
pngdata (Pngdata) – PNG image data

__init__(name=<factory>, pos=<factory>, scale=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=None, pngdata=<factory>)

class Comment(number=1, text='')[source]

Bases: NamedObject

Comment definition token.

The ‘comment’ token defines document comments in the format:

(comment N "COMMENT")

Where N is a number from 1 to 9.

Parameters:

number (int) – Comment number (1-9)
text (str) – Comment text

__init__(number=1, text='')

class Data(hex_bytes=<factory>)[source]

Bases: NamedObject

Data definition token.

The ‘data’ token defines hexadecimal byte data in the format:

(data XX1 ... XXN)

Where XXN represents hexadecimal bytes separated by spaces, with a maximum of 32 bytes per data token.

Parameters:: hex_bytes (List[str]) – Hexadecimal byte values (up to 32 bytes)

__init__(hex_bytes=<factory>)

class End(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

End point definition token.

The ‘end’ token defines an end point in the format:

(end X Y)

Parameters:

x (float) – Horizontal position of the end point
y (float) – Vertical position of the end point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Font(face=<factory>, size=<factory>, thickness=<factory>, bold=<factory>, italic=<factory>, color=<factory>)[source]

Bases: NamedObject

Font definition token.

The ‘font’ token defines font properties in the format: (font [face “FONT_NAME”] [size WIDTH HEIGHT] [thickness THICKNESS] [bold] [italic])

Parameters:

face (NamedString) – Font face specification (optional)
size (Size | None) – Font size (optional)
thickness (NamedFloat) – Font thickness (optional)
bold (TokenFlag) – Bold flag (optional)
italic (TokenFlag) – Italic flag (optional)
color (Color) – Font color (optional)

__init__(face=<factory>, size=<factory>, thickness=<factory>, bold=<factory>, italic=<factory>, color=<factory>)

class Group(name='', uuid=None, members=None)[source]

Bases: NamedObject

Group definition token.

The ‘group’ token defines a group of objects in the format:

(group
    "NAME"
    (uuid UUID)
    (members UUID1 ... UUIDN)
)

Parameters:

name (str) – Group name
uuid (Uuid | None) – Group unique identifier (optional)
members (Members | None) – List of member UUIDs (optional)

__init__(name='', uuid=None, members=None)

class Image(at=<factory>, scale=<factory>, uuid=None, data=<factory>, locked=<factory>)[source]

Bases: NamedObject

Image definition token.

The ‘image’ token defines an image object in PCB files in the format:

(image (at X Y) (scale FACTOR) (uuid UUID) (data ...))

Parameters:

at (AtXY) – Position
scale (NamedFloat) – Scale factor (optional)
uuid (Uuid | None) – Unique identifier (optional)
data (Data) – Image data (optional)
locked (TokenFlag) – Whether image is locked (optional)

__init__(at=<factory>, scale=<factory>, uuid=None, data=<factory>, locked=<factory>)

class Justify(left=<factory>, right=<factory>, top=<factory>, bottom=<factory>, center=<factory>, mirror=<factory>)[source]

Bases: NamedObject

Text justification definition token.

The ‘justify’ token defines text alignment and mirroring in the format:

(justify [left | right | center] [top | bottom | center] [mirror])

Parameters:

left (TokenFlag) – Left horizontal justification flag (optional)
right (TokenFlag) – Right horizontal justification flag (optional)
top (TokenFlag) – Top vertical justification flag (optional)
bottom (TokenFlag) – Bottom vertical justification flag (optional)
center (TokenFlag) – Center justification flag (horizontal or vertical) (optional)
mirror (TokenFlag) – Mirror text flag (optional)

__init__(left=<factory>, right=<factory>, top=<factory>, bottom=<factory>, center=<factory>, mirror=<factory>)

class KicadWks(version=<factory>, generator=<factory>, generator_version=<factory>, page=<factory>, title_block=<factory>, setup=<factory>, rect=<factory>, line=<factory>, tbtext=<factory>, elements=<factory>)[source]

Bases: NamedObject

KiCad worksheet definition token.

The ‘kicad_wks’ token defines worksheet format information in the format:

(kicad_wks
    (version VERSION)
    (generator GENERATOR)
    ;; contents of the schematic file...
)

Parameters:

version (NamedInt) – Format version (optional)
generator (NamedString) – Generator name (optional)
generator_version (NamedString) – Generator version (optional)
page (NamedString) – Page settings (optional)
title_block (TitleBlock) – Title block (optional)
setup (WksSetup) – Worksheet setup (optional)
rect (List[WksRect] | None) – List of rectangles (optional)
line (List[WksLine] | None) – List of lines (optional)
tbtext (List[WksTbText] | None) – List of text blocks (optional)
elements (List[Any] | None) – List of worksheet elements (optional)

__init__(version=<factory>, generator=<factory>, generator_version=<factory>, page=<factory>, title_block=<factory>, setup=<factory>, rect=<factory>, line=<factory>, tbtext=<factory>, elements=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for worksheet operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_wks file format.

Parameters:

file_path (str) – Path to write the .kicad_wks file
encoding (str) – File encoding (default: utf-8)

class Members(uuids=<factory>)[source]

Bases: NamedObject

Group members definition token.

The ‘members’ token defines the members of a group in the format:

(members UUID1 UUID2 ... UUIDN)

Parameters:: uuids (List[str]) – List of member UUIDs

__init__(uuids=<factory>)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Paper(size=None, width=None, height=None, portrait=<factory>)[source]

Bases: NamedObject

Paper settings definition token.

The ‘paper’ token defines paper size and orientation in the format:

(paper PAPER_SIZE | WIDTH HEIGHT [portrait])

Where PAPER_SIZE can be: A0, A1, A2, A3, A4, A5, A, B, C, D, E.

Parameters:

size (str | None) – Standard paper size (optional)
width (float | None) – Custom paper width (optional)
height (float | None) – Custom paper height (optional)
portrait (TokenFlag) – Whether paper is in portrait mode (optional)

__init__(size=None, width=None, height=None, portrait=<factory>)

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class Pngdata(data_lines=<factory>)[source]

Bases: NamedObject

PNG data definition token.

The ‘pngdata’ token defines PNG image data in the format:

(pngdata
    (data XX1 ... XXN)
    (data XX1 ... XXN)
    ...
)

Where each data line contains up to 32 hexadecimal bytes.

Parameters:: data_lines (List[Data]) – List of data token objects containing hexadecimal bytes

__init__(data_lines=<factory>)

class Pos(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

Position definition token.

The ‘pos’ token defines a position in the format: (pos X Y)

Parameters:

x (float) – Horizontal position coordinate
y (float) – Vertical position coordinate
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Size(width=0.0, height=0.0)[source]

Bases: NamedObject

Size definition token.

The ‘size’ token defines width and height dimensions in the format: (size WIDTH HEIGHT)

Parameters:

width (float) – Width dimension
height (float) – Height dimension

__init__(width=0.0, height=0.0)

class Start(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

Start point definition token.

The ‘start’ token defines a start point in the format: (start X Y)

Parameters:

x (float) – Horizontal position of the start point
y (float) – Vertical position of the start point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Tbtext(text='', name=<factory>, pos=<factory>, font=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=None)[source]

Bases: NamedObject

Title block text definition token.

The ‘tbtext’ token defines text elements in the title block in the format:

(tbtext
    "TEXT"
    (name "NAME")
    (pos X Y [CORNER])
    (font [(size WIDTH HEIGHT)] [bold] [italic])
    [(repeat COUNT)]
    [(incrx DISTANCE)]
    [(incry DISTANCE)]
    [(comment "COMMENT")]
)

Parameters:

text (str) – Text content
name (NamedString) – Text element name
pos (Pos) – Position coordinates
font (Font) – Font settings (optional)
repeat (NamedInt) – Repeat count for incremental text (optional)
incrx (NamedFloat) – Repeat distance on X axis (optional)
incry (NamedFloat) – Repeat distance on Y axis (optional)
comment (str | None) – Comment for the text object (optional)

__init__(text='', name=<factory>, pos=<factory>, font=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=None)

class Textsize(size=<factory>)[source]

Bases: NamedObject

Text size definition token.

The ‘textsize’ token defines text size in the format:

(textsize WIDTH HEIGHT)

Parameters:: size (Size) – Text size (width and height)

__init__(size=<factory>)

class TitleBlock(title=<factory>, date=<factory>, rev=<factory>, company=<factory>, comments=<factory>)[source]

Bases: NamedObject

Title block definition token.

The ‘title_block’ token defines the document title block in the format:

(title_block
    (title "TITLE")
    (date "DATE")
    (rev "REVISION")
    (company "COMPANY_NAME")
    (comment N "COMMENT")
)

Parameters:

title (NamedString) – Document title (optional)
date (NamedString) – Document date (optional)
rev (NamedString) – Document revision (optional)
company (NamedString) – Company name (optional)
comments (List[Comment] | None) – List of comments (optional)

__init__(title=<factory>, date=<factory>, rev=<factory>, company=<factory>, comments=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class WksLine(name=None, start=<factory>, end=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>)[source]

Bases: NamedObject

Worksheet line definition token.

Parameters:

name (str | None) – Line name (optional)
start (Start) – Start position
end (End) – End position
repeat (NamedInt) – Repeat count (optional)
incrx (NamedFloat) – X increment (optional)
incry (NamedFloat) – Y increment (optional)

__init__(name=None, start=<factory>, end=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>)

class WksRect(name=None, start=<factory>, end=<factory>, comment=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, linewidth=<factory>)[source]

Bases: NamedObject

Worksheet rectangle definition token.

Parameters:

name (str | None) – Rectangle name (optional)
start (Start) – Start position
end (End) – End position
comment (NamedString) – Comment (optional)
repeat (NamedInt) – Repeat count (optional)
incrx (NamedFloat) – X increment (optional)
incry (NamedFloat) – Y increment (optional)
linewidth (NamedFloat) – Line width (optional)

__init__(name=None, start=<factory>, end=<factory>, comment=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, linewidth=<factory>)

class WksSetup(textsize=<factory>, linewidth=<factory>, textlinewidth=<factory>, left_margin=<factory>, right_margin=<factory>, top_margin=<factory>, bottom_margin=<factory>)[source]

Bases: NamedObject

Worksheet setup definition token.

Parameters:

textsize (WksTextsize) – Text size (optional)
linewidth (NamedFloat) – Line width (optional)
textlinewidth (NamedFloat) – Text line width (optional)
left_margin (NamedFloat) – Left margin (optional)
right_margin (NamedFloat) – Right margin (optional)
top_margin (NamedFloat) – Top margin (optional)
bottom_margin (NamedFloat) – Bottom margin (optional)

__init__(textsize=<factory>, linewidth=<factory>, textlinewidth=<factory>, left_margin=<factory>, right_margin=<factory>, top_margin=<factory>, bottom_margin=<factory>)

class WksTbText(text='', name=<factory>, pos=<factory>, font=<factory>, justify=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=<factory>)[source]

Bases: NamedObject

Worksheet text block definition token.

Parameters:

text (str) – Text content
name (NamedString) – Text name (optional)
pos (Pos) – Text position
font (Font) – Font settings (optional)
justify (Justify) – Text justification (optional)
repeat (NamedInt) – Repeat count (optional)
incrx (NamedFloat) – X increment (optional)
incry (NamedFloat) – Y increment (optional)
comment (NamedString) – Comment (optional)

__init__(text='', name=<factory>, pos=<factory>, font=<factory>, justify=<factory>, repeat=<factory>, incrx=<factory>, incry=<factory>, comment=<factory>)

class WksTextsize(width=1.0, height=1.0)[source]

Bases: NamedObject

Worksheet text size definition token.

Parameters:

width (float) – Text width
height (float) – Text height

__init__(width=1.0, height=1.0)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.design_rules module

Design rules files (.kicad_dru) for manufacturing constraints.

Design rules elements for KiCad S-expressions - design rule constraint system.

class ConstraintType(*values)[source]

Bases: Enum

Design rule constraint types.

ANNULAR_WIDTH = 'annular_width'

ASSERTION = 'assertion'

BLIND_VIA_RATIO = 'blind_via_ratio'

CLEARANCE = 'clearance'

CONNECTION_WIDTH = 'connection_width'

COURTYARD_CLEARANCE = 'courtyard_clearance'

CREEPAGE = 'creepage'

DIFF_PAIR_GAP = 'diff_pair_gap'

DIFF_PAIR_UNCOUPLED = 'diff_pair_uncoupled'

DISALLOW = 'disallow'

EDGE_CLEARANCE = 'edge_clearance'

HOLE_CLEARANCE = 'hole_clearance'

HOLE_SIZE = 'hole_size'

HOLE_TO_HOLE = 'hole_to_hole'

LENGTH = 'length'

MICRO_VIA_DIAMETER = 'micro_via_diameter'

MICRO_VIA_DRILL = 'micro_via_drill'

MIN_RESOLVED_SPOKES = 'min_resolved_spokes'

PHYSICAL_CLEARANCE = 'physical_clearance'

PHYSICAL_HOLE_CLEARANCE = 'physical_hole_clearance'

SILK_CLEARANCE = 'silk_clearance'

SKEW = 'skew'

TEXT_HEIGHT = 'text_height'

TEXT_THICKNESS = 'text_thickness'

THERMAL_RELIEF_GAP = 'thermal_relief_gap'

THERMAL_SPOKE_WIDTH = 'thermal_spoke_width'

TRACK_WIDTH = 'track_width'

VIA_DIAMETER = 'via_diameter'

VIA_DRILL = 'via_drill'

ZONE_CONNECTION = 'zone_connection'

class DesignRule(name='', severity=<factory>, layer=<factory>, condition=<factory>, priority=<factory>, constraints=<factory>)[source]

Bases: NamedObject

Design rule definition token.

The ‘rule’ token defines a complete design rule in the format:

(rule NAME
    [(severity SEVERITY)]
    [(layer LAYER_NAME)]
    [(condition EXPRESSION)]
    [(priority PRIORITY_NUMBER)]
    (constraint CONSTRAINT_TYPE [CONSTRAINT_ARGUMENTS])
    [(constraint CONSTRAINT_TYPE [CONSTRAINT_ARGUMENTS])]...
)

Parameters:

name (str) – Rule name
severity (DesignRuleSeverity) – Severity level (optional)
layer (NamedString) – Layer specification (optional)
condition (NamedString) – Conditional expression (optional)
priority (NamedInt) – Rule priority (optional)
constraints (List[DesignRuleConstraint]) – List of constraint definitions

__init__(name='', severity=<factory>, layer=<factory>, condition=<factory>, priority=<factory>, constraints=<factory>)

class DesignRuleConstraint(constraint_type=ConstraintType.CLEARANCE, min_constraint=<factory>, opt_constraint=<factory>, max_constraint=<factory>, disallow_item=None)[source]

Bases: NamedObject

Design rule constraint definition token.

The ‘constraint’ token defines a constraint with optional min/opt/max values in the format:

(constraint CONSTRAINT_TYPE [(min VALUE)] [(opt VALUE)] [(max VALUE)])
(constraint disallow ITEM_TYPE)

Parameters:

constraint_type (ConstraintType) – Type of constraint
min_constraint (NamedString) – Minimum value constraint (optional)
opt_constraint (NamedString) – Optimal value constraint (optional)
max_constraint (NamedString) – Maximum value constraint (optional)
disallow_item (str | None) – Item type to disallow (optional)

__init__(constraint_type=ConstraintType.CLEARANCE, min_constraint=<factory>, opt_constraint=<factory>, max_constraint=<factory>, disallow_item=None)

class DesignRuleSeverity(level=SeverityLevel.ERROR)[source]

Bases: NamedObject

Design rule severity level token.

The ‘severity’ token defines the severity level for rule violations in the format:

(severity error | warning | ignore)

Parameters:: level (SeverityLevel) – Severity level

__init__(level=SeverityLevel.ERROR)

class KiCadDesignRules(version=<factory>, rules=<factory>)[source]

Bases: NamedObject

KiCad design rules file definition.

The design rules file contains version information and a list of rules in the format:

(version VERSION)
RULES...

Note: This is different from other KiCad files - it doesn’t have a root token like ‘kicad_dru’, instead it starts directly with version and rules.

Parameters:

version (NamedInt) – File format version
rules (List[DesignRule] | None) – List of design rules (optional)

__init__(version=<factory>, rules=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from S-expression file - convenience method for design rules operations.

Design rules files (.kicad_dru) have a special format without root token wrapping. This method handles the preprocessing needed for the parser.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for design rules.

This method automatically handles .kicad_dru format preprocessing.

save_to_file(file_path, encoding='utf-8')[source]

Save to .kicad_dru file format.

Parameters:

file_path (str) – Path to write the .kicad_dru file
encoding (str) – File encoding (default: utf-8)

to_dru_str()[source]

Convert to .kicad_dru format string (without root token wrapper).

This method produces the native .kicad_dru file format.

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class SeverityLevel(*values)[source]

Bases: Enum

Design rule severity levels.

ERROR = 'error'

EXCLUSION = 'exclusion'

IGNORE = 'ignore'

WARNING = 'warning'

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

sexpr_to_str(sexpr)[source]

Convert S-expression to string representation.

Parameters:: sexpr (List[Any]) – S-expression to serialize
Returns:: String representation of the S-expression
Raises:: ValueError – If sexpr cannot be serialized
Return type:: str

kicadfiles.library_tables module

Library table files (fp-lib-table, sym-lib-table) for library management.

Library table classes for KiCad library management.

This module provides dataclasses for parsing and managing KiCad library tables: - FpLibTable: Footprint library table (fp-lib-table) - SymLibTable: Symbol library table (sym-lib-table)

Both table types share the same structure with library entries containing: - name: Library identifier - type: Library type (typically “KiCad”) - uri: Path to library - options: Additional options - descr: Human readable description

class FpLibTable(version=<factory>, libraries=<factory>)[source]

Bases: NamedObject

Footprint library table (fp-lib-table file).

Contains version information and a list of footprint library entries.

Parameters:

version (NamedInt) – Table format version
libraries (List[LibraryEntry]) – List of library entries

__init__(version=<factory>, libraries=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from fp-lib-table file - convenience method for library table operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to fp-lib-table file format.

Parameters:

file_path (str) – Path to write the fp-lib-table file
encoding (str) – File encoding (default: utf-8)

class LibraryEntry(name=<factory>, type=<factory>, uri=<factory>, options=<factory>, descr=<factory>)[source]

Bases: NamedObject

A single library entry in a library table.

Represents a (lib …) entry with name, type, uri, options, and description.

Parameters:

name (NamedString) – Library name/identifier
type (NamedString) – Library type (e.g., ‘KiCad’)
uri (NamedString) – Path to library
options (NamedString) – Additional options
descr (NamedString) – Human readable description

__init__(name=<factory>, type=<factory>, uri=<factory>, options=<factory>, descr=<factory>)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class ParseStrictness(*values)[source]

Bases: Enum

Parser strictness levels for error handling.

FAILSAFE = 'failsafe'

SILENT = 'silent'

STRICT = 'strict'

class SymLibTable(version=<factory>, libraries=<factory>)[source]

Bases: NamedObject

Symbol library table (sym-lib-table file).

Contains version information and a list of symbol library entries.

Parameters:

version (NamedInt) – Table format version
libraries (List[LibraryEntry]) – List of library entries

__init__(version=<factory>, libraries=<factory>)

classmethod from_file(file_path, strictness=ParseStrictness.STRICT, encoding='utf-8')[source]

Parse from sym-lib-table file - convenience method for library table operations.

save_to_file(file_path, encoding='utf-8')[source]

Save to sym-lib-table file format.

Parameters:

file_path (str) – Path to write the sym-lib-table file
encoding (str) – File encoding (default: utf-8)

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

Component and Drawing Classes

kicadfiles.pad_and_drill module

Pad, via, and drill definitions for PCB footprints.

Pad and drill related elements for KiCad S-expressions.

class Anchor(pad_shape=PadShape.RECT)[source]

Bases: NamedObject

Anchor pad shape definition for custom pads.

The ‘anchor’ token defines the anchor pad shape of a custom pad in the format:

(anchor PAD_SHAPE)

Parameters:: pad_shape (PadShape) – Anchor pad shape (rect or circle)

__init__(pad_shape=PadShape.RECT)

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class Chamfer(corners=<factory>)[source]

Bases: NamedObject

Chamfer corner definition token for pads.

The ‘chamfer’ token defines which corners of a rectangular pad get chamfered in the format:

(chamfer CORNER_LIST)

Valid chamfer corner attributes are top_left, top_right, bottom_left, and bottom_right.

Parameters:: corners (List[str]) – List of corners to chamfer

__init__(corners=<factory>)

class Drill(oval=<factory>, diameter=0.0, width=None, offset=None)[source]

Bases: NamedObject

Drill definition token for pads.

The ‘drill’ token defines the drill attributes for a footprint pad in the format:

(drill
    [oval]
    DIAMETER
    [WIDTH]
    [(offset X Y)]
)

Parameters:

oval (SymbolValue | None) – Whether the drill is oval instead of round (optional)
diameter (float) – Drill diameter
width (float | None) – Width of the slot for oval drills (optional)
offset (Offset | None) – Drill offset coordinates from the center of the pad (optional)

__init__(oval=<factory>, diameter=0.0, width=None, offset=None)

class GrArc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Graphical arc definition token.

The ‘gr_arc’ token defines an arc graphic object in the format:

(gr_arc
    (start X Y)
    (mid X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

start (Start) – Start point coordinates
mid (Mid) – Mid point coordinates
end (End) – End point coordinates
stroke (Stroke) – Stroke definition (optional)
layer (Layer) – Layer definition (optional)
width (NamedFloat) – Line width (deprecated, use stroke) (optional)
uuid (Uuid) – Unique identifier

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)

class GrCircle(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, fill=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Graphical circle definition token.

The ‘gr_circle’ token defines a circle graphic object in the format:

(gr_circle
    (center X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    [(fill yes | no)]
    (uuid UUID)
)

Parameters:

center (Center) – Center point coordinates
end (End) – End point defining radius
layer (Layer) – Layer definition
width (NamedFloat) – Line width
fill (TokenFlag) – Fill definition (optional)
uuid (Uuid) – Unique identifier

__init__(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, fill=<factory>, uuid=<factory>)

class GrCurve(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: FpCurve

Graphical curve derived from footprint curve.

Inherits all fields from FpCurve but uses ‘gr_curve’ token.

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)

class GrLine(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: FpLine

Graphical line derived from footprint line.

Inherits all fields from FpLine but uses ‘gr_line’ token.

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)

class GrPoly(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: FpPoly

Graphical polygon derived from footprint polygon.

Inherits all fields from FpPoly but uses ‘gr_poly’ token.

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class GrRect(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: FpRect

Graphical rectangle derived from footprint rectangle.

Inherits all fields from FpRect but uses ‘gr_rect’ token.

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class Layers(layers=<factory>)[source]

Bases: NamedObject

Layer list definition token.

The ‘layers’ token defines a list of layer names in the format:

(layers "F.Cu" "F.Paste" "F.Mask")
(layers "*.Cu" "*.Mask" "F.SilkS")

Used for pad layers, via layers, and other layer specifications.

layers

List of layer names

Type:: List[str]

Parameters:: layers (List[str]) – List of layer names

__init__(layers=<factory>)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Net(number=0, name='')[source]

Bases: NamedObject

Net connection definition token.

The ‘net’ token defines the net connection in the format:

(net ORDINAL "NET_NAME")

Parameters:

number (int) – Net number
name (str) – Net name

__init__(number=0, name='')

class Offset(x=0.0, y=0.0)[source]

Bases: NamedObject

Offset definition token.

The ‘offset’ token defines an offset position in the format: (offset X Y)

Parameters:

x (float) – Horizontal offset coordinate
y (float) – Vertical offset coordinate

__init__(x=0.0, y=0.0)

class Options(clearance=<factory>, anchor=<factory>)[source]

Bases: NamedObject

Custom pad options definition token.

The ‘options’ token defines options for custom pads in the format:

(options
    (clearance CLEARANCE_TYPE)
    (anchor PAD_SHAPE)
)

Valid clearance types are outline and convexhull. Valid anchor pad shapes are rect and circle.

Parameters:

clearance (NamedString) – Clearance type for custom pad (optional)
anchor (Anchor) – Anchor pad shape (optional)

__init__(clearance=<factory>, anchor=<factory>)

class Pad(number='', type=PadType.THRU_HOLE, shape=PadShape.CIRCLE, at=<factory>, size=<factory>, layers=<factory>, drill=<factory>, property=None, locked=<factory>, remove_unused_layer=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, roundrect_rratio=<factory>, chamfer_ratio=None, chamfer=<factory>, net=<factory>, uuid=None, pinfunction=None, pintype=None, die_length=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=None, clearance=None, zone_connect=None, thermal_width=None, thermal_bridge_width=<factory>, thermal_gap=None, options=<factory>, primitives=<factory>, teardrops=<factory>)[source]

Bases: NamedObject

Footprint pad definition token.

The ‘pad’ token defines a pad in a footprint with comprehensive properties in the format:

(pad "NUMBER" TYPE SHAPE POSITION_IDENTIFIER [(locked)] (size X Y)
     [(drill DRILL_DEFINITION)] (layers "CANONICAL_LAYER_LIST") ...)

Note

Field order follows KiCad documentation, not dataclass conventions. Required fields after optional fields violate dataclass ordering.

Parameters:

number (str) – Pad number or name
type (PadType) – Pad type
shape (PadShape) – Pad shape
at (At) – Position and rotation
size (Size) – Pad dimensions
layers (Layers) – Layer list
drill (Drill) – Drill definition (optional)
property (str | None) – Pad property (optional)
locked (TokenFlag) – Whether pad is locked (optional)
remove_unused_layer (TokenFlag) – Remove unused layers flag (optional)
remove_unused_layers (TokenFlag) – Remove unused layers flag (newer format) (optional)
keep_end_layers (TokenFlag) – Keep end layers flag (optional)
roundrect_rratio (NamedFloat) – Round rectangle corner ratio (optional)
chamfer_ratio (float | None) – Chamfer ratio (optional)
chamfer (List[str] | None) – Chamfer corners (optional)
net (Net) – Net connection (optional)
uuid (Uuid | None) – Unique identifier (optional)
pinfunction (str | None) – Pin function name (optional)
pintype (str | None) – Pin type (optional)
die_length (float | None) – Die length (optional)
solder_mask_margin (float | None) – Solder mask margin (optional)
solder_paste_margin (float | None) – Solder paste margin (optional)
solder_paste_margin_ratio (float | None) – Solder paste margin ratio (optional)
clearance (float | None) – Clearance value (optional)
zone_connect (ZoneConnection | None) – Zone connection type (optional)
thermal_width (float | None) – Thermal width (optional)
thermal_bridge_width (NamedFloat) – Thermal bridge width (optional)
thermal_gap (float | None) – Thermal gap (optional)
options (Options) – Custom pad options (optional)
primitives (Primitives) – Custom pad primitives (optional)
teardrops (Teardrops) – Teardrop settings (optional)

__init__(number='', type=PadType.THRU_HOLE, shape=PadShape.CIRCLE, at=<factory>, size=<factory>, layers=<factory>, drill=<factory>, property=None, locked=<factory>, remove_unused_layer=<factory>, remove_unused_layers=<factory>, keep_end_layers=<factory>, roundrect_rratio=<factory>, chamfer_ratio=None, chamfer=<factory>, net=<factory>, uuid=None, pinfunction=None, pintype=None, die_length=None, solder_mask_margin=None, solder_paste_margin=None, solder_paste_margin_ratio=None, clearance=None, zone_connect=None, thermal_width=None, thermal_bridge_width=<factory>, thermal_gap=None, options=<factory>, primitives=<factory>, teardrops=<factory>)

class PadShape(*values)[source]

Bases: Enum

Pad shapes for footprints.

CIRCLE = 'circle'

CUSTOM = 'custom'

OVAL = 'oval'

RECT = 'rect'

ROUNDRECT = 'roundrect'

TRAPEZOID = 'trapezoid'

class PadType(*values)[source]

Bases: Enum

Pad types for footprints.

CONNECT = 'connect'

NP_THRU_HOLE = 'np_thru_hole'

SMD = 'smd'

THRU_HOLE = 'thru_hole'

class Pads(pads=<factory>)[source]

Bases: NamedObject

Container for multiple pads.

The ‘pads’ token defines a collection of pads in the format:

(pads
    (pad ...)
    ...
)

Parameters:: pads (List[Pad]) – List of pads

__init__(pads=<factory>)

class Primitives(elements=<factory>, width=<factory>, fill=<factory>)[source]

Bases: NamedObject

Custom pad primitives definition token.

The ‘primitives’ token defines drawing objects for custom pads in the format:

(primitives
    (gr_poly ...)
    (gr_line ...)
    (gr_circle ...)
    (gr_arc ...)
    (gr_rect ...)
    (gr_curve ...)
    ...
)

Parameters:

elements (List[GrArc | GrCircle | GrCurve | GrLine | GrPoly | GrRect] | None) – List of primitive graphical elements (optional)
width (NamedFloat) – Line width of graphical items (optional)
fill (TokenFlag) – Whether geometry should be filled (optional)

__init__(elements=<factory>, width=<factory>, fill=<factory>)

class Shape(shape=PadShape.CIRCLE)[source]

Bases: NamedObject

Pad shape definition token.

The ‘shape’ token defines the shape of a pad in the format:

(shape SHAPE_TYPE)

Valid pad shapes are circle, rect, oval, trapezoid, roundrect, or custom.

Parameters:: shape (PadShape) – Pad shape type

__init__(shape=PadShape.CIRCLE)

class Size(width=0.0, height=0.0)[source]

Bases: NamedObject

Size definition token.

The ‘size’ token defines width and height dimensions in the format: (size WIDTH HEIGHT)

Parameters:

width (float) – Width dimension
height (float) – Height dimension

__init__(width=0.0, height=0.0)

class SymbolValue(token='')[source]

Bases: TokenBase

Simple flag for optional symbols.

Represents standalone tokens like ‘oval’, ‘locked’ without values. Does not consume positional slots during parsing.

__bool__()[source]

Always True if instance exists.

__init__(token='')

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

to_sexpr()[source]

Serialize to S-expression.

class Teardrops(best_length_ratio=<factory>, max_length=<factory>, best_width_ratio=<factory>, max_width=<factory>, curved_edges=<factory>, filter_ratio=<factory>, enabled=<factory>, allow_two_segments=<factory>, prefer_zone_connections=<factory>)[source]

Bases: NamedObject

Teardrops definition token for pads.

The ‘teardrops’ token defines teardrop settings in the format:

(teardrops
    (best_length_ratio RATIO)
    (max_length LENGTH)
    (best_width_ratio RATIO)
    (max_width WIDTH)
    (curved_edges yes|no)
    (filter_ratio RATIO)
    (enabled yes|no)
    (allow_two_segments yes|no)
    (prefer_zone_connections yes|no)
)

Parameters:

best_length_ratio (NamedFloat) – Best length ratio setting
max_length (NamedFloat) – Maximum length setting
best_width_ratio (NamedFloat) – Best width ratio setting
max_width (NamedFloat) – Maximum width setting
curved_edges (TokenFlag) – Curved edges setting (optional)
filter_ratio (NamedFloat) – Filter ratio setting
enabled (TokenFlag) – Enabled setting (optional)
allow_two_segments (TokenFlag) – Allow two segments setting (optional)
prefer_zone_connections (TokenFlag) – Prefer zone connections setting (optional)

__init__(best_length_ratio=<factory>, max_length=<factory>, best_width_ratio=<factory>, max_width=<factory>, curved_edges=<factory>, filter_ratio=<factory>, enabled=<factory>, allow_two_segments=<factory>, prefer_zone_connections=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class ZoneConnect(connection_type=ZoneConnection.INHERITED)[source]

Bases: NamedObject

Zone connection definition token.

The ‘zone_connect’ token defines how a pad connects to filled zones in the format:

(zone_connect CONNECTION_TYPE)

Valid connection types are integer values from 0 to 3: - 0: Pad not connected to zone - 1: Pad connected using thermal relief - 2: Pad connected using solid fill

Parameters:: connection_type (ZoneConnection) – Zone connection type

__init__(connection_type=ZoneConnection.INHERITED)

class ZoneConnection(*values)[source]

Bases: Enum

Zone connection types for pads.

INHERITED = 0

NONE = 3

SOLID = 1

THERMAL_RELIEF = 2

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.primitive_graphics module

Basic graphical elements (lines, circles, rectangles, arcs, polygons).

Primitive graphics elements for KiCad S-expressions - basic geometric shapes.

class Arc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Arc definition token.

The ‘arc’ token defines a graphical arc in a symbol definition in the format:

(arc
    (start X Y)
    (mid X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
    (uuid UUID)
)

Parameters:

start (Start) – Start point of the arc
mid (Mid | None) – Mid point of the arc (optional)
end (End) – End point of the arc
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class Bezier(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)[source]

Bases: NamedObject

Bezier curve definition token.

The ‘bezier’ token defines a graphic Cubic Bezier curve in the format:

(bezier
    COORDINATE_POINT_LIST
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

pts (Pts) – List of X/Y coordinates of the four points of the curve
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition for filling (optional)
width (NamedFloat) – Line width of the curve (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=<factory>, fill=<factory>, width=<factory>, uuid=None)

class Center(x=0.0, y=0.0)[source]

Bases: NamedObject

Center point definition token.

The ‘center’ token defines a center point in the format:

(center X Y)

Parameters:

x (float) – Horizontal position of the center point
y (float) – Vertical position of the center point

__init__(x=0.0, y=0.0)

class Circle(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Circle definition token.

The ‘circle’ token defines a graphical circle in a symbol definition in the format:

(circle
    (center X Y)
    (radius RADIUS)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

center (Center) – Center point of the circle
radius (NamedFloat) – Radius length of the circle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(center=<factory>, radius=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class End(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

End point definition token.

The ‘end’ token defines an end point in the format:

(end X Y)

Parameters:

x (float) – Horizontal position of the end point
y (float) – Vertical position of the end point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Fill(type=<factory>, color=<factory>)[source]

Bases: NamedObject

Fill definition token.

The ‘fill’ token defines how schematic and symbol library graphical items are filled in the format: (fill

(type none | outline | background) (color R G B A)

)

This represents the nested structure exactly as it appears in the S-expression files.

Parameters:

type (Type) – Fill type specification (optional)
color (Color) – Fill color specification (optional)

__init__(type=<factory>, color=<factory>)

class Line(start=<factory>, end=<factory>, uuid=None)[source]

Bases: NamedObject

Line definition token.

The ‘line’ token defines a basic line geometry in the format:

(line (start X Y) (end X Y) (uuid UUID))

Parameters:

start (Start) – Start point of the line
end (End) – End point of the line
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, uuid=None)

class Mid(x=0.0, y=0.0)[source]

Bases: NamedObject

Mid point definition token.

The ‘mid’ token defines a mid point in the format:

(mid X Y)

Parameters:

x (float) – Horizontal position of the mid point
y (float) – Vertical position of the mid point

__init__(x=0.0, y=0.0)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class Polygon(pts=<factory>, uuid=None)[source]

Bases: NamedObject

Polygon definition token.

The ‘polygon’ token defines a polygon with multiple points in the format:

(polygon (pts (xy X Y) (xy X Y) ...) (uuid UUID))

Parameters:

pts (Pts) – Polygon vertex points
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, uuid=None)

class Polyline(pts=<factory>, stroke=None, fill=None, uuid=None)[source]

Bases: NamedObject

Polyline definition token.

The ‘polyline’ token defines a connected series of line segments in the format:

(polyline
    (pts (xy X Y) (xy X Y) ...)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

pts (Pts) – Polyline connection points
stroke (Stroke | None) – Stroke definition for outline (optional)
fill (Fill | None) – Fill definition (optional)
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, stroke=None, fill=None, uuid=None)

class Pts(points=<factory>)[source]

Bases: NamedObject

Coordinate point list definition token.

The ‘pts’ token defines a list of coordinate points in the format: (pts

(xy X Y) … (xy X Y)

)

Where each xy token defines a single X and Y coordinate pair. The number of points is determined by the object type.

Parameters:: points (List[Xy]) – List of 2D coordinate points

__init__(points=<factory>)

xy(x, y)[source]

Add a coordinate point to the list.

Parameters:

x (float) – X coordinate
y (float) – Y coordinate

Returns:

Self (for method chaining)

Return type:

Pts

class Rect(start=<factory>, end=<factory>)[source]

Bases: NamedObject

Rectangle definition token.

The ‘rect’ token defines a basic rectangle geometry in the format:

(rect (start X Y) (end X Y))

Parameters:

start (Start) – Start corner of the rectangle
end (End) – End corner of the rectangle

__init__(start=<factory>, end=<factory>)

class Rectangle(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)[source]

Bases: NamedObject

Rectangle definition token (symbol form).

The ‘rectangle’ token defines a graphical rectangle in a symbol definition in the format:

(rectangle
    (start X Y)
    (end X Y)
    STROKE_DEFINITION
    FILL_DEFINITION
)

Parameters:

start (Start) – Start point of the rectangle
end (End) – End point of the rectangle
stroke (Stroke) – Stroke definition for outline
fill (Fill) – Fill definition for filling
uuid (Uuid | None) – Unique identifier (optional)

__init__(start=<factory>, end=<factory>, stroke=<factory>, fill=<factory>, uuid=None)

class Start(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

Start point definition token.

The ‘start’ token defines a start point in the format: (start X Y)

Parameters:

x (float) – Horizontal position of the start point
y (float) – Vertical position of the start point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Stroke(width=<factory>, type=<factory>, color=<factory>)[source]

Bases: NamedObject

Stroke definition token.

The ‘stroke’ token defines how the outlines of graphical objects are drawn in the format: (stroke

(width WIDTH) (type TYPE) (color R G B A)

)

This represents the nested structure exactly as it appears in the S-expression files.

Parameters:

width (NamedFloat) – Line width specification
type (Type) – Stroke line style specification
color (Color) – Line color specification (optional)

__init__(width=<factory>, type=<factory>, color=<factory>)

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.advanced_graphics module

Advanced graphical elements (images, text boxes, dimension annotations).

Advanced graphics elements for KiCad S-expressions - complex graphical objects.

class At(x=0.0, y=0.0, angle=0.0)[source]

Bases: NamedObject

Position identifier token that defines positional coordinates and rotation of an object.

The ‘at’ token defines the positional coordinates in the format:: (at X Y [ANGLE])

Note

Symbol text ANGLEs are stored in tenth’s of a degree. All other ANGLEs are stored in degrees. For 3D model positioning, use ModelAt class which supports (at (xyz X Y Z)) format.

Parameters:

x (float) – Horizontal position of the object
y (float) – Vertical position of the object
angle (float | None) – Rotational angle of the object

__init__(x=0.0, y=0.0, angle=0.0)

class Center(x=0.0, y=0.0)[source]

Bases: NamedObject

Center point definition token.

The ‘center’ token defines a center point in the format:

(center X Y)

Parameters:

x (float) – Horizontal position of the center point
y (float) – Vertical position of the center point

__init__(x=0.0, y=0.0)

class Dimension(locked=<factory>, type=<factory>, layer=<factory>, uuid=<factory>, pts=<factory>, height=<factory>, orientation=<factory>, leader_length=<factory>, gr_text=<factory>, format=<factory>, style=<factory>)[source]

Bases: NamedObject

Dimension definition token.

The ‘dimension’ token defines measurement dimensions in the format:

(dimension
    [locked]
    (type DIMENSION_TYPE)
    (layer LAYER_DEFINITION)
    (uuid UUID)
    (pts (xy X Y) (xy X Y))
    [(height HEIGHT)]
    [(orientation ORIENTATION)]
    [(leader_length LEADER_LENGTH)]
    [(gr_text GRAPHICAL_TEXT)]
    [(format DIMENSION_FORMAT)]
    (style DIMENSION_STYLE)
)

Parameters:

locked (TokenFlag) – Whether dimension is locked (optional)
type (Type) – Dimension type (aligned | leader | center | orthogonal | radial)
layer (Layer) – Layer definition
uuid (Uuid) – Unique identifier
pts (Pts) – Dimension points
height (NamedFloat) – Height for aligned dimensions (optional)
orientation (NamedFloat) – Orientation angle for orthogonal dimensions (optional)
leader_length (NamedFloat) – Leader length for radial dimensions (optional)
gr_text (GrText) – Dimension text (optional)
format (Format) – Dimension format (optional)
style (NamedString) – Dimension style

__init__(locked=<factory>, type=<factory>, layer=<factory>, uuid=<factory>, pts=<factory>, height=<factory>, orientation=<factory>, leader_length=<factory>, gr_text=<factory>, format=<factory>, style=<factory>)

class Effects(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)[source]

Bases: NamedObject

Text effects definition token.

The ‘effects’ token defines text formatting effects in the format:

(effects
    (font [size SIZE] [thickness THICKNESS] [bold] [italic])
    [(justify JUSTIFY)]
    [hide]
)

Parameters:

font (Font) – Font definition (optional)
justify (Justify) – Text justification (optional)
hide (TokenFlag) – Whether text is hidden (optional)
href (NamedString) – Hyperlink reference (optional)

__init__(font=<factory>, justify=<factory>, hide=<factory>, href=<factory>)

class End(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

End point definition token.

The ‘end’ token defines an end point in the format:

(end X Y)

Parameters:

x (float) – Horizontal position of the end point
y (float) – Vertical position of the end point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Format(prefix=<factory>, suffix=<factory>, units=<factory>, units_format=<factory>, precision=<factory>, override_value=<factory>, suppress_zeros=<factory>)[source]

Bases: NamedObject

Dimension format definition token.

The ‘format’ token defines formatting for dimension text in the format:

(format
    [(prefix "PREFIX")]
    [(suffix "SUFFIX")]
    (units UNITS)
    (units_format UNITS_FORMAT)
    (precision PRECISION)
    [(override_value "VALUE")]
    [(suppress_zeros yes | no)]
)

Parameters:

prefix (NamedString) – Text prefix (optional)
suffix (NamedString) – Text suffix (optional)
units (NamedString) – Units type (0=inches, 1=mils, 2=mm, 3=auto)
units_format (NamedInt) – Units format (0=no suffix, 1=bare, 2=parenthesis)
precision (NamedInt) – Precision digits
override_value (NamedString) – Override text value (optional)
suppress_zeros (TokenFlag) – Whether to suppress trailing zeros (optional)

__init__(prefix=<factory>, suffix=<factory>, units=<factory>, units_format=<factory>, precision=<factory>, override_value=<factory>, suppress_zeros=<factory>)

class FpArc(start=<factory>, mid=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, locked=<factory>, angle=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint arc definition token.

The ‘fp_arc’ token defines an arc in a footprint in the format:

(fp_arc
    (start X Y)
    [(mid X Y)]
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    [STROKE_DEFINITION]
    [(locked)]
    [(uuid UUID)]
    [(angle ANGLE)]
)

Parameters:

start (Start) – Start point coordinates
mid (Mid) – Mid point coordinates (optional)
end (End) – End point coordinates
layer (Layer) – Layer definition
width (NamedFloat) – Line width (prior to version 7) (optional)
stroke (Stroke) – Stroke definition (from version 7) (optional)
locked (TokenFlag) – Whether the arc is locked (optional)
angle (NamedFloat) – Arc angle in degrees (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(start=<factory>, mid=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, locked=<factory>, angle=<factory>, uuid=<factory>)

class FpCircle(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint circle definition token.

The ‘fp_circle’ token defines a circle in a footprint in the format:

(fp_circle
    (center X Y)
    (end X Y)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

center (Center) – Center point
end (End) – End point
layer (Layer) – Layer definition
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
uuid (Uuid) – Unique identifier (optional)
stroke (Stroke) – Stroke definition (optional)
fill (TokenFlag) – Fill definition (optional)
locked (TokenFlag) – Whether the circle is locked (optional)

__init__(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>)

class FpCurve(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint curve definition token.

The ‘fp_curve’ token defines a Bezier curve in a footprint in the format:

(fp_curve
    (pts (xy X Y) (xy X Y) (xy X Y) (xy X Y))
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

pts (Pts) – Control points
layer (Layer) – Layer definition
width (NamedFloat) – Line width
tstamp (NamedString) – Timestamp UUID (optional)
stroke (Stroke) – Stroke definition (optional)
locked (TokenFlag) – Whether the curve is locked (optional)

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)

class FpLine(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: NamedObject

Footprint line definition token.

The ‘fp_line’ token defines a line in a footprint in the format:

(fp_line
    (start X Y)
    (end X Y)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

start (Start) – Start point
end (End) – End point
layer (Layer) – Layer definition
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
uuid (Uuid) – Unique identifier (optional)
stroke (Stroke) – Stroke definition (optional)
locked (TokenFlag) – Whether the line is locked (optional)

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)

class FpPoly(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint polygon definition token.

The ‘fp_poly’ token defines a polygon in a footprint in the format:

(fp_poly
    (pts (xy X Y) ...)
    (layer LAYER)
    (width WIDTH)
    [(tstamp UUID)]
)

Parameters:

pts (Pts) – Polygon points
layer (Layer) – Layer definition (optional)
width (NamedFloat) – Line width (optional)
tstamp (NamedString) – Timestamp UUID (optional)
stroke (Stroke) – Stroke definition (optional)
fill (TokenFlag) – Fill definition (optional)
locked (TokenFlag) – Whether thepolygon is locked (optional)
uuid (Uuid) – Unique identifier (optional)

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class FpRect(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint rectangle definition token.

The ‘fp_rect’ token defines a graphic rectangle in a footprint definition in the format:

(fp_rect
    (start X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    STROKE_DEFINITION
    [(fill yes | no)]
    [(locked)]
    (uuid UUID)
)

Parameters:

start (Start) – Coordinates of the upper left corner
end (End) – Coordinates of the lower right corner
layer (Layer) – Layer definition
width (NamedFloat) – Line width (prior to version 7) (optional)
stroke (Stroke) – Stroke definition (from version 7) (optional)
fill (TokenFlag) – Whether the rectangle is filled (yes/no) (optional)
locked (TokenFlag) – Whether the rectangle cannot be edited (optional)
uuid (Uuid) – Unique identifier

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class FpText(type='', text='', at=<factory>, unlocked=<factory>, layer=<factory>, hide=<factory>, effects=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Footprint text definition token.

The ‘fp_text’ token defines text in a footprint in the format:

(fp_text
    TYPE
    "TEXT"
    POSITION_IDENTIFIER
    [unlocked]
    (layer LAYER_DEFINITION)
    [hide]
    (effects TEXT_EFFECTS)
    (uuid UUID)
)

Parameters:

type (str) – Text type (reference | value | user)
text (str) – Text content
at (FpTextAt) – Position and rotation coordinates
unlocked (TokenFlag) – Whether text orientation can be other than upright (optional)
layer (Layer) – Layer definition
hide (TokenFlag) – Whether text is hidden (optional)
effects (Effects) – Text effects
uuid (Uuid) – Unique identifier

__init__(type='', text='', at=<factory>, unlocked=<factory>, layer=<factory>, hide=<factory>, effects=<factory>, uuid=<factory>)

class FpTextAt(x=0.0, y=None, angle=None)[source]

Bases: NamedObject

Position identifier token for FpText that supports flexible coordinate formats.

The ‘at’ token for fp_text defines positional coordinates in the format:: (at X [Y] [ANGLE])

Special case: Sometimes only one coordinate is provided like (at 0).

Parameters:

x (float) – Horizontal position of the text
y (float | None) – Vertical position of the text (optional)
angle (float | None) – Rotation angle of the text (optional)

__init__(x=0.0, y=None, angle=None)

class FpTextBox(locked=<factory>, text='', start=<factory>, end=<factory>, pts=<factory>, angle=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>, stroke=<factory>, render_cache=<factory>)[source]

Bases: NamedObject

Footprint text box definition token.

The ‘fp_text_box’ token defines a rectangle containing line-wrapped text in the format:

(fp_text_box
    [locked]
    "TEXT"
    [(start X Y)]
    [(end X Y)]
    [(pts (xy X Y) (xy X Y) (xy X Y) (xy X Y))]
    [(angle ROTATION)]
    (layer LAYER_DEFINITION)
    (uuid UUID)
    TEXT_EFFECTS
    [STROKE_DEFINITION]
    [(render_cache RENDER_CACHE)]
)

Parameters:

locked (TokenFlag) – Whether the text box can be moved (optional)
text (str) – Content of the text box
start (Start) – Top-left corner of cardinally oriented text box (optional)
end (End) – Bottom-right corner of cardinally oriented text box (optional)
pts (Pts) – Four corners of non-cardinally oriented text box (optional)
angle (NamedFloat) – Rotation of the text box in degrees (optional)
layer (Layer) – Layer definition
uuid (Uuid) – Unique identifier
effects (Effects) – Text effects
stroke (Stroke) – Stroke definition for optional border (optional)
render_cache (NamedString) – Text rendering cache for TrueType fonts (optional)

__init__(locked=<factory>, text='', start=<factory>, end=<factory>, pts=<factory>, angle=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>, stroke=<factory>, render_cache=<factory>)

class GrArc(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Graphical arc definition token.

The ‘gr_arc’ token defines an arc graphic object in the format:

(gr_arc
    (start X Y)
    (mid X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    (uuid UUID)
)

Parameters:

start (Start) – Start point coordinates
mid (Mid) – Mid point coordinates
end (End) – End point coordinates
stroke (Stroke) – Stroke definition (optional)
layer (Layer) – Layer definition (optional)
width (NamedFloat) – Line width (deprecated, use stroke) (optional)
uuid (Uuid) – Unique identifier

__init__(start=<factory>, mid=<factory>, end=<factory>, stroke=<factory>, layer=<factory>, width=<factory>, uuid=<factory>)

class GrBbox(start=<factory>, end=<factory>)[source]

Bases: NamedObject

Graphical bounding box definition token.

The ‘gr_bbox’ token defines a bounding box inside which annotations will be shown in the format:

(gr_bbox
    (start X Y)
    (end X Y)
)

Parameters:

start (Start) – Coordinates of the upper left corner
end (End) – Coordinates of the lower right corner

__init__(start=<factory>, end=<factory>)

class GrCircle(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, fill=<factory>, uuid=<factory>)[source]

Bases: NamedObject

Graphical circle definition token.

The ‘gr_circle’ token defines a circle graphic object in the format:

(gr_circle
    (center X Y)
    (end X Y)
    (layer LAYER_DEFINITION)
    (width WIDTH)
    [(fill yes | no)]
    (uuid UUID)
)

Parameters:

center (Center) – Center point coordinates
end (End) – End point defining radius
layer (Layer) – Layer definition
width (NamedFloat) – Line width
fill (TokenFlag) – Fill definition (optional)
uuid (Uuid) – Unique identifier

__init__(center=<factory>, end=<factory>, layer=<factory>, width=<factory>, fill=<factory>, uuid=<factory>)

class GrCurve(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: FpCurve

Graphical curve derived from footprint curve.

Inherits all fields from FpCurve but uses ‘gr_curve’ token.

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, locked=<factory>)

class GrLine(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)[source]

Bases: FpLine

Graphical line derived from footprint line.

Inherits all fields from FpLine but uses ‘gr_line’ token.

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, uuid=<factory>, stroke=<factory>, locked=<factory>)

class GrPoly(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: FpPoly

Graphical polygon derived from footprint polygon.

Inherits all fields from FpPoly but uses ‘gr_poly’ token.

__init__(pts=<factory>, layer=<factory>, width=<factory>, tstamp=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class GrRect(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)[source]

Bases: FpRect

Graphical rectangle derived from footprint rectangle.

Inherits all fields from FpRect but uses ‘gr_rect’ token.

__init__(start=<factory>, end=<factory>, layer=<factory>, width=<factory>, stroke=<factory>, fill=<factory>, locked=<factory>, uuid=<factory>)

class GrText(text='', at=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>)[source]

Bases: NamedObject

Graphical text definition token.

The ‘gr_text’ token defines text graphic objects in the format:

(gr_text
    "TEXT"
    POSITION_IDENTIFIER
    (layer LAYER_DEFINITION [knockout])
    (uuid UUID)
    (effects TEXT_EFFECTS)
)

Parameters:

text (str) – Text content
at (At) – Position and rotation coordinates
layer (Layer) – Layer definition
uuid (Uuid) – Unique identifier
effects (Effects) – Text effects

__init__(text='', at=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>)

class GrTextBox(locked=<factory>, text='', start=<factory>, end=<factory>, pts=<factory>, angle=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>, stroke=<factory>, render_cache=<factory>)[source]

Bases: NamedObject

Graphical text box definition token.

The ‘gr_text_box’ token defines a rectangle containing line-wrapped text in the format:

(gr_text_box
    [locked]
    "TEXT"
    [(start X Y)]
    [(end X Y)]
    [(pts (xy X Y) (xy X Y) (xy X Y) (xy X Y))]
    [(angle ROTATION)]
    (layer LAYER_DEFINITION)
    (uuid UUID)
    TEXT_EFFECTS
    [STROKE_DEFINITION]
    [(render_cache RENDER_CACHE)]
)

Parameters:

locked (TokenFlag) – Whether the text box can be moved (optional)
text (str) – Content of the text box
start (Start) – Top-left corner of cardinally oriented text box (optional)
end (End) – Bottom-right corner of cardinally oriented text box (optional)
pts (Pts) – Four corners of non-cardinally oriented text box (optional)
angle (NamedFloat) – Rotation of the text box in degrees (optional)
layer (Layer) – Layer definition
uuid (Uuid) – Unique identifier
effects (Effects) – Text effects
stroke (Stroke) – Stroke definition for optional border (optional)
render_cache (NamedString) – Text rendering cache for TrueType fonts (optional)

__init__(locked=<factory>, text='', start=<factory>, end=<factory>, pts=<factory>, angle=<factory>, layer=<factory>, uuid=<factory>, effects=<factory>, stroke=<factory>, render_cache=<factory>)

class Layer(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)[source]

Bases: NamedObject

Layer definition token.

The ‘layer’ token defines layer information in the format:

(layer "NAME" | dielectric NUMBER (type "DESCRIPTION")
       [(color "COLOR")] [(thickness THICKNESS)]
       [(material "MATERIAL")] [(epsilon_r VALUE)]
       [(loss_tangent VALUE)])

For simple layer references:: (layer “LAYER_NAME”)

Parameters:

name (str) – Layer name or ‘dielectric’
number (int | None) – Layer stack number (optional)
type (str | None) – Layer type description (optional)
color (str | None) – Layer color as string (optional)
thickness (float | None) – Layer thickness value (optional)
material (str | None) – Material name (optional)
epsilon_r (float | None) – Dielectric constant value (optional)
loss_tangent (float | None) – Loss tangent value (optional)

__init__(name='', number=None, type=None, color=None, thickness=None, material=None, epsilon_r=None, loss_tangent=None)

class Mid(x=0.0, y=0.0)[source]

Bases: NamedObject

Mid point definition token.

The ‘mid’ token defines a mid point in the format:

(mid X Y)

Parameters:

x (float) – Horizontal position of the mid point
y (float) – Vertical position of the mid point

__init__(x=0.0, y=0.0)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Pts(points=<factory>)[source]

Bases: NamedObject

Coordinate point list definition token.

The ‘pts’ token defines a list of coordinate points in the format: (pts

(xy X Y) … (xy X Y)

)

Where each xy token defines a single X and Y coordinate pair. The number of points is determined by the object type.

Parameters:: points (List[Xy]) – List of 2D coordinate points

__init__(points=<factory>)

xy(x, y)[source]

Add a coordinate point to the list.

Parameters:

x (float) – X coordinate
y (float) – Y coordinate

Returns:

Self (for method chaining)

Return type:

Pts

class Start(x=0.0, y=0.0, corner=None)[source]

Bases: NamedObject

Start point definition token.

The ‘start’ token defines a start point in the format: (start X Y)

Parameters:

x (float) – Horizontal position of the start point
y (float) – Vertical position of the start point
corner (str | None) – Corner reference (optional)

__init__(x=0.0, y=0.0, corner=None)

class Stroke(width=<factory>, type=<factory>, color=<factory>)[source]

Bases: NamedObject

Stroke definition token.

The ‘stroke’ token defines how the outlines of graphical objects are drawn in the format: (stroke

(width WIDTH) (type TYPE) (color R G B A)

)

This represents the nested structure exactly as it appears in the S-expression files.

Parameters:

width (NamedFloat) – Line width specification
type (Type) – Stroke line style specification
color (Color) – Line color specification (optional)

__init__(width=<factory>, type=<factory>, color=<factory>)

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Type(value='')[source]

Bases: NamedObject

Type definition token.

The ‘type’ token defines a type value in the format: (type VALUE)

Parameters:: value (str) – Type value

__init__(value='')

to_sexpr()[source]

Serialize with unquoted value.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

kicadfiles.zone_system module

Copper zones, keepout areas, and filled polygon regions.

Zone system elements for KiCad S-expressions - copper zones and keepout areas.

class Any(*args, **kwargs)[source]

Bases: object

Special type indicating an unconstrained type.

Any is compatible with every type.
Any assumed to have all methods.
All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class ConnectPads(connection_type=None, clearance=<factory>)[source]

Bases: NamedObject

Connect pads definition token for zones.

The ‘connect_pads’ token defines pad connection type and clearance in the format:

(connect_pads [CONNECTION_TYPE] (clearance CLEARANCE))

Parameters:

connection_type (str | None) – Pad connection type (thru_hole_only | full | no) (optional)
clearance (NamedFloat) – Pad clearance

__init__(connection_type=None, clearance=<factory>)

class Copperpour(value=ZoneKeepoutSetting.NOT_ALLOWED)[source]

Bases: NamedObject

Copper pour definition token.

The ‘copperpour’ token defines copper pour properties in the format:

(copperpour VALUE)

where VALUE can be: not_allowed, allowed

Parameters:: value (ZoneKeepoutSetting) – Copper pour setting

__init__(value=ZoneKeepoutSetting.NOT_ALLOWED)

class FillSegments(segments=<factory>)[source]

Bases: NamedObject

Fill segments definition token.

The ‘fill_segments’ token defines zone fill segments in the format:

(fill_segments ...)

Parameters:: segments (List[Any]) – List of fill segments

__init__(segments=<factory>)

class FilledPolygon(layer=<factory>, pts=<factory>)[source]

Bases: NamedObject

Filled polygon definition token.

The ‘filled_polygon’ token defines the polygons used to fill the zone in the format:

(filled_polygon
    (layer LAYER_DEFINITION)
    COORDINATE_POINT_LIST
)

Parameters:

layer (NamedString) – Layer the zone fill resides on
pts (Pts) – List of polygon X/Y coordinates used to fill the zone

__init__(layer=<factory>, pts=<factory>)

class FilledSegments(layer='', segments=<factory>)[source]

Bases: NamedObject

Filled segments definition token.

The ‘filled_segments’ token defines segments used to fill the zone in the format:

(fill_segments
    (layer LAYER_DEFINITION)
    COORDINATED_POINT_LIST
)

Parameters:

layer (str) – Layer the zone fill resides on
segments (List[Pts]) – List of X and Y coordinates of segments used to fill the zone

__init__(layer='', segments=<factory>)

class Hatch(style=HatchStyle.EDGE, pitch=0.5)[source]

Bases: NamedObject

Zone hatch display definition token.

The ‘hatch’ token defines zone outline display style and pitch in the format:

(hatch STYLE PITCH)

Parameters:

style (HatchStyle) – Hatch display style
pitch (float) – Hatch pitch distance

__init__(style=HatchStyle.EDGE, pitch=0.5)

class HatchOrientation(angle=<factory>)[source]

Bases: NamedObject

Hatch orientation definition token.

The ‘hatch_orientation’ token defines the angle for hatch lines in the format:

(hatch_orientation ANGLE)

Parameters:: angle (NamedFloat) – Hatch line angle in degrees

__init__(angle=<factory>)

class HatchStyle(*values)[source]

Bases: Enum

Zone hatch display styles.

EDGE = 'edge'

FULL = 'full'

NONE = 'none'

class Keepout(tracks=ZoneKeepoutSetting.NOT_ALLOWED, vias=ZoneKeepoutSetting.NOT_ALLOWED, pads=ZoneKeepoutSetting.NOT_ALLOWED, copperpour=ZoneKeepoutSetting.NOT_ALLOWED, footprints=ZoneKeepoutSetting.NOT_ALLOWED)[source]

Bases: NamedObject

Keepout zone definition token.

The ‘keepout’ token defines which objects should be kept out of the zone in the format:

(keepout
    (tracks KEEPOUT)
    (vias KEEPOUT)
    (pads KEEPOUT)
    (copperpour KEEPOUT)
    (footprints KEEPOUT)
)

Parameters:

tracks (ZoneKeepoutSetting) – Whether tracks should be excluded (allowed | not_allowed)
vias (ZoneKeepoutSetting) – Whether vias should be excluded (allowed | not_allowed)
pads (ZoneKeepoutSetting) – Whether pads should be excluded (allowed | not_allowed)
copperpour (ZoneKeepoutSetting) – Whether copper pours should be excluded (allowed | not_allowed)
footprints (ZoneKeepoutSetting) – Whether footprints should be excluded (allowed | not_allowed)

__init__(tracks=ZoneKeepoutSetting.NOT_ALLOWED, vias=ZoneKeepoutSetting.NOT_ALLOWED, pads=ZoneKeepoutSetting.NOT_ALLOWED, copperpour=ZoneKeepoutSetting.NOT_ALLOWED, footprints=ZoneKeepoutSetting.NOT_ALLOWED)

class Mode(mode=ZoneFillMode.SOLID)[source]

Bases: NamedObject

Fill mode definition token.

The ‘mode’ token defines the zone fill mode in the format:

(mode MODE)

Parameters:: mode (ZoneFillMode) – Fill mode

__init__(mode=ZoneFillMode.SOLID)

class NamedFloat(token='', value=0.0)[source]

Bases: NamedValue

Float wrapper for named values.

__init__(token='', value=0.0)

class NamedInt(token='', value=0)[source]

Bases: NamedValue

Integer wrapper for named values.

__init__(token='', value=0)

class NamedObject[source]

Bases: SExpressionBase

Base class for named S-expression objects.

Subclasses should define __token_name__ as ClassVar[str].

__init__()

__post_init__()[source]

Validate token name is defined.

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

classmethod from_str(sexpr_string, strictness=ParseStrictness.STRICT)[source]

Parse from S-expression string - convenience method for better clarity.

to_sexpr()[source]

Serialize to S-expression.

to_sexpr_str(_indent_level=0)[source]

Convert to KiCad-formatted S-expression string.

Parameters:: _indent_level (int) – Internal parameter for recursion depth
Returns:: Formatted S-expression string
Return type:: str

class NamedString(token='', value='')[source]

Bases: NamedValue

String wrapper for named values.

__init__(token='', value='')

class Polygon(pts=<factory>, uuid=None)[source]

Bases: NamedObject

Polygon definition token.

The ‘polygon’ token defines a polygon with multiple points in the format:

(polygon (pts (xy X Y) (xy X Y) ...) (uuid UUID))

Parameters:

pts (Pts) – Polygon vertex points
uuid (Uuid | None) – Unique identifier (optional)

__init__(pts=<factory>, uuid=None)

class Pts(points=<factory>)[source]

Bases: NamedObject

Coordinate point list definition token.

The ‘pts’ token defines a list of coordinate points in the format: (pts

(xy X Y) … (xy X Y)

)

Where each xy token defines a single X and Y coordinate pair. The number of points is determined by the object type.

Parameters:: points (List[Xy]) – List of 2D coordinate points

__init__(points=<factory>)

xy(x, y)[source]

Add a coordinate point to the list.

Parameters:

x (float) – X coordinate
y (float) – Y coordinate

Returns:

Self (for method chaining)

Return type:

Pts

class Smoothing(style=SmoothingStyle.NONE)[source]

Bases: NamedObject

Zone smoothing definition token.

The ‘smoothing’ token defines corner smoothing style in the format:

(smoothing STYLE)

Parameters:: style (SmoothingStyle) – Corner smoothing style

__init__(style=SmoothingStyle.NONE)

class SmoothingStyle(*values)[source]

Bases: Enum

Zone corner smoothing styles.

CHAMFER = 'chamfer'

FILLET = 'fillet'

NONE = 'none'

class TokenFlag(token='', token_value=None)[source]

Bases: TokenBase

Optional flag with optional value.

Formats:: (token) -> token=”token”, token_value=None (token value) -> token=”token”, token_value=”value”

__bool__()[source]

Boolean conversion based on token_value.

__call__(new_value=None)[source]

Allow calling the flag to update its value.

This enables convenient syntax like: pcb.legacy_teardrops(“no”) instead of: pcb.legacy_teardrops = TokenFlag(“legacy_teardrops”, “no”)

Parameters:: new_value (str | None) – New token value to set
Returns:: Self for method chaining
Return type:: TokenFlag

__init__(token='', token_value=None)

classmethod from_sexpr(sexpr, strictness=ParseStrictness.STRICT, cursor=None)[source]

Parse from S-expression.

TokenFlag supports only simple flags: - (token) or (token value) where value is NOT a nested list

Invalid: (fill (type none)) -> Use proper Fill class instead

to_sexpr()[source]

Serialize to S-expression.

class Uuid(value='')[source]

Bases: NamedObject

UUID identifier token.

The ‘uuid’ token defines a universally unique identifier in the format: (uuid UUID_VALUE)

Parameters:: value (str) – UUID value

__init__(value='')

classmethod create()[source]

Create a new UUID identifier (factory method).

Returns:: New Uuid object with a generated UUID value
Return type:: Uuid

new_id()[source]

Generate a new UUID identifier and update this instance.

Returns:: Self (for method chaining)
Return type:: Uuid

class Zone(hatch=<factory>, connect_pads=<factory>, fill=<factory>, polygon=<factory>, net=<factory>, net_name=<factory>, layer=<factory>, uuid=<factory>, min_thickness=<factory>, name=None, priority=None, filled_areas_thickness=<factory>, keepout=<factory>, filled_polygons=<factory>, filled_segments=<factory>)[source]

Bases: NamedObject

Zone definition token.

The ‘zone’ token defines a zone on the board or footprint in the format:

(zone
    (net NET_NUMBER)
    (net_name "NET_NAME")
    (layer LAYER_DEFINITION)
    (uuid UUID)
    [(name "NAME")]
    (hatch STYLE PITCH)
    [(priority PRIORITY)]
    (connect_pads [CONNECTION_TYPE] (clearance CLEARANCE))
    (min_thickness THICKNESS)
    [(filled_areas_thickness no)]
    [ZONE_KEEPOUT_SETTINGS]
    ZONE_FILL_SETTINGS
    (polygon COORDINATE_POINT_LIST)
    [ZONE_FILL_POLYGONS...]
    [ZONE_FILL_SEGMENTS...]
)

Parameters:

hatch (Hatch) – Hatch settings
connect_pads (ConnectPads) – Pad connection settings
fill (ZoneFill) – Fill settings
polygon (Polygon) – Zone outline polygon
net (NamedInt) – Net number
net_name (NamedString) – Net name
layer (NamedString) – Layer name
uuid (Uuid) – Unique identifier
min_thickness (NamedFloat) – Minimum thickness
name (str | None) – Zone name (optional)
priority (int | None) – Zone priority (optional)
filled_areas_thickness (TokenFlag) – Filled areas thickness flag (optional)
keepout (Keepout | None) – Keepout settings (optional)
filled_polygons (List[FilledPolygon] | None) – List of fill polygons (optional)
filled_segments (List[FilledSegments] | None) – List of fill segments (optional)

__init__(hatch=<factory>, connect_pads=<factory>, fill=<factory>, polygon=<factory>, net=<factory>, net_name=<factory>, layer=<factory>, uuid=<factory>, min_thickness=<factory>, name=None, priority=None, filled_areas_thickness=<factory>, keepout=<factory>, filled_polygons=<factory>, filled_segments=<factory>)

class ZoneFill(enabled=None, thermal_gap=<factory>, thermal_bridge_width=<factory>, smoothing=<factory>, radius=<factory>)[source]

Bases: NamedObject

Zone fill definition token.

The ‘fill’ token for zones defines zone fill properties in the format:

(fill yes
    (thermal_gap GAP)
    (thermal_bridge_width WIDTH)
    (smoothing STYLE)
    (radius RADIUS)
)

Parameters:

enabled (str | None) – Whether fill is enabled (yes|no) (optional)
thermal_gap (NamedFloat) – Thermal gap distance (optional)
thermal_bridge_width (NamedFloat) – Thermal bridge width (optional)
smoothing (NamedString) – Smoothing style (optional)
radius (NamedFloat) – Smoothing radius (optional)

__init__(enabled=None, thermal_gap=<factory>, thermal_bridge_width=<factory>, smoothing=<factory>, radius=<factory>)

class ZoneFillMode(*values)[source]

Bases: Enum

Zone fill modes.

HATCHED = 'hatched'

SOLID = 'solid'

class ZoneKeepoutSetting(*values)[source]

Bases: Enum

Zone keepout settings.

ALLOWED = 'allowed'

NOT_ALLOWED = 'not_allowed'

dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)[source]

Add dunder methods based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, a new class with a __slots__ attribute is returned.

field(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)[source]

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.