Board

class kipy.board.Board(kicad: KiCadClient, document: DocumentSpecifier)

Represents an open board (.kicad_pcb) document in KiCad

add_to_selection(items)

Not yet implemented

begin_commit() → Commit

Begins a commit transaction on the board, returning a Commit object that can be used to push or drop (cancel) the commit. Each commit represents a set of changes that can be undone or redone as a single operation.

If you do not call begin_commit, any changes made to the board will be committed immediately, which will result in multiple steps being added to the undo history.

If you call begin_commit, changes made to the board will not be reflected in the editor until you call push_commit. This allows you to group multiple changes into a single undo step.

clear_selection()

Not yet implemented

property client: KiCadClient

The KiCad client used to communicate with the API server

create_items(items: Wrapper | Iterable[Wrapper]) → List[Wrapper]
property document: DocumentSpecifier

The document specifier for the board

drop_commit(commit: Commit)

Cancel a commit, discarding any changes made since the commit was opened

expand_text_variables(text: str) → str
expand_text_variables(text: List[str]) → List[str]

Expands text variables in a string or list of strings. Any text variables that do not exist will be left as-is in the output.

get_active_layer() → int
get_as_string() → str

Returns the board as a string in KiCad’s board file format

get_dimensions() → Sequence[Dimension]

Retrieves all dimension objects on the board

get_editor_appearance_settings() → BoardEditorAppearanceSettings
get_footprints() → Sequence[FootprintInstance]

Retrieves all footprints on the board

get_graphics_defaults() → Dict[int, BoardLayerGraphicsDefaults]

Retrieves the default graphics properties for each layer class on the board

get_item_bounding_box(items: BoardItem, include_text: bool = False) → Box2 | None
get_item_bounding_box(items: Sequence[BoardItem], include_text: bool = False) → List[Box2 | None]

Gets the KiCad-calculated bounding box for an item or items, returning None if the item does not exist or has no bounding box

get_items(types: int | Sequence[int]) → Sequence[Wrapper]

Retrieves items from the board, optionally filtering to a single or set of types

get_netclass_for_nets(nets: Net | Sequence[Net]) → Dict[str, NetClass]

Retrieves the net class for one or more nets on the board

get_nets(netclass_filter: str | Sequence[str] | None = None) → Sequence[Net]

Retrieves all nets on the board, optionally filtering by net class

get_pad_shapes_as_polygons(pads: Pad, layer: int = BoardLayer.BL_F_Cu) → PolygonWithHoles | None
get_pad_shapes_as_polygons(pads: Sequence[Pad], layer: int = BoardLayer.BL_F_Cu) → List[PolygonWithHoles | None]

Retrieves the polygonal shape of one or more pads on a given layer. If a pad does not exist or has no polygonal shape on the given layer, None will be returned for that pad.

get_pads() → Sequence[Pad]

Retrieves all pads on the board (note that pads belong to footprints, not the board itself)

get_project() → Project

Returns the project that this board is a part of

get_selection() → Sequence[Wrapper]

Not yet implemented

get_selection_as_string() → str

Returns the current selection as a string in KiCad’s board file format

get_shapes() → Sequence[BoardShape]

Retrieves all graphic shapes (not including tracks or text) on the board

get_stackup() → BoardStackup

Retrieves the stackup for the board

get_text() → Sequence[BoardText | BoardTextBox]

Retrieves all text objects on the board

get_title_block_info() → TitleBlockInfo

Retrieves the title block information for the board

get_tracks() → Sequence[Track | ArcTrack]

Retrieves all tracks and arc tracks on the board

get_vias() → Sequence[Via]

Retrieves all vias on the board

get_visible_layers() → Sequence[int]
get_zones() → Sequence[Zone]

Retrieves all zones (including rule areas and graphic zones) on the board

hit_test(item: Item, position: Vector2, tolerance: int = 0) → bool

Performs a hit test on a board item at a given position

interactive_move(items: KIID | Iterable[KIID])

Initiates an interactive move operation on one or more items on the board. The user will be able to move the items interactively in the KiCad editor. This is a blocking operation; this function will return immediately but future API calls will return AS_BUSY until the interactive move is complete.

property name: str

Returns the file name of the board

push_commit(commit: Commit, message: str = '')

