KiCad¶

class kipy.KiCad(socket_path: str | None = None, client_name: str | None = None, kicad_token: str | None = None, timeout_ms: int = 2000)¶

Creates a connection to a running KiCad instance

Parameters:

socket_path – The path to the IPC API socket (leave default to read from the KICAD_API_SOCKET environment variable, which will be set automatically by KiCad when launching API plugins, or to use the default platform-dependent socket path if the environment variable is not set).
client_name – A unique name identifying this plugin instance. Leave default to generate a random client name.
kicad_token – A token that can be provided to the client to uniquely identify a KiCad instance. Leave default to read from the KICAD_API_TOKEN environment variable.
timeout_ms – The maximum time to wait for a response from KiCad, in milliseconds

check_version() → bool¶: Checks if the connected KiCad version matches the version this library was built against

static from_client(client: KiCadClient)¶: Creates a KiCad object from an existing KiCad client

get_api_version() → KiCadVersion¶: Returns the version of KiCad that this library was built against

get_board() → Board¶: Retrieves a reference to the PCB open in KiCad, if one exists

get_kicad_binary_path(binary_name: str) → str¶

Returns the full path to the given KiCad binary

Parameters:: binary_name – The short name of the binary, such as kicad-cli or kicad-cli.exe. If on Windows, an .exe extension will be assumed if not present.
Returns:: The full path to the binary

get_open_documents(doc_type: int) → Sequence[DocumentSpecifier]¶: Retrieves a list of open documents matching the given type

get_plugin_settings_path(identifier: str) → str¶

Return a writeable path that a plugin can use for storing persistent data such as configuration files, etc. This path may not yet exist; actual creation of the directory for a given plugin is up to the plugin itself. Files in this path will not be modified if the plugin is uninstalled or upgraded.

Parameters:: identifier – should be the full identifier of the plugin (e.g. org.kicad.myplugin)
Returns:: a path, with local separators, that the plugin can use for storing settings

get_project(document: DocumentSpecifier) → Project¶: Returns a Project object for the given document

get_text_as_shapes(texts: Text | TextBox | Sequence[Text | TextBox]) → list[CompoundShape]¶: Returns polygonal shapes representing the given text objects

get_text_extents(text: Text) → Box2¶: Returns the bounding box of the given text object

get_version() → KiCadVersion¶: Returns the KiCad version as a string, including any package-specific info

ping()¶

run_action(action: str)¶

Runs a KiCad tool action, if it is available

WARNING: This is an unstable API and is not intended for use other than by API developers. KiCad does not guarantee the stability of action names, and running actions may have unintended side effects. :param action: the name of a KiCad TOOL_ACTION :return: a value from the KIAPI.COMMON.COMMANDS.RUN_ACTION_STATUS enum

Common Types¶

class kipy.common_types.Arc(proto: GraphicShape | None = None)¶

Represents a generic graphical arc (not a board or schematic item)

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 mid: Vector2¶

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¶

class kipy.common_types.Bezier(proto: GraphicShape | None = None)¶

Represents a graphic bezier curve (not a board or schematic item)

bounding_box() → Box2¶

property control1: Vector2¶

property control2: Vector2¶

property end: Vector2¶

property start: Vector2¶

class kipy.common_types.Circle(proto: GraphicShape | None = None)¶

Represents a graphic circle (not a board or schematic item)

bounding_box() → Box2¶: Calculates the bounding box of the circle

property center: Vector2¶

radius() → float¶: Calculates the radius of the circle

property radius_point: Vector2¶

class kipy.common_types.Color(proto: Color | None = None, proto_ref: Color | None = None)¶

property alpha: float¶

property blue: float¶

property green: float¶

property red: float¶

class kipy.common_types.Commit(id: KIID)¶

property id: KIID¶

class kipy.common_types.CompoundShape(proto: CompoundShape | None = None)¶

Represents a compound shape (a collection of other shapes)

append(shape: GraphicShape)¶

property shapes: Sequence[GraphicShape]¶

class kipy.common_types.GraphicAttributes(proto: GraphicAttributes | None = None, proto_ref: GraphicAttributes | None = None)¶

property fill: GraphicFillAttributes¶

property stroke: StrokeAttributes¶

class kipy.common_types.GraphicFillAttributes(proto: GraphicFillAttributes | None = None, proto_ref: GraphicFillAttributes | None = None)¶

property color: Color¶: The fill color. Only supported in schematic graphics.

property filled: bool¶

class kipy.common_types.GraphicShape(proto: GraphicShape | None = None)¶

Represents an abstract graphic shape (not a board or schematic item)

property attributes: GraphicAttributes¶

bounding_box() → Box2¶

class kipy.common_types.LibraryIdentifier(proto: LibraryIdentifier | None = None, proto_ref: LibraryIdentifier | None = None)¶

A KiCad library identifier (LIB_ID), consisting of a library nickname and entry name

property library: str¶

property name: str¶

class kipy.common_types.Polygon(proto: GraphicShape | None = None)¶

Represents a graphic polygon (not a board or schematic item)

bounding_box() → Box2¶: Calculates the bounding box of the polygon

property polygons: Sequence[PolygonWithHoles]¶

class kipy.common_types.Rectangle(proto: GraphicShape | None = None)¶

Represents a graphic rectangle (not a board or schematic item)

property bottom_right: Vector2¶

bounding_box() → Box2¶: Calculates the bounding box of the rectangle

property top_left: Vector2¶

class kipy.common_types.Segment(proto: GraphicShape | None = None)¶

Represents a base graphic segment (not a board or schematic item)

bounding_box() → Box2¶: Calculates the bounding box of the segment

property end: Vector2¶

property start: Vector2¶

class kipy.common_types.StrokeAttributes(proto: StrokeAttributes | None = None, proto_ref: StrokeAttributes | None = None)¶

property color: Color¶: The stroke color. Only supported in schematic graphics.

property style: int¶

property width: int¶: The stroke line width in nanometers

class kipy.common_types.Text(proto: Text | None = None, proto_ref: Text | None = None)¶

Common text properties (wrapper for KiCad’s EDA_TEXT) shared between board and schematic

property attributes: TextAttributes¶

property position: Vector2¶

property value: str¶

class kipy.common_types.TextAttributes(proto: TextAttributes | None = None, proto_ref: TextAttributes | None = None)¶

property angle: Angle¶

property bold: bool¶

property font_name: str¶

property horizontal_alignment: int¶

property italic: bool¶

property keep_upright: bool¶

property line_spacing: float¶

property mirrored: bool¶

property multiline: bool¶

property size: Vector2¶

property stroke_width: Distance¶

property underlined: bool¶

property vertical_alignment: int¶

property visible: bool¶

class kipy.common_types.TextBox(proto: TextBox | None = None, proto_ref: TextBox | None = None)¶

property attributes: TextAttributes¶

property bottom_right: Vector2¶

property size: Vector2¶

property top_left: Vector2¶

property value: str¶

class kipy.common_types.TitleBlockInfo(proto: TitleBlockInfo | None = None, proto_ref: TitleBlockInfo | None = None)¶

property comments: dict[int, str]¶

property company: str¶

property date: str¶

property revision: str¶

property title: str¶

kipy.common_types.to_concrete_shape(shape: GraphicShape) → GraphicShape | None¶

class kipy.proto.common.types.DocumentSpecifier¶: A protobuf message referring to a document or project open in KiCad. Typically this is retrieved from kipy.KiCad.get_open_documents() or kipy.KiCad.get_project().