kiutils.items package

Board items (kiutils.items.brditems)

Classes to manage KiCad board items

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

20.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/

class kiutils.items.brditems.GeneralSettings(thickness: float = 1.6)

Bases: object

The general token define general information about the board

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_general_section

thickness: float = 1.6: The thickness token attribute defines the overall board thickness

classmethod from_sexpr(exp: list) → GeneralSettings

Convert the given S-Expresstion into a GeneralSettings object

Args:

exp (list): Part of parsed S-Expression (general ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not general

Returns:

GeneralSettings: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.LayerToken(ordinal: int = 0, name: str = 'F.Cu', type: str = 'signal', userName: str | None = None)

Bases: object

Intermediate type used for the layers token in a board

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_layers_section

ordinal: int = 0: The layer ordinal is an integer used to associate the layer stack ordering. This is mostly to ensure correct mapping when the number of layers is increased in the future

name: str = 'F.Cu': The name is the layer name defined for internal board use

type: str = 'signal': The layer type defines the type of layer and can be defined as jumper, mixed, power, signal, or user.

userName: str | None = None: The optional userName attribute defines the custom user name

classmethod from_sexpr(exp: list) → LayerToken

Convert the given S-Expresstion into a LayerToken object

Args:

exp (list): Part of parsed S-Expression (<nr> "<name>" <type>)

Raises:

Exception: When given parameter’s type is not a list or the length of the list is not 3 - 4
Exception: When the first item of the list is not kicad_pcb

Returns:

LayerToken: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.StackupSubLayer(thickness: float = 0.1, material: str | None = None, epsilonR: float | None = None, lossTangent: float | None = None)

Bases: object

The StackupSubLayer token defines a sublayer used when stacking dielectrics in a PCB

thickness: float = 0.1: The thickness token defines the thickness of the sublayer. Defaults to 0.1

material: str | None = None: The optional material token defines a string that describes the sublayer material

epsilonR: float | None = None: The optional epsilonR token defines the dielectric constant of the sublayer material

lossTangent: float | None = None: The optional layer lossTangent token defines the dielectric loss tangent of the sublayer

classmethod from_sexpr(exp: list) → StackupSubLayer

This class cannot be derived from an S-Expression as the format currently used in KiCad board files does not match the usual convention. Assign member values manually when using this object.

Raises:

NotImplementedError

to_sexpr(indent=0, newline=False) → str

Generate the S-Expression representing this object. The representation differs from the normal form of an S-Expression as this uses no opening and closing parenthesis.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.StackupLayer(name: str = '', type: str = '', color: str | None = None, thickness: float | None = None, material: str | None = None, epsilonR: float | None = None, lossTangent: float | None = None, subLayers: ~typing.List[~kiutils.items.brditems.StackupSubLayer] = <factory>)

Bases: object

The layer token defines the stack up setting of a single layer in the board stack up settings.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_stack_up_settings

name: str = '': The name attribute is either one of the canonical copper or technical layer names or dielectric ID if it is dielectric layer

type: str = '': The type token defines a string that describes the layer

color: str | None = None: The optional color token defines a string that describes the layer color. This is only used on solder mask and silkscreen layers

thickness: float | None = None: The optional thickness token defines the thickness of the layer where appropriate

material: str | None = None: The optional material token defines a string that describes the layer material where appropriate

epsilonR: float | None = None: The optional epsilonR token defines the dielectric constant of the layer material

lossTangent: float | None = None: The optional layer lossTangent token defines the dielectric loss tangent of the layer

subLayers: List[StackupSubLayer]: The sublayers token defines a list of zero or more sublayers that are used to create stacks of dielectric layers. Does not apply to copper-type layers.

classmethod from_sexpr(exp: list) → StackupLayer

Convert the given S-Expresstion into a StackupLayer object

Args:

exp (list): Part of parsed S-Expression (layer ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not layer

Returns:

StackupLayer: Object of the class initialized with the given S-Expression

to_sexpr(indent=6, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.Stackup(layers: ~typing.List[~kiutils.items.brditems.StackupLayer] = <factory>, copperFinish: str | None = None, dielectricContraints: str | None = None, edgeConnector: str | None = None, castellatedPads: bool = False, edgePlating: bool = False)

Bases: object

The stackup token defines the board stack up settings and is defined in the setup section.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_stack_up_settings

layers: List[StackupLayer]: The ``layers``token is a list of layer settings for each layer required to manufacture a board including the dielectric material between the actual layers defined in the board editor.

copperFinish: str | None = None: The optional copperFinish token is a string that defines the copper finish used to manufacture the board

dielectricContraints: str | None = None: The optional dielectricContraints token define if the board should meet all dielectric requirements. Valid values are yes and no.

edgeConnector: str | None = None: The optional edgeConnector token defines if the board has an edge connector (value: yes) and if the edge connector is bevelled (value: bevelled)

castellatedPads: bool = False: The castellatedPads token defines if the board edges contain castellated pads

edgePlating: bool = False: The edgePlating token defines if the board edges should be plated.

classmethod from_sexpr(exp: list) → Stackup

Convert the given S-Expresstion into a Stackup object

Args:

exp (list): Part of parsed S-Expression (stackup ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not stackup

Returns:

Stackup: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.PlotSettings(layerSelection: str = '', plotOnAllLayersSelection: str | None = None, disableApertMacros: bool = False, useGerberExtensions: bool = False, useGerberAttributes: bool = False, useGerberAdvancedAttributes: bool = False, createGerberJobFile: bool = False, dashedLineDashRatio: float | None = None, dashedLineGapRatio: float | None = None, svgUseInch: bool | None = None, svgPrecision: float = 0.0, excludeEdgeLayer: bool | None = None, plotFameRef: bool = False, viasOnMask: bool = False, mode: int = 1, useAuxOrigin: bool = False, hpglPenNumber: int = 0, hpglPenSpeed: int = 0, hpglPenDiameter: float = 0.0, dxfPolygonMode: bool = False, dxfImperialUnits: bool = False, dxfUsePcbnewFont: bool = False, psNegative: bool = False, psA4Output: bool = False, plotReference: bool = False, plotValue: bool = False, plotInvisibleText: bool = False, sketchPadsOnFab: bool = False, subtractMaskFromSilk: bool = False, outputFormat: int = 0, mirror: bool = False, drillShape: int = 0, scaleSelection: int = 1, outputDirectory: str = '')

Bases: object

The pcbplotparams token defines the plotting and printing settings used for the last plot and is defined in the set up section.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_plot_settings

layerSelection: str = '': The layerSelection token defines a hexadecimal bit set of the layers to plot

plotOnAllLayersSelection: str | None = None

The plotOnAllLayersSelection token defines a hexadecimal bit set of layers where all selected layers shall be plotted.

Available and required since KiCad v7

disableApertMacros: bool = False: The disableApertMacros token defines if aperture macros are to be used in gerber plots

useGerberExtensions: bool = False: The useGerberExtensions token defines if the Protel layer file name extensions are to be used in gerber plots

useGerberAttributes: bool = False: The useGerberAttributes token defines if the X2 extensions are used in gerber plots

useGerberAdvancedAttributes: bool = False: The useGerberAdvancedAttributes token defines if the netlist information should be included in gerber plots

createGerberJobFile: bool = False: The createGerberJobFile token defines if a job file should be created when plotting gerber files

dashedLineDashRatio: float | None = None

The dashedLineDashRatio token’s documentation is still missing ..

Available and required since KiCad v7

dashedLineGapRatio: float | None = None

The dashedLineGapRatio token’s documentation is still missing ..

Available and required since KiCad v7

svgUseInch: bool | None = None

The svgUseInch token defines if inch units should be use when plotting SVG files.

Required until KiCad v6, removed since KiCad v7

svgPrecision: float = 0.0: The svgPrecision token defines the units precision used when plotting SVG files

excludeEdgeLayer: bool | None = None

The excludeEdgeLayer token defines if the board edge layer is plotted on all layers.

Required until KiCad v6, removed since KiCad v7

plotFameRef: bool = False: The plotFameRef token defines if the border and title block should be plotted

viasOnMask: bool = False: The viasOnMask token defines if the vias are to be tented

mode: int = 1: The mode token defines the plot mode. An attribute of 1 plots in the normal mode and an attribute of 2 plots in the outline (sketch) mode.

useAuxOrigin: bool = False: The useAuxOrigin token determines if all coordinates are offset by the defined user origin

hpglPenNumber: int = 0: The hpglPenNumber token defines the integer pen number used for HPGL plots

hpglPenSpeed: int = 0: The hpglPenSpeed token defines the integer pen speed used for HPGL plots

hpglPenDiameter: float = 0.0: The hpglPenDiameter token defines the floating point pen size for HPGL plots

dxfPolygonMode: bool = False: The dxfPolygonMode token defines if the polygon mode should be used for DXF plots

dxfImperialUnits: bool = False: The dxfImperialUnits token defines if imperial units should be used for DXF plots

dxfUsePcbnewFont: bool = False: The dxfUsePcbnewFont token defines if the Pcbnew font (vector font) or the default font should be used for DXF plots

psNegative: bool = False: The psNegative token defines if the output should be the negative for PostScript plots

psA4Output: bool = False: The psA4Output token defines if the A4 page size should be used for PostScript plots

plotReference: bool = False: The plotReference token defines if hidden reference field text should be plotted

plotValue: bool = False: The plotValue token defines if hidden value field text should be plotted

plotInvisibleText: bool = False: The plotInvisibleText token defines if hidden text other than the reference and value fields should be plotted

sketchPadsOnFab: bool = False: The sketchPadsOnFab token defines if pads should be plotted in the outline (sketch) mode

subtractMaskFromSilk: bool = False: The subtractMaskFromSilk token defines if the solder mask layers should be subtracted from the silk screen layers for gerber plots

outputFormat: int = 0: The outputFormat token defines the last plot type. The following values are defined: - 0: gerber - 1: PostScript - 2: SVG - 3: DXF - 4: HPGL - 5: PDF

mirror: bool = False: The mirror token defines if the plot should be mirrored

drillShape: int = 0: The drillShape token defines the type of drill marks used for drill files

scaleSelection: int = 1: The scaleSelection is not documented yet (as of 20.02.2022)

outputDirectory: str = '': The drillShape token defines the path relative to the current project path where the plot files will be saved

classmethod from_sexpr(exp: list) → PlotSettings

Convert the given S-Expresstion into a PlotSettings object

Args:

exp (list): Part of parsed S-Expression (pcbplotparams ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not pcbplotparams

Returns:

PlotSettings: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.SetupData(stackup: Stackup | None = None, packToMaskClearance: float = 0.0, solderMaskMinWidth: float | None = None, padToPasteClearance: float | None = None, padToPasteClearanceRatio: float | None = None, auxAxisOrigin: Position | None = None, gridOrigin: Position | None = None, plotSettings: PlotSettings | None = None)

Bases: object

The setup token is used to store the current settings such as default item sizes and other options used by the board

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_setup_section

stackup: Stackup | None = None: The optional stackup define the parameters required to manufacture the board

packToMaskClearance: float = 0.0: The packToMaskClearance token defines the clearance between footprint pads and the solder mask

solderMaskMinWidth: float | None = None: The optional solderMaskMinWidth defines the minimum solder mask width. If not defined, the minimum width is zero.

padToPasteClearance: float | None = None: The optional padToPasteClearance defines the clearance between footprint pads and the solder paste layer. If not defined, the clearance is zero

padToPasteClearanceRatio: float | None = None: The optional padToPasteClearanceRatio is the percentage (from 0 to 100) of the footprint pad to make the solder paste. If not defined, the ratio is 100% (the same size as the pad).

auxAxisOrigin: Position | None = None: The optional auxAxisOrigin defines the auxiliary origin if it is set to anything other than (0,0).

gridOrigin: Position | None = None: The optional gridOrigin defines the grid original if it is set to anything other than (0,0).

plotSettings: PlotSettings | None = None: The optional plotSettings define how the board was last plotted.

classmethod from_sexpr(exp: list) → SetupData

Convert the given S-Expresstion into a SetupData object

Args:

exp (list): Part of parsed S-Expression (setup ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not setup

Returns:

SetupData: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.Segment(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, width: float = 0.1, layer: str = 'F.Cu', locked: bool = False, net: int = 0, tstamp: str = '')

Bases: object

The segment token defines a track segment in a KiCad board

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_track_segment

start: Position: The start token defines the coordinates of the beginning of the line

end: Position: The end token defines the coordinates of the end of the line

width: float = 0.1: The width token defines the line width

layer: str = 'F.Cu': The layer token defines the canonical layer the track segment resides on

locked: bool = False: The locked token defines if the line cannot be edited

net: int = 0: The net token defines by the net ordinal number which net in the net section that the segment is part of

tstamp: str = '': The tstamp token defines the unique identifier of the line object

classmethod from_sexpr(exp: list) → Segment

Convert the given S-Expresstion into a Segment object

Args:

exp (list): Part of parsed S-Expression (segment ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not segment

Returns:

Segment: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.Via(type: str | None = None, locked: bool = False, position: ~kiutils.items.common.Position = <factory>, size: float = 0.0, drill: float = 0.0, layers: ~typing.List[str] = <factory>, removeUnusedLayers: bool = False, keepEndLayers: bool = False, free: bool = False, net: int = 0, tstamp: str | None = None)

Bases: object

The via token defines a track via in a KiCad board

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_track_via

type: str | None = None: The optional type attribute specifies the via type. Valid via types are blind and micro. If no type is defined, the via is a through hole type

locked: bool = False: The locked token defines if the line cannot be edited

position: Position: The position token define the coordinates of the center of the via

size: float = 0.0: The size token define the diameter of the via annular ring

drill: float = 0.0: The drill token define the drill diameter of the via

layers: List[str]: The layers token define the canonical layer set the via connects as a list of strings

removeUnusedLayers: bool = False: The removeUnusedLayers token is undocumented (as of 20.02.2022)

keepEndLayers: bool = False: The keepEndLayers token is undocumented (as of 20.02.2022)

free: bool = False: The free token indicates that the via is free to be moved outside it’s assigned net

net: int = 0: The net token defines by net ordinal number which net in the net section that the via is part of

tstamp: str | None = None: The tstamp token defines the unique identifier of the via

classmethod from_sexpr(exp: list) → Via

Convert the given S-Expresstion into a Via object

Args:

exp (list): Part of parsed S-Expression (via ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not via

Returns:

Via: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.Arc(start: ~kiutils.items.common.Position = <factory>, mid: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, width: float = 0.2, layer: str = 'F.Cu', locked: bool = False, net: int = 0, tstamp: str | None = None)

Bases: object

The arc token defines a track arc, which will be generated when using the length-matching feature on differential pairs.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/#_track_arc

start: Position: The start token defines the coordinates of the beginning of the arc

mid: Position: The mid token defines the coordinates of the mid point of the radius of the arc

end: Position: The end token defines the coordinates of the end of the arc

width: float = 0.2: The width token defines the line width of the arc. Defaults to 0,2.

layer: str = 'F.Cu': The layer token defiens the canonical layer the track arc resides on. Defaults to F.Cu.

locked: bool = False: The locked token defines if the arc cannot be edited. Defaults to False.

net: int = 0: The net token defines the net ordinal number which net in the net section that arc is part of. Defaults to 0.

tstamp: str | None = None: The optional tstamp token defines the unique identifier of the arc

classmethod from_sexpr(exp: list) → Arc

Convert the given S-Expresstion into a Arc object

Args:

exp (list): Part of parsed S-Expression (arc ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not arc

Returns:

Arc: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.brditems.Target(type: str = 'plus', position: ~kiutils.items.common.Position = <factory>, size: float = 0, width: float = 0.1, layer: str = 'F.Cu', tstamp: str | None = None)

Bases: object

The target token defines a target marker on the PCB

Documentation:: Not found in KiCad docu - 15.06.2022

type: str = 'plus': The type token specifies the shape of the marker. Valid types are plus and x.

position: Position: The position token specifies the position of the target marker

size: float = 0: The size token sets the marker’s size

width: float = 0.1: The width token sets the marker’s line width

layer: str = 'F.Cu': The layer token sets the canonical layer where the target marker resides

tstamp: str | None = None: The tstamp token defines the unique identifier of the target

classmethod from_sexpr(exp: list) → Target

Convert the given S-Expresstion into a Target object

Args:

exp (list): Part of parsed S-Expression (target ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not target

Returns:

Target: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

Common items (kiutils.items.common)

Defines all syntax that is shared across the symbol library, footprint library,

schematic, board and work sheet file formats.

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

02.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_common_syntax

class kiutils.items.common.Position(X: float = 0.0, Y: float = 0.0, angle: float | None = None, unlocked: bool = False)

Bases: object

The position token defines the positional coordinates and rotation of an object.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_position_identifier

X: float = 0.0: The X attribute defines the horizontal position of the object

Y: float = 0.0: The Y attribute defines the vertical position of the object

angle: float | None = None: The optional angle attribute defines the rotational angle of the object. Not all objects have rotational position definitions. Symbol text angles are stored in tenths of a degree. All other angles are stored in degrees.

unlocked: bool = False: The unlocked token’s description has to be defined yet ..

classmethod from_sexpr(exp: list) → Position

Convert the given S-Expresstion into a Position object

Args:

exp (list): Part of parsed S-Expression (xxx ...)

Raises:

Exception: When the given expression is not of type list or the list is less than
3 items long

Returns:

Position: Object of the class initialized with the given S-Expression

to_sexpr() → str: This object does not have a direct S-Expression representation.

class kiutils.items.common.Coordinate(X: float = 0.0, Y: float = 0.0, Z: float = 0.0)

Bases: object

The coordinate token defines a three-dimentional position

X: float = 0.0: The X token defines the position of the object on the x-axis

Y: float = 0.0: The Y token defines the position of the object on the y-axis

Z: float = 0.0: The Z token defines the position of the object on the z-axis

classmethod from_sexpr(exp: list) → Coordinate

Convert the given S-Expresstion into a Coordinate object

Args:

exp (list): Part of parsed S-Expression (xyz ...)

Raises:

Exception: When given parameter’s type is not a list or the list is not 4 items long
Exception: When the first item of the list is not xyz

Returns:

Coordinate: Object of the class initialized with the given S-Expression

to_sexpr(indent=0, newline=False) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.common.ColorRGBA(R: int = 0, G: int = 0, B: int = 0, A: int = 0, precision: int | None = None)

Bases: object

The color token defines a RGBA color

R: int = 0: The R token defines the red channel of the color

G: int = 0: The G token defines the green channel of the color

B: int = 0: The B token defines the blue channel of the color

A: int = 0: The A token defines the alpha channel of the color

precision: int | None = None: Wether the output of to_sexpr() should have a set number of precision after the decimal point of the self.A attribute

classmethod from_sexpr(exp: list) → ColorRGBA

Convert the given S-Expresstion into a ColorRGBA object

Args:

exp (list): Part of parsed S-Expression (color ...)

Raises:

Exception: When given parameter’s type is not a list or the list is not 5 items long
Exception: When the first item of the list is not color

Returns:

ColorRGBA: Object of the class initialized with the given S-Expression

to_sexpr(indent=0, newline=False) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.common.Stroke(width: float = 0.0, type: str | None = None, color: ColorRGBA | None = None)

Bases: object

The stroke token defines how the outlines of graphical objects are drawn.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_stroke_definition

width: float = 0.0: The width token attribute defines the line width of the graphic object

type: str | None = None: The optional type token attribute defines the line style of the graphic object. Valid stroke line styles are: - dash, dash_dot, dash_dot_dot (since KiCad v7), dot, default, solid

color: ColorRGBA | None = None: The color token attributes define the line red, green, blue, and alpha color settings. Defaults to None and was made optional since KiCad 7.

classmethod from_sexpr(exp: list) → Stroke

Convert the given S-Expresstion into a Stroke object

Args:

exp (list): Part of parsed S-Expression (stroke ...)

Raises:

Exception: When given parameter’s type is not a list or the list is not 4 items long
Exception: When the first item of the list is not stroke

Returns:

Stroke: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.Font(face: str | None = None, height: float = 1.0, width: float = 1.0, thickness: float | None = None, bold: bool = False, italic: bool = False, lineSpacing: float | None = None, color: ColorRGBA | None = None)

Bases: object

The font token attributes define how text is shown.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_text_effects

face: str | None = None: The optional ‘face’ token indicates the font family. It should be a TrueType font family name or “KiCad Font” for the KiCad stroke font. (Kicad version 7)

height: float = 1.0: The ‘height’ token attributes define the font’s height

width: float = 1.0: The ‘width’ token attributes define the font’s width

thickness: float | None = None: The ‘thickness’ token attribute defines the line thickness of the font

bold: bool = False: The ‘bold’ token specifies if the font should be bold

italic: bool = False: The ‘italic’ token specifies if the font should be italicized

lineSpacing: float | None = None: The ‘line_spacing’ token specifies the spacing between lines as a ratio of standard line-spacing. (Not yet supported)

color: ColorRGBA | None = None

The optional color token specifies the color of the text element

Available since KiCad v7

classmethod from_sexpr(exp: list) → Font

Convert the given S-Expresstion into a Font object

Args:

exp (list): Part of parsed S-Expression (font ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not font

Returns:

Font: Object of the class initialized with the given S-Expression

to_sexpr(indent=0, newline=False) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.common.Justify(horizontally: str | None = None, vertically: str | None = None, mirror: bool = False)

Bases: object

The justify token defines the justification of a text object

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_text_effects

horizontally: str | None = None: The horizontally token sets the horizontal justification. Valid values are right or left

vertically: str | None = None: The vertically token sets the vertical justification. Valid values are top or bottom

mirror: bool = False: The mirror token defines if the text is mirrored or not

classmethod from_sexpr(exp: list) → Justify

Convert the given S-Expresstion into a Justify object

Args:

exp (list): Part of parsed S-Expression (justify ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not justify

Returns:

Justify: Object of the class initialized with the given S-Expression

to_sexpr(indent=0, newline=False) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object or an empty string (depending on given indentation and newline settings) if no justification is given. This will cause the text to be horizontally and vertically aligend

class kiutils.items.common.Effects(font: ~kiutils.items.common.Font = <factory>, justify: ~kiutils.items.common.Justify = <factory>, hide: bool = False, href: str | None = None)

Bases: object

All text objects can have an optional effects section that defines how the text is displayed.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_text_effects

font: Font: The font token defines how the text is shown

justify: Justify: The justify token defines the justification of the text

hide: bool = False: The optional hide token defines if the text is hidden

href: str | None = None

The optional href token specifies a link that the text element represents.

Available since KiCad v7

classmethod from_sexpr(exp: list) → Effects

Convert the given S-Expresstion into a Effects object

Args:

exp (list): Part of parsed S-Expression (effects ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not effects

Returns:

Effects: Object of the class initialized with the given S-Expression

to_sexpr(indent=0, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.Net(number: int = 0, name: str = '')

Bases: object

The net token defines the number and name of a net

number: int = 0: The number token defines the integer number of the net

name: str = '': The name token defines the name of the net

classmethod from_sexpr(exp: list) → Net

Convert the given S-Expresstion into a Net object

Args:

exp (list): Part of parsed S-Expression (net ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not net

Returns:

Net: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 0, newline: bool = False) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.common.Group(name: str = '', locked: bool = False, id: str = '', members: ~typing.List[str] = <factory>)

Bases: object

The group token defines a group of items.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_group

name: str = '': The name attribute defines the name of the group

locked: bool = False: The locked token defines if the group may be moved or not

id: str = '': The id token attribute defines the unique identifier of the group

members: List[str]: The members token attributes define a list of unique identifiers of the objects belonging to the group

classmethod from_sexpr(exp: list) → Group

Convert the given S-Expresstion into a Group object

Args:

exp (list): Part of parsed S-Expression (group ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not group

Returns:

Group: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.PageSettings(paperSize: str = 'A4', width: float | None = None, height: float | None = None, portrait: bool = False)

Bases: object

The paper token defines the drawing page size and orientation.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_page_settings

paperSize: str = 'A4': The paperSize token defines the size of the paper. Valid sizes are A0, A1, A2, A3, A4, A5, A, B, C, D and E. When using user-defines page sizes, set this to User

width: float | None = None: The width token sets the width of a user-defines page size

height: float | None = None: The height token sets the height of a user-defines page size

portrait: bool = False: The portrait token defines if the page is in portrait or landscape mode

classmethod from_sexpr(exp: list) → PageSettings

Convert the given S-Expresstion into a PageSettings object

Args:

exp (list): Part of parsed S-Expression (paper ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not paper
Exception: When the paper type is set to User and the list’s length is not 4

Returns:

PageSettings: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Raises:

Exception: When paper size is set to User and width or height is not specified

Returns:

str: S-Expression of this object

class kiutils.items.common.TitleBlock(title: str | None = None, date: str | None = None, revision: str | None = None, company: str | None = None, comments: ~typing.Dict[int, str] = <factory>)

Bases: object

The title_block token defines the contents of the title block.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/#_title_block

title: str | None = None: The optional title token attribute is a quoted string that defines the document title

date: str | None = None: The optional date token attribute is a quoted string that defines the document date using the YYYY-MM-DD format

revision: str | None = None: The optional revision token attribute is a quoted string that defines the document revision

company: str | None = None: The optional company token attribute is a quoted string that defines the document company name

comments: Dict[int, str]: The comments token attributes define a dictionary of document comments where the key is a number from 1 to 9 and the value is a comment string

classmethod from_sexpr(exp: list) → TitleBlock

Convert the given S-Expresstion into a TitleBlock object

Args:

exp (list): Part of parsed S-Expression (title_block ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not title_block

Returns:

TitleBlock: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.Property(key: str = '', value: str = '', id: int | None = None, position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects | None = None, showName: bool = False)

Bases: object

The property token defines a symbol property when used inside a symbol definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_property

key: str = '': The key string defines the name of the property and must be unique

value: str = '': The value string defines the value of the property

id: int | None = None

The id token defines an integer ID for the property and must be unique.

Optional since KiCad v7, but required in older versions

position: Position: The position defines the X and Y coordinates as well as the rotation angle of the property. All three items will initially be set to zero.

effects: Effects | None = None: The optional effects section defines how the text is displayed

showName: bool = False

The show_name token defines if the property name is visibly shown. Used for netclass labels.

Available since KiCad v7

classmethod from_sexpr(exp: list) → Property

Convert the given S-Expresstion into a Property object

Args:

exp (list): Part of parsed S-Expression (property ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not property

Returns:

Property: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.RenderCachePolygon(pts: ~typing.List[~kiutils.items.common.Position] = <factory>)

Bases: object

A polygon used by the render_cache token

Used since KiCad v7

pts: List[Position]: The pts token defines a list of points that define the outlines of the polygon

classmethod from_sexpr(exp: list) → RenderCachePolygon

Convert the given S-Expresstion into a RenderCachePolygon object

Args:

exp (list): Part of parsed S-Expression (polygon ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not polygon

Returns:

RenderCachePolygon: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.RenderCache(text: str = '', id: int = 0, polygons: ~typing.List[~kiutils.items.common.Position] = <factory>)

Bases: object

The render_cache token defines a cache for none-standard fonts.

Used since KiCad v7

Documentation:

None found (05.03.2023), seems to be used in ‘’text_box’’ tokens for custom fonts

text: str = '': The text token defines which text the cache represents. Defaults to an empty string.

id: int = 0: The id token is some number after the text. Defaults to 0.

polygons: List[Position]: The polygons token is a list of polygons that define the outline of the cached text

classmethod from_sexpr(exp: list) → RenderCache

Convert the given S-Expresstion into a RenderCache object

Args:

exp (list): Part of parsed S-Expression (render_cache ...)

Raises:

Exception: When given parameter’s type is not a list or the list is smaller than 3
Exception: When the first item of the list is not render_cache

Returns:

RenderCache: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.Fill(type: str = 'none', color: ColorRGBA | None = None)

Bases: object

The fill token defines how schematic and symbol graphical items are filled

Documentation:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_fill_definition

type: str = 'none': The type attribute defines how the graphical item is filled. Defaults to None. Possible values are: - none: Graphic is not filled - outline: Graphic item filled with the line color - background: Graphic item filled with the theme background color

color: ColorRGBA | None = None

The optional color token defines the color of the filled item.

Available since KiCad v7

classmethod from_sexpr(exp: list) → Fill

Convert the given S-Expresstion into a Fill object

Args:

exp (list): Part of parsed S-Expression (fill ...)

Raises:

Exception: When given parameter’s type is not a list or the list is smaller than 3
Exception: When the first item of the list is not fill

Returns:

Fill: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.Image(position: ~kiutils.items.common.Position = <factory>, scale: float | None = None, data: ~typing.List[str] = <factory>, uuid: str | None = None, layer: str | None = None)

Bases: object

The image token defines an image embedded into the file

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_image_section

position: Position: The position defines the X and Y coordinates of the image

scale: float | None = None: The optional scale token attribute defines the scale factor (size) of the image

data: List[str]: The data token attribute defines the image data in the portable network graphics format (PNG) encoded with MIME type base64 as a list of strings

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

layer: str | None = None: The optional layer token defines the canonical layer name when the image is used inside a footprint or PCB. When used inside a schematic, this token is required to be None.

classmethod from_sexpr(exp: list) → Image

Convert the given S-Expresstion into a Image object

Args:

exp (list): Part of parsed S-Expression (image ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not image

Returns:

Image: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.common.ProjectInstance(name: str = '')

Bases: ABC

The instances token defines a project instance and serves as an abstract base class for symbol and hierarchical sheet project instances.

Available since KiCad v7.

name: str = '': The name token defines the name of the project instance

abstract from_sexpr(exp: list) → ProjectInstance

abstract to_sexpr(indent=2, newline=True) → str

Dimensions (kiutils.items.dimension)

The dimensions are used to mark spots in the board file for their dimensions (units, metric, imperial, etc)

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

14.06.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_dimension

class kiutils.items.dimensions.DimensionFormat(prefix: str | None = None, suffix: str | None = None, units: int = 3, unitsFormat: int = 1, precision: int = 4, overrideValue: str | None = None, suppressZeroes: bool = False)

Bases: object

The format token defines the text formatting of a dimension

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_dimension_format

prefix: str | None = None: The optional prefix token defines the string to add to the beginning of the dimension text

suffix: str | None = None: The optional suffix token defines the string to add to the end of the dimension text

units: int = 3: The units token defines the dimension units used to display the dimension text. Valid units are as follows: - 0: Inches - 1: Mils - 2: Millimeters - 3: Automatic

unitsFormat: int = 1: The unitsFormat token defines how the unit’s suffix is formatted. Valid units formats are as follows: - 0: No suffix - 1: Bare suffix - 2: Wrap suffix in parenthesis

precision: int = 4: The precision token defines the number of significant digits to display

overrideValue: str | None = None: The optional overrideValue token defines the text to substitute for the actual physical dimension

suppressZeroes: bool = False: The suppressZeroes token removes all trailing zeros from the dimension text

classmethod from_sexpr(exp: list) → DimensionFormat

Convert the given S-Expresstion into a DimensionFormat object

Args:

exp (list): Part of parsed S-Expression (format ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not format

Returns:

DimensionFormat: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.dimensions.DimensionStyle(thickness: float = 0.0, arrowLength: float = 0.0, textPositionMode: int = 0, extensionHeight: float | None = None, textFrame: int | None = None, extensionOffset: float | None = None, keepTextAligned: bool = False)

Bases: object

The style token defines the style of a dimension

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_dimension_style

thickness: float = 0.0: The thickness token defines the line thickness of the dimension

arrowLength: float = 0.0: The arrowLength token defines the length of the dimension arrows

textPositionMode: int = 0: The textPositionMode token defines the position mode of the dimension text. Valid position modes are as follows: - 0: Text is outside the dimension line - 1: Text is in line with the dimension line - 2: Text has been manually placed by the user

extensionHeight: float | None = None: The optional extensionHeight token defines the length of the extension lines past the dimension crossbar

textFrame: int | None = None: The optional textFrame token defines the style of the frame around the dimension text. This only applies to leader dimensions. Valid text frames are as follows: - 0: No text frame - 1: Rectangle - 2: Circle - 3:Rounded rectangle

extensionOffset: float | None = None: The optional extensionOffset token defines the distance from feature points to extension line start

keepTextAligned: bool = False: The keepTextAligned token indicates that the dimension text should be kept in line with the dimension crossbar. When false, the dimension text is shown horizontally regardless of the orientation of the dimension.

classmethod from_sexpr(exp: list) → DimensionStyle

Convert the given S-Expresstion into a DimensionStyle object

Args:

exp (list): Part of parsed S-Expression (style ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not style

Returns:

DimensionStyle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.dimensions.Dimension(locked: bool = False, type: str = 'aligned', layer: str = 'F.Cu', tstamp: str | None = None, pts: ~typing.List[~kiutils.items.common.Position] = <factory>, height: float | None = None, orientation: float | None = None, leaderLength: float | None = None, grText: ~kiutils.items.gritems.GrText | None = None, format: ~kiutils.items.dimensions.DimensionFormat | None = None, style: ~kiutils.items.dimensions.DimensionStyle = <factory>)

Bases: object

The dimension token defines a dimension in the PCB

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_dimension

locked: bool = False: The optional locked token specifies if the dimension can be moved

type: str = 'aligned': The type token defines the type of dimension. Valid dimension types are aligned, leader, center, orthogonal (and radial in KiCad version 7)

layer: str = 'F.Cu': The layer token defines the canonical layer the polygon resides on

tstamp: str | None = None: The tstamp token defines the unique identifier for the footprint. This only applies to footprints defined in the board file format.

pts: List[Position]: The pts token define the list of xy coordinates of the dimension

height: float | None = None: The optional height token defines the height of aligned dimensions

orientation: float | None = None: The optional orientation token defines the rotation angle for orthogonal dimensions

leaderLength: float | None = None: The optional leaderLength token attribute defines the distance from the marked radius to the knee for radial dimensions.

grText: GrText | None = None: The optional grText token define the dimension text formatting for all dimension types except center dimensions

format: DimensionFormat | None = None: The optional format token define the dimension formatting for all dimension types except center dimensions

style: DimensionStyle: The style token defines the dimension style information

classmethod from_sexpr(exp: list) → Dimension

Convert the given S-Expresstion into a Dimension object

Args:

exp (list): Part of parsed S-Expression (dimension ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not dimension

Returns:

Dimension: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Raises:

Exception: When number of coordinate points of the dimension equals 0

Returns:

str: S-Expression of this object

Footprint items (kiutils.items.fpitems)

Footprint graphical items define all of the drawing items that are used in the footprint definition. This includes text, text boxes, lines, rectangles, circles, arcs, polygons, curves and dimensions.

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

08.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_graphics_items

class kiutils.items.fpitems.FpText(type: str = 'reference', text: str = '%REF', position: ~kiutils.items.common.Position = <factory>, layer: str = 'F.Cu', hide: bool = False, effects: ~kiutils.items.common.Effects = <factory>, tstamp: str | None = None, renderCache: ~kiutils.items.common.RenderCache | None = None)

Bases: object

The fp_text token defines a graphic line in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_text

type: str = 'reference': The type attribute defines the type of text. Valid types are reference, value, and user

text: str = '%REF': The text attribute is a string that defines the text

position: Position: The position defines the X and Y position coordinates and optional orientation angle of the text

layer: str = 'F.Cu': The layer token defines the canonical layer the text resides on

hide: bool = False: The optional hide token, defines if the text is hidden

effects: Effects: The effects token defines how the text is displayed

tstamp: str | None = None: The tstamp token defines the unique identifier of the text object

renderCache: RenderCache | None = None

If the effects token prescribe a TrueType font then the optional render_cache token should be given in case the font can not be found on the current system.

Available since KiCad v7

classmethod from_sexpr(exp: list) → FpText

Convert the given S-Expresstion into a FpText object

Args:

exp (list): Part of parsed S-Expression (fp_text ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_text

Returns:

FpText: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpLine(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str = 'F.Cu', width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The fp_line token defines a graphic line in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_line

start: Position: The start token defines the coordinates of the upper left corner of the line

end: Position: The end token defines the coordinates of the low right corner of the line

layer: str = 'F.Cu': The layer token defines the canonical layer the line resides on

width: float | None = 0.12: The width token defines the line width of the line. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the line. (version 7)

locked: bool = False: The optional locked token defines if the line cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the line object

classmethod from_sexpr(exp: list) → FpLine

Convert the given S-Expresstion into a FpLine object

Args:

exp (list): Part of parsed S-Expression (fp_line ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_line

Returns:

FpLine: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpRect(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str = 'F.Cu', width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, fill: str | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The fp_rect token defines a graphic rectangle in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_rectangle

start: Position: The start token defines the coordinates of the upper left corner of the rectangle

end: Position: The end token defines the coordinates of the low right corner of the rectangle

layer: str = 'F.Cu': The layer token defines the canonical layer the rectangle resides on

width: float | None = 0.12: The width token defines the line width of the rectangle. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the rectangle. (version 7)

fill: str | None = None: The optional fill toke defines how the rectangle is filled. Valid fill types are solid and none. If not defined, the rectangle is not filled.

locked: bool = False: The optional locked token defines if the rectangle cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the rectangle object

classmethod from_sexpr(exp: list) → FpRect

Convert the given S-Expresstion into a FpRect object

Args:

exp (list): Part of parsed S-Expression (fp_rect ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_rect

Returns:

FpRect: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpTextBox(locked: bool = False, text: str = '', start: ~kiutils.items.common.Position | None = None, end: ~kiutils.items.common.Position | None = None, pts: ~typing.List[~kiutils.items.common.Position] = <factory>, angle: float | None = None, layer: str = 'F.Cu', tstamp: str | None = None, effects: ~kiutils.items.common.Effects | None = None, stroke: ~kiutils.items.common.Stroke | None = None, renderCache: ~kiutils.items.common.RenderCache | None = None)

Bases: object

The fp_text_box token defines a rectangle containing line-wrapped text.

Available since KiCad v7

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_text_box

locked: bool = False: The locked token specifies if the text box can be moved. Defaults to False.

text: str = '': The text token defines the content of the text box. Defaults to an empty string.

start: Position | None = None: The optional start token defines the top-left of a cardinally oriented text box

end: Position | None = None: The optional end token defines the bottom-right of a cardinally oriented text box

pts: List[Position]: The pts token defines the four corners of a non-cardianlly oriented text box. The corners must be in order, but the winding can be either direction.

angle: float | None = None

The optional angle token defines the rotation of the text box in degrees.

Note:

If angle is not given, or is a cardinal angle (0, 90, 180 or 270), then the text box

MUST have start and end tokens. - If angle is given and is not a cardinal angle, then the text box MUST have a pts token (with 4 pts).

layer: str = 'F.Cu': The layer token defines the canonical layer the text box resides on. Defaults to F.Cu.

tstamp: str | None = None: The optional tstamp token defines the unique identifier of the text box

effects: Effects | None = None: The optional effects token describes the style of the text in the text box

stroke: Stroke | None = None: The optional stroke token describes the style of an optional border to be drawn around the text box

renderCache: RenderCache | None = None: If the effects token prescribe a TrueType font then the optional render_cache token should be given in case the font can not be found on the current system.

classmethod from_sexpr(exp: list) → FpTextBox

Convert the given S-Expression into a FpTextBox object

Args:

exp (list): Part of parsed S-Expression (fp_text_box ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_text_box

Returns:

FpTextBox: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Raises:

Exception: When a non-cardinal angle is given and no corner points were defined using the self.pts token
Exception: When a cardinal angle or no angle is given and either start or end token is undefined

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpCircle(center: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str = 'F.Cu', width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, fill: str | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The ``fp_circle `` token defines a graphic circle in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_circle

center: Position: The center token defines the coordinates of the center of the circle

end: Position: The end token defines the coordinates of the low right corner of the circle

layer: str = 'F.Cu': The layer token defines the canonical layer the circle resides on

width: float | None = 0.12: The width token defines the line width of the circle. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the circle. (version 7)

fill: str | None = None: The optional fill toke defines how the circle is filled. Valid fill types are solid and none. If not defined, the circle is not filled.

locked: bool = False: The optional locked token defines if the circle cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the circle object

classmethod from_sexpr(exp: list) → FpCircle

Convert the given S-Expresstion into a FpCircle object

Args:

exp (list): Part of parsed S-Expression (fp_circle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_circle

Returns:

FpCircle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpArc(start: ~kiutils.items.common.Position = <factory>, mid: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str = 'F.Cu', width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The fp_arc token defines a graphic arc in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_arc

start: Position: The start token defines the coordinates of the start position of the arc radius

mid: Position: The mid token defines the coordinates of the midpoint along the arc

end: Position: The end token defines the coordinates of the end position of the arc radius

layer: str = 'F.Cu': The layer token defines the canonical layer the arc resides on

width: float | None = 0.12: The width token defines the line width of the arc. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the arc. (version 7)

locked: bool = False: The optional locked token defines if the arc cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the arc object

classmethod from_sexpr(exp: list) → FpArc

Convert the given S-Expresstion into a FpArc object

Args:

exp (list): Part of parsed S-Expression (fp_arc ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_arc

Returns:

FpArc: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpPoly(layer: str = 'F.Cu', coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>, width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, fill: str | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The fp_poly token defines a graphic polygon in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_polygon

layer: str = 'F.Cu': The layer token defines the canonical layer the polygon resides on

coordinates: List[Position]: The coordinates define the list of X/Y coordinates of the polygon outline

width: float | None = 0.12: The width token defines the line width of the polygon. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the polygon. (version 7)

fill: str | None = None: The optional fill toke defines how the polygon is filled. Valid fill types are solid and none. If not defined, the rectangle is not filled.

locked: bool = False: The optional locked token defines if the polygon cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the polygon object

classmethod from_sexpr(exp: list) → FpPoly

Convert the given S-Expresstion into a FpPoly object

Args:

exp (list): Part of parsed S-Expression (fp_poly ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_poly

Returns:

FpPoly: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the polygon, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.fpitems.FpCurve(coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>, layer: str = 'F.Cu', width: float | None = 0.12, stroke: ~kiutils.items.common.Stroke | None = None, locked: bool = False, tstamp: str | None = None)

Bases: object

The fp_curve token defines a graphic Cubic Bezier curve in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_curve

coordinates: List[Position]: The coordinates define the list of X/Y coordinates of the curve outline

layer: str = 'F.Cu': The layer token defines the canonical layer the curve resides on

width: float | None = 0.12: The width token defines the line width of the curve. (prior to version 7)

stroke: Stroke | None = None: The stroke describes the line width and style of the curve. (version 7)

locked: bool = False: The optional locked token defines if the curve cannot be edited

tstamp: str | None = None: The tstamp token defines the unique identifier of the curve object

classmethod from_sexpr(exp: list) → FpCurve

Convert the given S-Expresstion into a FpCurve object

Args:

exp (list): Part of parsed S-Expression (fp_curve ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_curve

Returns:

FpCurve: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the curve, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

Graphical items (kiutils.items.gritems)

The graphical items are footprint and board items that are outside of the connectivity items.

This includes graphical items on technical, user, and copper layers. Graphical items are also used to define complex pad geometries.

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

10.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphic_items

class kiutils.items.gritems.GrText(text: str = '', position: ~kiutils.items.common.Position = <factory>, layer: str | None = None, effects: ~kiutils.items.common.Effects = <factory>, tstamp: str | None = None, locked: bool = False, renderCache: ~kiutils.items.common.RenderCache | None = None)

Bases: object

The gr_text token defines a graphical text.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_text

text: str = '': The text attribute is a string that defines the text

position: Position: The position defines the X and Y position coordinates and optional orientation angle of the text

layer: str | None = None: The layer token defines the canonical layer the text resides on

effects: Effects: The effects token defines how the text is displayed

tstamp: str | None = None: The tstamp token defines the unique identifier of the text object

locked: bool = False: The locked token defines if the object may be moved or not

renderCache: RenderCache | None = None

If the effects token prescribe a TrueType font then the optional render_cache token should be given in case the font can not be found on the current system.

Available since KiCad v7

classmethod from_sexpr(exp: list) → GrText

Convert the given S-Expresstion into a GrText object

Args:

exp (list): Part of parsed S-Expression (gr_text ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_text

Returns:

GrText: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrTextBox(locked: bool = False, text: str = '', start: ~kiutils.items.common.Position | None = None, end: ~kiutils.items.common.Position | None = None, pts: ~typing.List[~kiutils.items.common.Position] = <factory>, angle: float | None = None, layer: str = 'F.Cu', tstamp: str | None = None, effects: ~kiutils.items.common.Effects | None = None, stroke: ~kiutils.items.common.Stroke | None = None, renderCache: ~kiutils.items.common.RenderCache | None = None)

Bases: object

The gr_text_box token defines a graphical rectangle containing line-wrapped text.

Available since KiCad v7

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_text_box

locked: bool = False: The locked token specifies if the text box can be moved. Defaults to False.

text: str = '': The text token defines the content of the text box. Defaults to an empty string.

start: Position | None = None: The optional start token defines the top-left of a cardinally oriented text box

end: Position | None = None: The optional end token defines the bottom-right of a cardinally oriented text box

pts: List[Position]: The pts token defines the four corners of a non-cardianlly oriented text box. The corners must be in order, but the winding can be either direction.

angle: float | None = None

The optional angle token defines the rotation of the text box in degrees.

Note:

If angle is not given, or is a cardinal angle (0, 90, 180 or 270), then the text box MUST have start and end tokens.
If angle is given and is not a cardinal angle, then the text box MUST have a pts token (with 4 pts).

layer: str = 'F.Cu': The layer token defines the canonical layer the text box resides on. Defaults to F.Cu.

tstamp: str | None = None: The optional tstamp token defines the unique identifier of the text box

effects: Effects | None = None: The optional effects token describes the style of the text in the text box

stroke: Stroke | None = None: The optional stroke token describes the style of an optional border to be drawn around the text box

renderCache: RenderCache | None = None

If the effects token prescribe a TrueType font then the optional render_cache token should be given in case the font can not be found on the current system.

Available since KiCad v7

classmethod from_sexpr(exp: list) → GrTextBox

Convert the given S-Expression into a GrTextBox object

Args:

exp (list): Part of parsed S-Expression (gr_text_box ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fp_text_box

Returns:

GrTextBox: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Raises:

Exception: When a non-cardinal angle is given and no corner points were defined using the self.pts token
Exception: When a cardinal angle or no angle is given and either start or end token is undefined

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrLine(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, angle: float | None = None, layer: str | None = None, width: float | None = 0.12, tstamp: str | None = None, locked: bool = False)

Bases: object

The gr_line token defines a graphical line.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_line

start: Position: The start token defines the coordinates of the start of the line

end: Position: The end token defines the coordinates of the end of the line

angle: float | None = None: The optional angle token defines the rotational angle of the line

layer: str | None = None: The layer token defines the canonical layer the rectangle resides on

width: float | None = 0.12: The width token defines the line width of the rectangle. (prior to version 7)

tstamp: str | None = None: The tstamp token defines the unique identifier of the rectangle object

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrLine

Convert the given S-Expresstion into a GrLine object

Args:

exp (list): Part of parsed S-Expression (gr_line ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_line

Returns:

GrLine: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrRect(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str | None = None, width: float | None = 0.12, fill: str | None = None, tstamp: str | None = None, locked: bool = False)

Bases: object

The gr_rect token defines a graphical rectangle.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_rectangle

start: Position: The start token defines the coordinates of the upper left corner of the rectangle

end: Position: The end token defines the coordinates of the low right corner of the rectangle

layer: str | None = None: The layer token defines the canonical layer the rectangle resides on

width: float | None = 0.12: The width token defines the line width of the rectangle. (prior to version 7)

fill: str | None = None: The optional fill toke defines how the rectangle is filled. Valid fill types are solid and none. If not defined, the rectangle is not filled

tstamp: str | None = None: The tstamp token defines the unique identifier of the rectangle object

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrRect

Convert the given S-Expresstion into a GrRect object

Args:

exp (list): Part of parsed S-Expression (gr_rect ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_rect

Returns:

GrRect: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrCircle(center: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str | None = None, width: float | None = 0.12, fill: str | None = None, tstamp: str | None = None, locked: bool = False)

Bases: object

The ``gr_circle `` token defines a graphical circle.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_circle

center: Position: The center token defines the coordinates of the center of the circle

end: Position: The end token defines the coordinates of the low right corner of the circle

layer: str | None = None: The layer token defines the canonical layer the circle resides on

width: float | None = 0.12: The width token defines the line width of the circle. (prior to version 7)

fill: str | None = None: The optional fill toke defines how the circle is filled. Valid fill types are solid and none. If not defined, the rectangle is not filled

tstamp: str | None = None: The tstamp token defines the unique identifier of the circle object

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrCircle

Convert the given S-Expresstion into a GrCircle object

Args:

exp (list): Part of parsed S-Expression (gr_circle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_circle

Returns:

GrCircle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrArc(start: ~kiutils.items.common.Position = <factory>, mid: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, layer: str | None = None, width: float | None = 0.12, tstamp: str | None = None, locked: bool = False)

Bases: object

The gr_arc token defines a graphic arc.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_arc

start: Position: The start token defines the coordinates of the start position of the arc radius

mid: Position: The mid token defines the coordinates of the midpoint along the arc

end: Position: The end token defines the coordinates of the end position of the arc radius

layer: str | None = None: The layer token defines the canonical layer the arc resides on

width: float | None = 0.12: The width token defines the line width of the arc. (prior to version 7)

tstamp: str | None = None: The tstamp token defines the unique identifier of the arc object.

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrArc

Convert the given S-Expresstion into a GrArc object

Args:

exp (list): Part of parsed S-Expression (gr_arc ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_arc

Returns:

GrArc: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrPoly(layer: str | None = None, coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>, width: float | None = 0.12, fill: str | None = None, tstamp: str | None = None, locked: bool = False)

Bases: object

The gr_poly token defines a graphic polygon in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_polygon

layer: str | None = None: The coordinates define the list of X/Y coordinates of the polygon outline

coordinates: List[Position]: The layer token defines the canonical layer the polygon resides on

width: float | None = 0.12: The width token defines the line width of the polygon. (prior to version 7)

fill: str | None = None: The optional fill toke defines how the polygon is filled. Valid fill types are solid and none. If not defined, the rectangle is not filled

tstamp: str | None = None: The tstamp token defines the unique identifier of the polygon object

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrPoly

Convert the given S-Expresstion into a GrPoly object

Args:

exp (list): Part of parsed S-Expression (gr_poly ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_poly

Returns:

GrPoly: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True, pts_newline: bool = False) → str

Generate the S-Expression representing this object. When no coordinates are set in the polygon, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.
pts_newline (bool): Adds a newline for the (pts ..) token as KiCad treats
this different in Board files than Footprint files. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.gritems.GrCurve(coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>, layer: str | None = None, width: float | None = 0.12, tstamp: str | None = None, locked: bool = False)

Bases: object

The gr_curve token defines a graphic Cubic Bezier curve in a footprint definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_graphical_curve

coordinates: List[Position]: The coordinates define the list of X/Y coordinates of the curve outline

layer: str | None = None: The layer token defines the canonical layer the curve resides on

width: float | None = 0.12: The width token defines the line width of the curve. (prior to version 7)

tstamp: str | None = None: The tstamp token defines the unique identifier of the curve object

locked: bool = False: The locked token defines if the object may be moved or not

classmethod from_sexpr(exp: list) → GrCurve

Convert the given S-Expresstion into a GrCurve object

Args:

exp (list): Part of parsed S-Expression (gr_curve ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not gr_curve

Returns:

GrCurve: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the curve, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

Schematic items (kiutils.items.schitems)

Defines items used in KiCad schematic files

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

19.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/

class kiutils.items.schitems.Junction(position: ~kiutils.items.common.Position = <factory>, diameter: float = 0, color: ~kiutils.items.common.ColorRGBA = <factory>, uuid: str | None = None)

Bases: object

The junction token defines a junction in the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_junction_section

position: Position: The position defines the X and Y coordinates of the junction

diameter: float = 0: The diameter token attribute defines the DIAMETER of the junction. A diameter of 0 is the default diameter in the system settings.

color: ColorRGBA: The color token attributes define the Red, Green, Blue, and Alpha transparency of the junction. If all four attributes are 0, the default junction color is used.

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Junction

Convert the given S-Expresstion into a Junction object

Args:

exp (list): Part of parsed S-Expression (junction ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not junction

Returns:

Junction: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.NoConnect(position: ~kiutils.items.common.Position = <factory>, uuid: str | None = None)

Bases: object

The no_connect token defines a unused pin connection in the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_no_connect_section

position: Position: The position defines the X and Y coordinates of the no connect

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → NoConnect

Convert the given S-Expresstion into a NoConnect object

Args:

exp (list): Part of parsed S-Expression (no_connect ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not no_connect

Returns:

NoConnect: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.BusEntry(position: ~kiutils.items.common.Position = <factory>, uuid: str | None = None, size: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>)

Bases: object

The bus_entry token defines a bus entry in the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_bus_entry_section

position: Position: The position defines the X and Y coordinates of the bus entry

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

size: Position: The size token attributes define the X and Y distance of the end point from the position of the bus entry

stroke: Stroke: The stroke defines how the bus entry is drawn

classmethod from_sexpr(exp: list) → BusEntry

Convert the given S-Expresstion into a BusEntry object

Args:

exp (list): Part of parsed S-Expression (bus_entry ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not bus_entry

Returns:

BusEntry: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.BusAlias(name: str = '', members: ~typing.List[str] = <factory>)

Bases: object

The bus_alias token defines a bus entry in the schematic

Documentation:: https://gitlab.com/kicad/services/kicad-dev-docs/-/merge_requests/53/diffs

name: str = '': The name of the bus.

members: List[str]: The list of members defined in the bus. Note that when you tap out a bus entry from a bus using one these members a label will be created with the selected member name

classmethod from_sexpr(exp: list) → BusAlias

Convert the given S-Expresstion into a BusAlias object

Args:

exp (list): Part of parsed S-Expression (bus_alias ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not bus_alias
Exception: When the S-Expression is not exactly three items long
Exception: When the members token is missing

Returns:

BusAlias: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.Connection(type: str = 'wire', points: ~typing.List[~kiutils.items.common.Position] = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, uuid: str | None = None)

Bases: object

The wire and bus tokens define wires and buses in the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_wire_and_bus_section

type: str = 'wire': The type token defines wether the connection is a bus or a wire

points: List[Position]: The points token defines the list of X and Y coordinates of start and end points of the wire or bus

stroke: Stroke: The stroke defines how the connection is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Connection

Convert the given S-Expresstion into a Connection object

Args:

exp (list): Part of parsed S-Expression (wire ...) or (bus ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not wire or bus

Returns:

Connection: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.PolyLine(points: ~typing.List[~kiutils.items.common.Position] = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, uuid: str | None = None)

Bases: object

The polyline token defines one or more lines that may or may not represent a polygon

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_graphical_line_section

points: List[Position]: The points token defines the list of X/Y coordinates of to draw line(s) between. A minimum of two points is required.

stroke: Stroke: The stroke defines how the graphical line is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → PolyLine

Convert the given S-Expresstion into a PolyLine object

Args:

exp (list): Part of parsed S-Expression (polyline ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not polyline

Returns:

PolyLine: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.Text(text: str = '', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None)

Bases: object

The text token defines graphical text in a schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_graphical_text_section

text: str = '': The text token defines the text string

position: Position: The position token defines the X and Y coordinates and rotation angle of the text

effects: Effects: The effects token defines how the text is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Text

Convert the given S-Expresstion into a Text object

Args:

exp (list): Part of parsed S-Expression (text ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not text

Returns:

Text: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.TextBox(text: str = '', position: ~kiutils.items.common.Position = <factory>, size: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None)

Bases: object

The text_box token defines a text box inside a schematic

Available since KiCad v7

Documentation:

text: str = '': The text token defines the text string

position: Position: The position token defines the X and Y coordinates and rotation angle of the text

size: Position: The size token defines the size in X and Y direction. Angle is not used.

stroke: Stroke: The stroke token defines the look of the outline of the text box

fill: Fill: The fill token defines how the text box should be filled

effects: Effects: The effects token defines how the text is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → TextBox

Convert the given S-Expresstion into a TextBox object

Args:

exp (list): Part of parsed S-Expression (text_box ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not text_box

Returns:

TextBox: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.LocalLabel(text: str = '', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None, fieldsAutoplaced: bool = False)

Bases: object

The label token defines an wire or bus label name in a schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#local_label_section

text: str = '': The text token defines the text in the label

position: Position: The position token defines the X and Y coordinates and rotation angle of the label

effects: Effects: The effects token defines how the label is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the global label have been place automatically

classmethod from_sexpr(exp: list) → LocalLabel

Convert the given S-Expresstion into a LocalLabel object

Args:

exp (list): Part of parsed S-Expression (label ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not label

Returns:

LocalLabel: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.GlobalLabel(text: str = '', shape: str = 'input', fieldsAutoplaced: bool = False, position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None, properties: ~typing.List[~kiutils.items.common.Property] = <factory>)

Bases: object

The global_label token defines a label name that is visible across all schematics in a design

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_global_label_section

text: str = '': The text token defines the text in the label

shape: str = 'input': The shape token defines the way the global label is drawn. Possible values are: input, output, bidirectional, tri_state, passive.

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the global label have been place automatically

position: Position: The position token defines the X and Y coordinates and rotation angle of the label

effects: Effects: The effects token defines how the label is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

properties: List[Property]: The properties token defines a list of properties of the global label. Currently, the only supported property is the inter-sheet reference

classmethod from_sexpr(exp: list) → GlobalLabel

Convert the given S-Expresstion into a GlobalLabel object

Args:

exp (list): Part of parsed S-Expression (global_label ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not global_label

Returns:

GlobalLabel: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalLabel(text: str = '', shape: str = 'input', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None, fieldsAutoplaced: bool = False)

Bases: object

The hierarchical_label token defines a label that are used by hierarchical sheets to define connections between sheet in hierarchical designs

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_label_section

text: str = '': The text token defines the text in the label

shape: str = 'input': The shape token defines the way the global label is drawn. Possible values are: input, output, bidirectional, tri_state, passive.

position: Position: The position token defines the X and Y coordinates and rotation angle of the label

effects: Effects: The effects token defines how the label is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the global label have been place automatically

classmethod from_sexpr(exp: list) → HierarchicalLabel

Convert the given S-Expresstion into a HierarchicalLabel object

Args:

exp (list): Part of parsed S-Expression (hierarchical_label ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not hierarchical_label

Returns:

HierarchicalLabel: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.SymbolProjectPath(sheetInstancePath: str = '', reference: str = '', unit: int = 1)

Bases: object

The symbol project path defines the path token to the sheet instance of the instance data of a symbol.

Available since KiCad v7.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_symbol_section

sheetInstancePath: str = '': The PATH_INSTANCE token defines the path to the symbol instance

reference: str = '': The reference token is a string that defines the reference designator for the symbol instance

unit: int = 1: The unit token is a integer that defines the symbol unit for the symbol instance. For symbols that do not define multiple units, this will always be 1.

classmethod from_sexpr(exp: list) → SymbolProjectPath

Convert the given S-Expression into a SymbolProjectPath object

Args:

exp (list): Part of parsed S-Expression (path ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not path

Returns:

SymbolProjectPath: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.SymbolProjectInstance(name: str = '', paths: ~typing.List[~kiutils.items.schitems.SymbolProjectPath] = <factory>)

Bases: ProjectInstance

The project token attribute defines the name of the project as well as a list of symbol project paths (instance data). There can be instance data from other project when schematics are shared across multiple projects. The projects will have to be sorted by the name token in alphabetical order.

Available since KiCad v7.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_symbol_section

paths: List[SymbolProjectPath]: The paths token defines a list of symbol project paths for this project instance

classmethod from_sexpr(exp: list) → SymbolProjectInstance

Convert the given S-Expression into a SymbolProjectInstance object

Args:

exp (list): Part of parsed S-Expression (project ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not project

Returns:

SymbolProjectInstance: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.SchematicSymbol(libraryNickname: str | None = None, entryName: str | None = None, libName: str | None = None, position: ~kiutils.items.common.Position = <factory>, unit: int | None = None, inBom: bool = False, onBoard: bool = False, dnp: bool | None = None, fieldsAutoplaced: bool = False, uuid: str | None = '', properties: ~typing.List[~kiutils.items.common.Property] = <factory>, pins: ~typing.Dict[str, str] = <factory>, mirror: str | None = None, instances: ~typing.List[~kiutils.items.schitems.SymbolProjectInstance] = <factory>)

Bases: object

The symbol token in the symbol section of the schematic defines an instance of a symbol from the library symbol section of the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_symbol_section

property libId: str

The lib_id token defines which symbol in the library symbol section of the schematic this schematic symbol references. In kiutils, the lib_id token is a combination of both the libraryNickname and entryName token. Setting the lib_id token will update those tokens accordingly.

Returns:

Symbol id in the following format: <libraryNickname>:<entryName> or <entryName>, if libraryNickname token is not set.

libraryNickname: str | None = None: The optional libraryNickname token defines which symbol library this symbol belongs to and is a part of the id token

entryName: str = None: The entryName token defines the actual name of the symbol and is a part of the id token

libName: str | None = None: The optional lib_name token is only set when the symbol was edited in the schematic. It may be set to <entryName>_X where X is a unique number that specifies which variation this symbol is of its original.

position: Position: The position defines the X and Y coordinates and angle of rotation of the symbol

unit: int | None = None: The optional unit token attribute defines which unit in the symbol library definition that the schematic symbol represents

inBom: bool = False: The in_bom token attribute determines whether the schematic symbol appears in any bill of materials output

onBoard: bool = False: The on_board token attribute determines if the footprint associated with the symbol is exported to the board via the netlist

dnp: bool | None = None

The optional dnp token defines if a symbol is marked as do-not-populate in the schematic.

Available since KiCad v7

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the global label have been place automatically

uuid: str | None = '': The optional uuid defines the universally unique identifier

properties: List[Property]: The properties section defines a list of symbol properties of the schematic symbol

pins: Dict[str, str]: The pins token defines a dictionary with pin numbers in form of strings as keys and uuid’s as values

mirror: str | None = None: The mirror token defines if the symbol is mirrored in the schematic. Accepted values: x or y. When mirroring around the x and y axis at the same time use some additional rotation to get the correct orientation of the symbol.

instances: List[SymbolProjectInstance]

The instances token defines a list of symbol instances grouped by project. Every symbol will have a least one instance.

Available since KiCad v7.

classmethod from_sexpr(exp: list) → SchematicSymbol

Convert the given S-Expresstion into a SchematicSymbol object

Args:

exp (list): Part of parsed S-Expression (symbol ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not symbol

Returns:

SchematicSymbol: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalPin(name: str = '', connectionType: str = 'input', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None)

Bases: object

The pin token in a sheet object defines an electrical connection between the sheet in a: schematic with the hierarchical label defined in the associated schematic file
Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_sheet_pin_definition

name: str = '': The name attribute defines the name of the sheet pin. It must have an identically named hierarchical label in the associated schematic file.

connectionType: str = 'input': The electrical connect type token defines the type of electrical connect made by the sheet pin

position: Position: The position defines the X and Y coordinates and angle of rotation of the pin

effects: Effects: The effects section defines how the pin name text is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → HierarchicalPin

Convert the given S-Expresstion into a HierarchicalPin object

Args:

exp (list): Part of parsed S-Expression (pin ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not pin

Returns:

HierarchicalPin: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalSheetProjectPath(sheetInstancePath: str = '', page: str = '')

Bases: object

The symbol project path defines the path token to the sheet instance of the instance data of a symbol.

Available since KiCad v7.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_sheet_section

sheetInstancePath: str = '': The PATH_INSTANCE token defines the path to the symbol instance

page: str = '': The page token is a string that defines the page number of the sheet instance

classmethod from_sexpr(exp: list) → HierarchicalSheetProjectPath

Convert the given S-Expression into a HierarchicalSheetProjectPath object

Args:

exp (list): Part of parsed S-Expression (path ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not path

Returns:

HierarchicalSheetProjectPath: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalSheetProjectInstance(name: str = '', paths: ~typing.List[~kiutils.items.schitems.HierarchicalSheetProjectPath] = <factory>)

Bases: ProjectInstance

The project token attribute defines the name of the project as well as a list of hierarchical sheet project paths (instance data). There can be instance data from other project when schematics are shared across multiple projects. The projects will have to be sorted by the name token in alphabetical order.

Available since KiCad v7.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_sheet_section

paths: List[HierarchicalSheetProjectPath]: The paths token defines a list of hierarchical sheet project paths for this project instance

classmethod from_sexpr(exp: list) → HierarchicalSheetProjectInstance

Convert the given S-Expression into a HierarchicalSheetProjectInstance object

Args:

exp (list): Part of parsed S-Expression (project ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not project

Returns:

HierarchicalSheetProjectInstance: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalSheet(position: ~kiutils.items.common.Position = <factory>, width: float = 0, height: float = 0, fieldsAutoplaced: bool = False, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.ColorRGBA = <factory>, uuid: str | None = None, sheetName: ~kiutils.items.common.Property = <factory>, fileName: ~kiutils.items.common.Property = <factory>, pins: ~typing.List[~kiutils.items.schitems.HierarchicalPin] = <factory>, instances: ~typing.List[~kiutils.items.schitems.HierarchicalSheetProjectInstance] = <factory>)

Bases: object

The sheet token defines a hierarchical sheet of the schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_sheet_section

position: Position: The position defines the X and Y coordinates and angle of rotation of the sheet in the schematic

width: float = 0: The width token defines the width of the sheet

height: float = 0: The height token defines the height of the sheet

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the global label have been place automatically

stroke: Stroke: The stroke defines how the sheet outline is drawn

fill: ColorRGBA: The fill defines the color how the sheet is filled

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

sheetName: Property: The sheetName is a property that defines the name of the sheet. The property’s key should therefore be set to Sheet name

fileName: Property: The fileName is a property that defines the file name of the sheet. The property’s key should therefore be set to Sheet file

pins: List[HierarchicalPin]: The pins section is a list of hierarchical pins that map a hierarchical label defined in the associated schematic file

instances: List[HierarchicalSheetProjectInstance]

The instances token defines a list of hierachical sheet instances grouped by project. Every hierarchical sheet will have a least one instance.

Available since KiCad v7.

classmethod from_sexpr(exp: list) → HierarchicalSheet

Convert the given S-Expresstion into a HierarchicalSheet object

Args:

exp (list): Part of parsed S-Expression (sheet ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not sheet

Returns:

HierarchicalSheet: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.HierarchicalSheetInstance(instancePath: str = '/', page: str = '1')

Bases: object

The sheet_instance token defines the per sheet information for the entire schematic. This: section will only exist in schematic files that are the root sheet of a project
Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_hierarchical_sheet_instance_section

instancePath: str = '/': The instancePath attribute is the path to the sheet instance

page: str = '1': The page token defines the page number of the schematic represented by the sheet instance information. Page numbers can be any valid string.

classmethod from_sexpr(exp: list) → HierarchicalSheetInstance

Convert the given S-Expresstion into a HierarchicalSheetInstance object

Args:

exp (list): Part of parsed S-Expression (path ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not path

Returns:

HierarchicalSheetInstance: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.SymbolInstance(path: str = '/', reference: str = '', unit: int = 0, value: str = '', footprint: str = '')

Bases: object

The symbol_instance token defines the per symbol information for the entire schematic

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-schematic/#_symbol_instance_section

path: str = '/': The path attribute is the path to the sheet instance

reference: str = '': The reference token attribute is a string that defines the reference designator for the symbol instance

unit: int = 0: The unit token attribute is a integer ordinal that defines the symbol unit for the symbol instance. For symbols that do not define multiple units, this will always be 1.

value: str = '': The value token attribute is a string that defines the value field for the symbol instance

footprint: str = '': The footprint token attribute is a string that defines the LIBRARY_IDENTIFIER for footprint associated with the symbol instance

classmethod from_sexpr(exp: list) → SymbolInstance

Convert the given S-Expresstion into a SymbolInstance object

Args:

exp (list): Part of parsed S-Expression (path ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not path

Returns:

SymbolInstance: Object of the class initialized with the given S-Expression

to_sexpr(indent=4, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.Rectangle(start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>, uuid: str | None = None)

Bases: object

The rectangle token defines a graphical rectangle in a schematic.

Available since KiCad v7

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_rectangle

start: Position: The start token attributes define the coordinates of the start point of the rectangle

end: Position: The end token attributes define the coordinates of the end point of the rectangle

stroke: Stroke: The stroke defines how the rectangle outline is drawn

fill: Fill: The fill token attributes define how rectangle arc is filled

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Rectangle

Convert the given S-Expresstion into a Rectangle object

Args:

exp (list): Part of parsed S-Expression (rectangle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not rectangle

Returns:

Rectangle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.Arc(start: ~kiutils.items.common.Position = <factory>, mid: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>, uuid: str | None = None)

Bases: object

The Arc token defines a graphical arc in a schematic.

Available since KiCad v7

Documentation:

???

start: Position: The start token attributes define the coordinates of the start point of the arc

mid: Position: The end token attributes define the coordinates of the mid point of the arc

end: Position: The end token attributes define the coordinates of the end point of the arc

stroke: Stroke: The stroke defines how the arc outline is drawn

fill: Fill: The fill token attributes define how the arc is filled

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Arc

Convert the given S-Expresstion into a Arc object

Args:

exp (list): Part of parsed S-Expression (arc ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not arc

Returns:

Arc: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.Circle(center: ~kiutils.items.common.Position = <factory>, radius: float = 0.0, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>, uuid: str | None = None)

Bases: object

The Circle token defines a graphical circle in a schematic.

Available since KiCad v7

Documentation:

???

center: Position: The center token attributes define the coordinates of the center point of the circle

radius: float = 0.0: The radius token attributes define the radius of the circle

stroke: Stroke: The stroke defines how the circle outline is drawn

fill: Fill: The fill token attributes define how the circle is filled

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → Circle

Convert the given S-Expresstion into a Circle object

Args:

exp (list): Part of parsed S-Expression (circle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not circle

Returns:

Circle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.schitems.NetclassFlag(text: str = '', length: float = 2.54, shape: str = 'round', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>, properties: ~typing.List[~kiutils.items.common.Property] = <factory>, uuid: str | None = None, fieldsAutoplaced: bool = False)

Bases: object

The netclass_flag token defines a netclass flag in a schematic.

Available since KiCad v7

Documentation:

???

text: str = '': The text token defines the text the netclass flag

length: float = 2.54: The length token defines the length of the netclass flag

shape: str = 'round': The shape token defines the shape of the netclass flag. Valid values are round, rectangle, dot or``diamond``.

position: Position: The position token defines the position and rotation of the netclass flag

effects: Effects: The effects token defines how the text is drawn

properties: List[Property]: The properties token defines a list of properties the netclass is assigned to

uuid: str | None = None: The optional uuid defines the universally unique identifier

fieldsAutoplaced: bool = False: The fields_autoplaced is a flag that indicates that any PROPERTIES associated with the netclas flag have been place automatically

classmethod from_sexpr(exp: list) → NetclassFlag

Convert the given S-Expresstion into a Circle object

Args:

exp (list): Part of parsed S-Expression (netclass_flag ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not netclass_flag

Returns:

NetclassFlag: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

Symbol items (kiutils.items.syitems)

Symbol graphical items define all of the drawing items that are used in the symbol definition. This includes text, text boxes, lines, rectangles, circles, arcs, polygons and curves.

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

16.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_graphic_items

class kiutils.items.syitems.SyArc(private: bool = False, start: ~kiutils.items.common.Position = <factory>, mid: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>)

Bases: object

The arc token defines a graphical arc in a symbol definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_arc

private: bool = False

The private token defines if the arc is only visible in the symbol editor. Defaults to False.

Available since KiCad v7

start: Position: The start token defines the coordinates of start point of the arc

mid: Position: The mid token defines the coordinates of mid point of the arc

end: Position: The end token defines the coordinates of end point of the arc

stroke: Stroke: The stroke defines how the arc outline is drawn

fill: Fill: The fill token attributes define how the arc is filled

classmethod from_sexpr(exp: list) → SyArc

Convert the given S-Expresstion into a SyArc object

Args:

exp (list): Part of parsed S-Expression (arc ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not arc

Returns:

SyArc: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyCircle(private: bool = False, center: ~kiutils.items.common.Position = <factory>, radius: float = 0.0, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>)

Bases: object

The circle token defines a graphical circle in a symbol definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_circle

private: bool = False

The private token defines if the circle is only visible in the symbol editor. Defaults to False.

Available since KiCad v7

center: Position: The center token defines the coordinates of center point of the circle

radius: float = 0.0: The radius token defines the length of the radius of the circle

stroke: Stroke: The stroke defines how the circle outline is drawn

fill: Fill: The fill token attributes define how the circle is filled

classmethod from_sexpr(exp: list) → SyCircle

Convert the given S-Expresstion into a SyCircle object

Args:

exp (list): Part of parsed S-Expression (circle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not circle

Returns:

SyCircle: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyCurve(points: ~typing.List[~kiutils.items.common.Position] = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>)

Bases: object

The curve token defines a graphical Qubic Bezier curve.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_curve

points: List[Position]: The points token defines the four X/Y coordinates of each point of the curve

stroke: Stroke: The stroke defines how the curve outline is drawn

fill: Fill: The fill token attributes define how curve arc is filled

classmethod from_sexpr(exp: list) → SyCurve

Convert the given S-Expresstion into a SyCurve object

Args:

exp (list): Part of parsed S-Expression (curve ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not curve

Returns:

SyCurve: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyPolyLine(points: ~typing.List[~kiutils.items.common.Position] = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>)

Bases: object

The polyline token defines one or more graphical lines that may or may not define a polygon.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_line

points: List[Position]: The points token defines the four X/Y coordinates of each point of the polyline

stroke: Stroke: The stroke defines how the polyline outline is drawn

fill: Fill: The fill token attributes define how polyline arc is filled

classmethod from_sexpr(exp: list) → SyPolyLine

Convert the given S-Expresstion into a SyPolyLine object

Args:

exp (list): Part of parsed S-Expression (polyline ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not polyline

Returns:

SyPolyLine: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyRect(private: bool = False, start: ~kiutils.items.common.Position = <factory>, end: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>)

Bases: object

The rectangle token defines a graphical rectangle in a symbol definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_rectangle

private: bool = False

The private token defines if the rectangle is only visible in the symbol editor. Defaults to False.

Available since KiCad v7

start: Position: The start token attributes define the coordinates of the start point of the rectangle

end: Position: The end token attributes define the coordinates of the end point of the rectangle

stroke: Stroke: The stroke defines how the rectangle outline is drawn

fill: Fill: The fill token attributes define how rectangle arc is filled

classmethod from_sexpr(exp: list) → SyRect

Convert the given S-Expresstion into a SyRect object

Args:

exp (list): Part of parsed S-Expression (rectangle ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not rectangle

Returns:

SyRect: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyText(text: str = '', position: ~kiutils.items.common.Position = <factory>, effects: ~kiutils.items.common.Effects = <factory>)

Bases: object

The text token defines a graphical text in a symbol definition.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_text

text: str = '': The text attribute is a quoted string that defines the text

position: Position: The position defines the X and Y coordinates and rotation angle of the text

effects: Effects: The effects token defines how the text is displayed

classmethod from_sexpr(exp: list) → SyText

Convert the given S-Expresstion into a SyText object

Args:

exp (list): Part of parsed S-Expression (text ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not text

Returns:

SyText: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 6, newline: bool = True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 6.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

class kiutils.items.syitems.SyTextBox(text: str = '', private: bool = False, position: ~kiutils.items.common.Position = <factory>, size: ~kiutils.items.common.Position = <factory>, stroke: ~kiutils.items.common.Stroke = <factory>, fill: ~kiutils.items.common.Fill = <factory>, effects: ~kiutils.items.common.Effects = <factory>, uuid: str | None = None)

Bases: object

The text_box token defines a text box inside a symbol

Available since KiCad v7

Documentation:

text: str = '': The text token defines the text string

private: bool = False: The private token defines if the text box is only visible in the symbol editor. Defaults to False.

position: Position: The position token defines the X and Y coordinates and rotation angle of the text

size: Position: The size token defines the size in X and Y direction. Angle is not used.

stroke: Stroke: The stroke token defines the look of the outline of the text box

fill: Fill: The fill token defines how the text box should be filled

effects: Effects: The effects token defines how the text is drawn

uuid: str | None = None: The optional uuid defines the universally unique identifier. Defaults to None.

classmethod from_sexpr(exp: list) → SyTextBox

Convert the given S-Expresstion into a SyTextBox object

Args:

exp (list): Part of parsed S-Expression (text_box ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not text_box

Returns:

SyTextBox: Object of the class initialized with the given S-Expression

to_sexpr(indent=2, newline=True) → str

Generate the S-Expression representing this object

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object

Zone items (kiutils.items.zones)

The zone token defines a zone on the board or footprint. Zones serve two purposes in

KiCad: filled copper zones and keep out areas.

Author:

Marvin Mager - @mvnmgrx - 2022

License identifier:

GPL-3.0

Major changes:

11.02.2022 - created

Documentation taken from:

https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_footprint_graphics_items

class kiutils.items.zones.KeepoutSettings(tracks: str = 'allowed', vias: str = 'allowed', pads: str = 'allowed', copperpour: str = 'not-allowed', footprints: str = 'not-allowed')

Bases: object

The ``keepout `` token attributes define which objects should be kept out of the zone. This section only applies to keep out zones.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_zone_keep_out_settings

tracks: str = 'allowed': The tracks token attribute defines whether or not tracks should be excluded from the keep out area. Valid attributes are allowed and not_allowed.

vias: str = 'allowed': The vias token attribute defines whether or not vias should be excluded from the keep out area. Valid attributes are allowed and not_allowed.

pads: str = 'allowed': The pads token attribute defines whether or not pads should be excluded from the keep out area. Valid attributes are allowed and not_allowed.

copperpour: str = 'not-allowed': The copperpour token attribute defines whether or not copper pours should be excluded from the keep out area. Valid attributes are allowed and not_allowed.

footprints: str = 'not-allowed': The footprints token attribute defines whether or not footprints should be excluded from the keep out area. Valid attributes are allowed and not_allowed.

classmethod from_sexpr(exp: list) → KeepoutSettings

Convert the given S-Expresstion into a KeepoutSettings object

Args:

exp (list): Part of parsed S-Expression (keepout ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not keepout

Returns:

KeepoutSettings: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 0, newline: bool = False) → str

Generate the S-Expression representing this object. When no coordinates are set in the curve, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

Bases: object

The fill token attributes define how the zone is to be filled.

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_zone_fill_settings

yes: bool = False: The yes token specifies if the zone should be filled. If not specified, the zone is not filled and no additional attributes are required.

mode: str | None = None: The optional mode token attribute defines how the zone is filled. The only valid fill mode is hatched. When not defined, the fill mode is solid.

thermalGap: float | None = None: The optional thermalGap token attribute defines the distance from the zone to all pad thermal relief connections to the zone.

thermalBridgeWidth: float | None = None: The optional thermalBridgeWidth token attribute defines the spoke width for all pad thermal relief connection to the zone.

smoothingStyle: str | None = None: The optional smoothingStyle token attributes define the style of corner smoothing. Valid smoothing styles are chamfer and fillet

smoothingRadius: float | None = None: The optional smoothingRadius token attributes define the radius of corner smoothing

islandRemovalMode: int | None = None: The optional islandRemovalMode token attribute defines the island removal mode. Valid island removal modes are: - 0: Always remove islands. - 1: Never remove islands. - 2: Minimum area island to allow.

islandAreaMin: float | None = None: The optional islandAreaMin token attribute defines the minimum allowable zone island. This only valid when the remove islands mode is set to 2.

hatchThickness: float | None = None: The optional hatchThickness token attribute defines the thickness for hatched fills

hatchGap: float | None = None: The optional hatchGap token attribute defines the distance between lines for hatched fills

hatchOrientation: float | None = None: The optional hatchOrientation token attribute defines the line angle for hatched fills

hatchSmoothingLevel: int | None = None: The optional hatchSmoothingLevel token attribute defines how hatch outlines are smoothed. Valid hatch smoothing levels are: - 0: No smoothing - 1: Fillet - 2: Arc minimum - 3: Arc maximum

hatchSmoothingValue: float | None = None: The optional hatchSmoothingValue token attribute defines the ratio between the hole and the chamfer/fillet size

hatchBorderAlgorithm: int | None = None: The optional hatchBorderAlgorithm token attribute defines the if the zone line thickness is used when performing a hatch fill. Valid values for the hatch border algorithm are: - 0: Use zone minimum thickness. - 1: Use hatch thickness.

hatchMinHoleArea: float | None = None: The optional hatchMinHoleArea token attribute defines the minimum area a hatch file hole can be

classmethod from_sexpr(exp: list) → FillSettings

Convert the given S-Expresstion into a FillSettings object

Args:

exp (list): Part of parsed S-Expression (fill ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fill

Returns:

FillSettings: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 0, newline: bool = False) → str

Generate the S-Expression representing this object. When no coordinates are set in the curve, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 0.
newline (bool): Adds a newline to the end of the output. Defaults to False.

Returns:

str: S-Expression of this object

class kiutils.items.zones.ZonePolygon(coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>)

Bases: object

The polygon token defines a list of coordinates that define part of a zone

coordinates: List[Position]: The coordinates defines the list of polygon X/Y coordinates used to define the zone polygon

classmethod from_sexpr(exp: list) → ZonePolygon

Convert the given S-Expresstion into a ZonePolygon object

Args:

exp (list): Part of parsed S-Expression (polygon ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not polygon

Returns:

ZonePolygon: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the polygon, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object. If the polygon has no coordinates, an empty
expression is returned.

class kiutils.items.zones.FilledPolygon(layer: str = 'F.Cu', island: bool = False, coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>)

Bases: object

The filled_polygon token defines the polygons used to fill a zone

Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_zone_fill_polygons

layer: str = 'F.Cu': The layer token attribute defines the canonical layer the zone fill resides on

island: bool = False: The island token’s definition has to be defined ..

coordinates: List[Position]: The coordinates defines the list of polygon X/Y coordinates used to fill the zone

classmethod from_sexpr(exp: list) → FilledPolygon

Convert the given S-Expresstion into a FilledPolygon object

Args:

exp (list): Part of parsed S-Expression (filled_polygon ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not filled_polygon

Returns:

FilledPolygon: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the filled polygon, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object. If the filled polygon has no coordinates, an empty
expression is returned.

class kiutils.items.zones.FillSegments(layer: str = 'F.Cu', coordinates: ~typing.List[~kiutils.items.common.Position] = <factory>)

Bases: object

The fill_polygon token defines the segments used to fill the zone. This is only: used when loading boards prior to version 4 which filled zones with segments.
Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_zone_fill_segments

layer: str = 'F.Cu': The layer token attribute defines the canonical layer the zone fill resides on

coordinates: List[Position]: The coordinates defines the list of polygon X/Y coordinates used to fill the zone.

classmethod from_sexpr(exp: list) → FillSegments

Convert the given S-Expresstion into a FillSegments object

Args:

exp (list): Part of parsed S-Expression (fill_segments ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not fill_segments

Returns:

FillSegments: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 4, newline: bool = True) → str

Generate the S-Expression representing this object. When no coordinates are set in the curve, the resulting S-Expression will be left empty.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 4.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Returns:

str: S-Expression of this object. If the fill segments has no coordinates, an empty expression is returned.

class kiutils.items.zones.Hatch(style: str = 'none', pitch: float = 0.0)

Bases: object

Data wrapper for Zone class hatching attribute

style: str = 'none': The style token defines the style of the hatching. Valid hatch styles are none, edge and full

pitch: float = 0.0: The pitch token defines the pitch of the hatch

class kiutils.items.zones.Zone(locked: bool = False, net: int = 0, netName: str = 'unknown', layers: ~typing.List[str] = <factory>, tstamp: str | None = None, name: str | None = None, hatch: ~kiutils.items.zones.Hatch = <factory>, priority: int | None = None, connectPads: str | None = None, clearance: float = 0.254, minThickness: float = 0.254, filledAreasThickness: str | None = None, keepoutSettings: ~kiutils.items.zones.KeepoutSettings | None = None, fillSettings: ~kiutils.items.zones.FillSettings | None = None, polygons: ~typing.List[~kiutils.items.zones.ZonePolygon] = <factory>, filledPolygons: ~typing.List[~kiutils.items.zones.FilledPolygon] = <factory>, fillSegments: ~kiutils.items.zones.FillSegments | None = None)

Bases: object

The zone token defines a zone on the board or footprint. Zones serve two purposes: in KiCad: filled copper zones and keep out areas.
Documentation:: https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_zone

locked: bool = False: The locked token defines if the zone may be edited or not (Missing in KiCad docu as of 11.02.2022)

net: int = 0: The net token attribute defines by the net ordinal number which net in the nets section that the zone is part of

netName: str = 'unknown': The net_name token attribute defines the name of the net if the zone is not a keep out area. The net name attribute will be an empty string if the zone is a keep out area.

layers: List[str]: The layers token define the canonical layer set the zone connects as a list of strings. When the zone only resides on one layer, the output of self.to_sexpr() will change into (layer "xyz") instead of (layers ..) automatically.

tstamp: str | None = None: The tstamp token defines the unique identifier of the zone object

name: str | None = None: The optional name token attribute defines the name of the zone if one has been assigned

hatch: Hatch: The hatch token attributes define the zone outline display hatch style and pitch

priority: int | None = None: The optional priority attribute defines the zone priority if it is not zero

connectPads: str | None = None: The connectPads token attributes define the pad connection type and clearance. Valid pad connection types are thru_hole_only, full and no. If the pad connection type is not defined, thermal relief pad connections are used

clearance: float = 0.254: The clearance token defines the thermal relief for pad connections. The usage of this token is depending on the value of connectPads.

minThickness: float = 0.254: The minThickness token attributed defines the minimum fill width allowed in the zone

filledAreasThickness: str | None = None: The optional filledAreasThickness attribute no specifies if the zone like width is not used when determining the zone fill area. This is to maintain compatibility with older board files that included the line thickness when performing zone fills when it is not defined.

keepoutSettings: KeepoutSettings | None = None: The optional keepoutSettings section defines the keep out items if the zone defines as a keep out area

fillSettings: FillSettings | None = None: The optional fillSettings section defines how the zone is to be filled

polygons: List[ZonePolygon]: The polygon token defines a list of zone polygons that define the shape of the zone

filledPolygons: List[FilledPolygon]: The filledPolygons token defines a list of filled polygons in the zone

fillSegments: FillSegments | None = None: The optional fillSegments section defines a list of track segments used to fill the zone

classmethod from_sexpr(exp: list) → Zone

Convert the given S-Expresstion into a Zone object

Args:

exp (list): Part of parsed S-Expression (zone ...)

Raises:

Exception: When given parameter’s type is not a list
Exception: When the first item of the list is not zone

Returns:

Zone: Object of the class initialized with the given S-Expression

to_sexpr(indent: int = 2, newline: bool = True) → str

Generate the S-Expression representing this object.

Args:

indent (int): Number of whitespaces used to indent the output. Defaults to 2.
newline (bool): Adds a newline to the end of the output. Defaults to True.

Raises:

Exception: When the zone has no elements in its layer list

Returns:

str: S-Expression of this object.