If a commit is open, pushes the changes to the board and closes the commit. This will result in a single undo step being added to the undo history.

refill_zones(block=True, max_poll_seconds: float = 30.0, poll_interval_seconds: float = 0.5)

Refills all zones on the board. If block is True, this function will block until the refill operation is complete. If block is False, this function will return immediately, and future API calls will return AS_BUSY until the refill operation is complete.

remove_from_selection(items)

Not yet implemented

remove_items(items: BoardItem | Sequence[BoardItem])

Deletes one or more items from the board

revert()

Reverts the board to the last saved state

save()
save_as(filename: str, overwrite: bool = False, include_project: bool = True)

Saves the board to a new file.

Parameters:

  • filename – The path to save the board to

  • overwrite – If True, the file will be overwritten if it already exists

  • include_project – If True, the project will be saved along with the board

set_active_layer(layer: int)
set_editor_appearance_settings(settings: BoardEditorAppearanceSettings)
set_visible_layers(layers: Sequence[int])
update_items(items: BoardItem | Sequence[BoardItem])

Updates the properties of one or more items on the board. The items must already exist on the board, and are matched by internal UUID. All other properties of the items are updated from those passed in this call.

class kipy.board.BoardLayerGraphicsDefaults(proto: BoardLayerGraphicsDefaults | None = None)

The default properties for graphic items added on a given class of board layer

property layer: int

The layer class that these defaults apply to

property line_thickness: int
property text: TextAttributes
class kipy.board.BoardStackup(proto: BoardStackup | None = None)
property layers: List[BoardStackupLayer]

The stackup layers, in order from top to bottom of the board

class kipy.board.BoardStackupDielectricLayer(proto: BoardStackupDielectricLayer | None = None)
property layers: List[BoardStackupDielectricProperties]

Each dielectric layer may be made up of one or more sub-layers with different properties

class kipy.board.BoardStackupDielectricProperties(proto: BoardStackupDielectricProperties | None = None)
property epsilon_r: float
property loss_tangent: float
property material_name: str
property thickness: int
class kipy.board.BoardStackupLayer(proto: BoardStackupLayer | None = None)
property color: Color
property dielectric: BoardStackupDielectricLayer
property enabled: bool
property layer: int

The board layer this stackup entry corresponds to, or BL_UNDEFINED if this entry is a dielectric layer

property material_name: str
property thickness: int

The total thickness of this layer, in nanometers. If this is a dielectric layer, this thickness may be the sum of multiple sub-layers.

property type: int
property user_name: str

The name of the layer shown in the KiCad GUI, which may be a default value like “F.Cu” or may have been customized by the user. This field does not apply to dielectric layers.

Board Types

class kipy.board_types.AlignedDimension(proto: Dimension | None = None)
property end: Vector2
property extension_height: int
property height: int
property start: Vector2
class kipy.board_types.ArcTrack(proto: Arc | None = None)

Represents an arc track segment

bounding_box() → Box2
center() → Vector2 | None

Calculates the center of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The center of the arc, or None if the arc is degenerate

property end: Vector2
end_angle() → float | None
property layer: int
property mid: Vector2
property net: Net
radius() → float

Calculates the radius of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The radius of the arc, or 0 if the arc is degenerate

property start: Vector2
start_angle() → float | None
property width: int
class kipy.board_types.BoardArc(proto: BoardGraphicShape | None = None)

Represents a graphic arc (not a track) on a board or footprint

class kipy.board_types.BoardBezier(proto: BoardGraphicShape | None = None)

Represents a graphic bezier curve on a board or footprint

class kipy.board_types.BoardCircle(proto: BoardGraphicShape | None = None)

Represents a graphic circle on a board or footprint

class kipy.board_types.BoardEditorAppearanceSettings(proto: BoardEditorAppearanceSettings | None = None, proto_ref: BoardEditorAppearanceSettings | None = None)
property board_flip: int

Whether or not the board view is flipped (mirrored around the X axis)

property inactive_layer_display: int

How layers other than the active (selected) layer are displayed

property net_color_display: int

Whether to apply net and netclass colors to copper items and ratsnest lines

property ratsnest_display: int

Whether or not ratsnest lines are drawn to hidden layers

class kipy.board_types.BoardItem(proto: Message)
property id: KIID
class kipy.board_types.BoardPolygon(proto: BoardGraphicShape | None = None)

Represents a graphic polygon on a board or footprint

class kipy.board_types.BoardRectangle(proto: BoardGraphicShape | None = None)

Represents a graphic rectangle on a board or footprint

class kipy.board_types.BoardSegment(proto: BoardGraphicShape | None = None)

Represents a graphic line segment (not a track) on a board or footprint

class kipy.board_types.BoardShape(proto: BoardGraphicShape | None = None)

Represents a graphic shape on a board or footprint

property attributes: GraphicAttributes
property id: KIID
property layer: int
property locked: bool
property net: Net
class kipy.board_types.BoardText(proto: BoardText | None = None, proto_ref: BoardText | None = None)

Represents a free text object, or the text component of a field

as_text() → Text

Returns a base Text object using the same data as this BoardText

property attributes: TextAttributes
property id: KIID
property layer: int
property locked: bool
property position: Vector2
property value: str
class kipy.board_types.BoardTextBox(proto: BoardTextBox | None = None, proto_ref: BoardTextBox | None = None)

Represents a text box on a board

as_textbox() → TextBox

Returns a base TextBox object using the same data as this BoardText

property attributes: TextAttributes
property bottom_right: Vector2
property layer: int
property locked: bool
property top_left: Vector2
property value: str
class kipy.board_types.CenterDimension(proto: Dimension | None = None)
property center: Vector2
property end: Vector2
class kipy.board_types.Dimension(proto: Dimension | None = None)

Represents a dimension object on a board

property arrow_direction: int
property arrow_length: int
property extension_offset: int
property id: KIID
property keep_text_aligned: bool
property layer: int
property line_thickness: int
property locked: bool
property override_text: str
property override_text_enabled: bool
property precision: int
property prefix: str
property suffix: str
property suppress_trailing_zeroes: bool
property text: Text
property text_position: int
property unit: int
property unit_format: int
class kipy.board_types.DrillProperties(proto: DrillProperties | None = None, proto_ref: DrillProperties | None = None)
property diameter: Vector2

The drill diameter, which may also be a milled slot with different X and Y dimensions

property end_layer: int
property shape: int
property start_layer: int
class kipy.board_types.Field(proto: Field | None = None, proto_ref: Field | None = None)

Represents a footprint field

property field_id: int
property layer: int
property name: str
property text: BoardText
class kipy.board_types.Footprint(proto: Footprint | None = None, proto_ref: Footprint | None = None)

Represents a library footprint

add_item(item: Wrapper)
property id: LibraryIdentifier
property items: Sequence[Wrapper]
property pads: Sequence[Pad]

Returns all pads in the footprint

property shapes: Sequence[BoardShape]

Returns all graphic shapes in the footprint

property texts: Sequence[BoardText | BoardTextBox | Field]

Returns all fields and free text objects in the footprint library definition

class kipy.board_types.Footprint3DModel(proto: Footprint3DModel | None = None)

Represents a 3D model associated with a footprint

property filename: str
property offset: Vector3D
property opacity: float
property rotation: Vector3D
property scale: Vector3D
property visible: bool
class kipy.board_types.FootprintAttributes(proto: FootprintAttributes | None = None, proto_ref: FootprintAttributes | None = None)

The built-in attributes that a Footprint or FootprintInstance may have

property exclude_from_bill_of_materials: bool
property exclude_from_position_files: bool
property not_in_schematic: bool
class kipy.board_types.FootprintInstance(proto: FootprintInstance | None = None)

Represents a footprint instance on a board

property attributes: FootprintAttributes
property datasheet_field: Field
property definition: Footprint
property description_field: Field
property id: KIID
property layer: int

The layer on which the footprint is placed (BoardLayer.BL_F_Cu or BoardLayer.BL_B_Cu)

property locked: bool
property orientation: Angle
property position: Vector2
property reference_field: Field
property texts_and_fields: Sequence[BoardText | BoardTextBox | Field]

Returns all fields and free text objects in the footprint

property value_field: Field
class kipy.board_types.LeaderDimension(proto: Dimension | None = None)
property border_style: int
property end: Vector2
property start: Vector2
class kipy.board_types.Net(proto: Net | None = None)
property code: int
property name: str
class kipy.board_types.OrthogonalDimension(proto: Dimension | None = None)
property alignment: int
property end: Vector2
property extension_height: int
property height: int
property start: Vector2
class kipy.board_types.Pad(proto: Pad | None = None)
property id: KIID
property net: Net
property number: str
property pad_type: int
property padstack: PadStack
property position: Vector2
class kipy.board_types.PadStack(proto: PadStack | None = None, proto_ref: PadStack | None = None)
property angle: Angle
property back_outer_layers: PadStackOuterLayer
copper_layer(layer: int) → PadStackLayer | None
property copper_layers: list[PadStackLayer]
property drill: DrillProperties
property front_outer_layers: PadStackOuterLayer
is_masked(layer: int = 1) → bool

Returns true if the padstack is masked on the given copper layer, or on either layer if layer is BL_UNDEFINED.

property layers: Sequence[int]
property type: int
property unconnected_layer_removal: int
property zone_settings: ZoneConnectionSettings
class kipy.board_types.PadStackLayer(proto: PadStackLayer | None = None, proto_ref: PadStackLayer | None = None)
property chamfer_ratio: float
property chamfered_corners: ChamferedRectCorners
property corner_rounding_ratio: float
property custom_anchor_shape: int
property custom_shapes: Sequence[BoardShape]
property layer: int
property offset: Vector2
property shape: int
property size: Vector2
property trapezoid_delta: Vector2
property zone_settings: ZoneConnectionSettings
class kipy.board_types.PadStackOuterLayer(proto: PadStackOuterLayer | None = None, proto_ref: PadStackOuterLayer | None = None)
property solder_mask_mode: int
property solder_mask_settings: SolderMaskOverrides
property solder_paste_mode: int
property solder_paste_settings: SolderPasteOverrides
class kipy.board_types.RadialDimension(proto: Dimension | None = None)
property center: Vector2
property leader_length: int
property radius_point: Vector2
class kipy.board_types.SolderMaskOverrides(proto: SolderMaskOverrides | None = None, proto_ref: SolderMaskOverrides | None = None)
property solder_mask_margin: int
class kipy.board_types.SolderPasteOverrides(proto: SolderPasteOverrides | None = None, proto_ref: SolderPasteOverrides | None = None)
property solder_paste_margin: int
property solder_paste_margin_ratio: float
class kipy.board_types.Track(proto: Track | None = None)

Represents a straight track segment

property end: Vector2
property layer: int
length() → float

Calculates track length in nanometers

property net: Net
property start: Vector2
property width: int
class kipy.board_types.Via(proto: Via | None = None)
property locked: bool
property net: Net
property padstack: PadStack
property position: Vector2
property type: int
class kipy.board_types.Zone(proto: Zone | None = None)

Represents a copper, graphical, or rule area zone on a board

property border_hatch_pitch: int
property border_style: int
bounding_box() → Box2
property clearance: int | None

The override (local) clearance for this filled copper zone

property connection: ZoneConnectionSettings | None
property fill_mode: int | None
property filled: bool
property filled_polygons: dict[int, list[PolygonWithHoles]]
is_rule_area() → bool
property island_mode: int | None
property layers: Sequence[int]
property locked: bool
property min_island_area: int | None
property min_thickness: int | None
property name: str
property net: Net | None
property outline: PolygonWithHoles
property priority: int
property teardrop: TeardropSettings | None
property type: int
class kipy.board_types.ZoneConnectionSettings(proto: ZoneConnectionSettings | None = None, proto_ref: ZoneConnectionSettings | None = None)
property thermal_spokes: ThermalSpokeSettings
property zone_connection: int
class kipy.board_types.ZoneFilledPolygons(proto: ZoneFilledPolygons | None = None, proto_ref: ZoneFilledPolygons | None = None)

Represents the set of filled polygons of a zone on a single board layer

property layer: int
property shapes: Sequence[PolygonWithHoles]
kipy.board_types.to_concrete_board_shape(shape: BoardShape) → BoardShape | None
kipy.board_types.to_concrete_dimension(dimension: Dimension) → Dimension | None
kipy.board_types.unwrap(message: Any) → Wrapper