KiCad¶

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
headless – Start and connect to a headless kicad-cli api-server instance.
kicad_cli_path – Optional path to kicad-cli.
file_path – Optional path to a board, schematic, or project file to pre-load in headless mode.

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

close()¶: Close the KiCad connection and stop any headless server started by this object.

close_document(document: DocumentSpecifier)¶: In headless mode, closes an open document. Not currently supported for GUI mode.

Added in version 0.7.0.

create_document(path: str, type: int) → DocumentSpecifier¶: In headless mode, creates a new document. Not currently supported for GUI mode. The new document is created in memory only; call save() to persist to disk. A project will be created for the document if it doesn’t already exist. Returns an error if the current document is unsaved: save or revert first.

Added in version 0.x.y: (KiCad 11)

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_library_footprint(lib_id: LibraryIdentifier | str, document: DocumentSpecifier | None = None) → Footprint¶

Retrieves the definition of a footprint from a library

Requires the libraries to have been loaded already. Use load_all_libraries() first in headless contexts.

Parameters:

lib_id – The footprint to retrieve, either as a LibraryIdentifier or a string such as "Resistor_SMD:R_0603_1608Metric".
document – Optional document specifier used to enable project-specific libraries; if not given, only global libraries are searched.

Returns:

The footprint definition.

Added in version 0.x.y: (KiCad 11)

get_library_footprints(nicknames: Sequence[str] = ()) → Sequence[LibraryIdentifier]¶

Retrieves the identifiers of all footprints contained in the given library or libraries

See get_library_items() for caveats about asynchronous library loading.

Parameters:: nicknames – The library nickname(s) to query. If empty, all footprint libraries are queried.

Added in version 0.x.y: (KiCad 11)

get_library_items(type: int, nicknames: Sequence[str] = ()) → Sequence[LibraryIdentifier]¶

Retrieves the identifiers of all items contained in the given library or libraries

Library loading happens asynchronously after KiCad starts up, so this command may return an empty list if the requested libraries have not finished loading yet. Use wait_for_libraries() to wait until the libraries you need have finished loading.

Parameters:

type – The type of library to query
nicknames – The library nickname(s) to query. If empty, all libraries of the given type are queried.

Added in version 0.x.y: (KiCad 11)

get_library_statuses(types: int | Sequence[int] | None = None, scope: int = 3) → Sequence[LibraryStatus]¶

Retrieves the load status of each library in the given table scope(s)

Parameters:

types – The type(s) of library to query. If not given, all types are queried.
scope – Which table scope(s) to query (global, project, or both).

Returns:

One LibraryStatus per enabled library row in the queried tables.

Added in version 0.x.y: (KiCad 11)

get_library_symbol(lib_id: LibraryIdentifier | str, document: DocumentSpecifier | None = None) → SchematicSymbol¶

Retrieves the definition of a symbol from a library

Requires the libraries to have been loaded already. Use load_all_libraries() first in headless contexts.

Parameters:

lib_id – The symbol to retrieve, either as a LibraryIdentifier or a string such as "Device:R".
document – Optional document specifier used to enable project-specific libraries; if not given, only global libraries are searched.

Returns:

The symbol definition.

Added in version 0.x.y: (KiCad 11)

get_library_symbols(nicknames: Sequence[str] = ()) → Sequence[LibraryIdentifier]¶

Retrieves the identifiers of all symbols contained in the given library or libraries

See get_library_items() for caveats about asynchronous library loading.

Parameters:: nicknames – The library nickname(s) to query. If empty, all symbol libraries are queried.

Added in version 0.x.y: (KiCad 11)

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

get_paths() → dict[int, str]¶: Returns a dictionary mapping well-known KiCad filesystem paths to their locations. Paths are returned in platform-native format. Not every path is guaranteed to exist and be accessible. The meaning and contents of this dictionary are not covered by API stability guarantees and may change between KiCad versions.

Added in version 0.x.y: (KiCad 11)

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_schematic() → Schematic¶: Added in version 0.x.y: (KiCad 11)

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

load_all_libraries(types: int | Sequence[int] | None = None)¶

Starts a background load of all libraries of the given type(s) that are listed in the library tables

This command is only available in headless (command-line) mode; in GUI mode KiCad preloads libraries on its own. The load proceeds asynchronously; use wait_for_libraries() to wait for it to finish.

NOTE: KiCad may need to load the schematic and PCB editor dynamic libraries if they have not been loaded already prior to this call (such as if you call this right after starting kicad-cli). In this case, KiCad may briefly stop responding to API messages, which can cause transient timeout errors if your connection timeout is set to a low value.

Parameters:: types – The type(s) of library to load. If not given, all types are loaded.
Raise:: LibraryCommandError if the load request could not be processed.

Added in version 0.x.y: (KiCad 11)

open_document(path: str, type: int) → DocumentSpecifier¶: In headless mode, opens a document. Not currently supported for GUI mode.

Added in version 0.7.0.

open_library_item(library: str, name: str, type: int)¶

Loads a library item (e.g. a footprint) into the matching editor.

At present, only DOCTYPE_FOOTPRINT is supported by KiCad; the footprint editor must already be open.

Parameters:

library – The library nickname.
name – The entry name within the library.
type – The document type of the item to load.

ping()¶

reload_library(type: int, scope: int, nicknames: Sequence[str] = ())¶

Reloads library table row(s) from disk

The reload process operates asynchronously; updated library content will not be available until the load has completed. Use wait_for_libraries() to wait for the reload to finish.

Parameters:

type – The type of library to reload.
scope – Which table to look up the libraries in. LTS_BOTH is not valid here; choose one table.
nicknames – The library nickname(s) to reload. If empty, all libraries matching the given type and scope are reloaded.

Raise:

LibraryCommandError if one of the given nicknames could not be reloaded (usually because the nickname could not be found in the library tables).

Added in version 0.x.y: (KiCad 11)

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

wait_for_libraries(types: int | Sequence[int] | None = None, interval_ms: int = 500, timeout_s: float = 60.0, scope: int = 3) → Sequence[LibraryStatus]¶

Waits until no queried libraries are still loading, polling with get_library_statuses().

Parameters:

types – The type(s) of library to wait for. If not given, all types are waited for.
interval_ms – How long to sleep between status polls, in milliseconds.
timeout_s – Maximum time to wait, in seconds, before raising TimeoutError.
scope – Which table scope(s) to query.

Returns:

The final status of each library. Libraries whose status is not LLS_LOADED did not finish loading; check LibraryStatus.error_message on those entries for details.

Added in version 0.x.y: (KiCad 11)

Common Types¶

class Arc(proto: GraphicShape | None = None, proto_ref: GraphicShape | None = None)¶

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

angle() → float | None¶

Calculates the angle between the start and end of the arc in radians

Returns:: The angle of the arc, or None if the arc is degenerate

Added in version 0.4.0.

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¶

classmethod from_coords(start: Vector2, mid: Vector2, end: Vector2) → Self¶: Create an arc from its start, midpoint, and end coordinates.

Added in version 0.9.0.

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 Bezier(proto: GraphicShape | None = None, proto_ref: 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¶

classmethod from_coords(start: Vector2, control1: Vector2, control2: Vector2, end: Vector2) → Self¶: Create a bezier curve from its endpoints and control points.

Added in version 0.9.0.

property start: Vector2¶

class Circle(proto: GraphicShape | None = None, proto_ref: 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¶

classmethod from_center_radius(center: Vector2, radius: int) → Self¶: Create a circle from its center and radius.

Added in version 0.9.0.

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

property radius_point: Vector2¶

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

property alpha: float¶

property blue: float¶

property green: float¶

property red: float¶

class Commit(id: KIID)¶

property id: KIID¶

class CompoundShape(proto: CompoundShape | None = None)¶

Represents a compound shape (a collection of other shapes)

property shapes: MutableWrapperSequence[GraphicShape]¶

class CustomProperty(proto: CustomProperty | None = None, proto_ref: CustomProperty | None = None)¶

A user-defined key/value property stored on a board/schematic object

Added in version 0.x.0: (KiCad 11)

property key: str¶

property value: str¶

class DesignVariant(proto: DesignVariant | None = None, proto_ref: DesignVariant | None = None)¶

property description: str¶: The default variant is addressed by the empty string

property name: str¶: Variant name (must be case-insensitively unique in a project)

class Ellipse(proto: GraphicShape | None = None, proto_ref: GraphicShape | None = None)¶

Represents a graphic ellipse (not a board or schematic item).

Added in version 0.9.0.

classmethod from_center_radii(center: Vector2, major_radius: int, minor_radius: int, rotation: Angle | None = None) → Self¶: Create an ellipse from its center, radii, and optional rotation.

class EllipseArc(proto: GraphicShape | None = None, proto_ref: GraphicShape | None = None)¶

Represents a graphic elliptical arc (not a board or schematic item).

Added in version 0.x.0.

classmethod from_center_radii_angles(center: Vector2, major_radius: int, minor_radius: int, start_angle: Angle, end_angle: Angle, rotation: Angle | None = None) → Self¶: Create an ellipse arc from its center, radii, and angles.

class EmbeddedFile(proto: EmbeddedFile | None = None, proto_ref: EmbeddedFile | None = None)¶

A file embedded in a document, such as a font, datasheet, or 3D model

Added in version 0.9.0: (KiCad 10.0.7)

property data: bytes¶: zstd-compressed payload, base64-encoded.

property data_hash: str¶: MurmurHash3 integrity hash

classmethod from_bytes(data: bytes, name: str, type: int = 1) → EmbeddedFile¶: Creates a new embedded file from raw bytes.

classmethod from_path(path: str | Path, type: int | None = None) → EmbeddedFile¶

Creates a new embedded file from a file path.

Parameters:

path – Path of the file to embed.
type – Embedded file type, guessed from the extension when omitted.

property name: str¶

property type: int¶

class EmbeddedFiles(proto: EmbeddedFiles | None = None, proto_ref: EmbeddedFiles | None = None)¶

Added in version 0.9.0: (KiCad 10.0.7)

property files: Sequence[EmbeddedFile]¶

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

property fill: GraphicFillAttributes¶

property stroke: StrokeAttributes¶

class 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 GraphicShape(proto: GraphicShape | None = None, proto_ref: GraphicShape | None = None)¶

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

property attributes: GraphicAttributes¶

bounding_box() → Box2¶

classmethod from_concrete(value: GraphicShape) → GraphicShape¶: Packs a concrete shape subclass into a GraphicShape of the static base type

property proto¶

class JobResult(proto: RunJobResponse | None = None, proto_ref: RunJobResponse | None = None)¶

A result returned from running an export job. Provides overall status and a list of files created by the job.

property message: str¶: Optional message containing warning or error details. Should be empty if status is JS_SUCCESS.

property output_paths: list[str]¶

property status: int¶

property succeeded: bool¶

class 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 LibraryStatus(proto: LibraryStatusEntry | None = None, proto_ref: LibraryStatusEntry | None = None)¶

property error_message: str | None¶: The error message if the library failed to load, otherwise None

property nickname: str¶: The library nickname (the first part of a LIB_ID)

property scope: int¶: Which library table this library belongs to

property status: int¶: The load status of this library

property type: int¶: The kind of content managed by this library

class LineEnding(proto: LineEnding | None = None, proto_ref: LineEnding | None = None)¶

Added in version 0.x.0: (KiCad 11)

property length: int | None¶

property stroke: StrokeAttributes¶

property style: int¶

property width: int | None¶

class PageSettings(proto: PageSettings | None = None, proto_ref: PageSettings | None = None)¶

property drawing_sheet: str¶: Path to a .kicad_wks drawing sheet file. Empty string means the default (built-in) drawing sheet is used.

property orientation: int¶

property page_size: int¶

property user_page_size: Vector2¶: Relevant only when page_size == PS_USER

class Polygon(proto: GraphicShape | None = None, proto_ref: GraphicShape | None = None)¶

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

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

classmethod from_outline(outline: PolyLine, *holes: PolyLine) → Self¶

Create a polygon from an outer outline and optional holes.

The outline and holes are forced closed.

Added in version 0.9.0.

property polygons: MutableWrapperSequence[PolygonWithHoles]¶: The polygons of this shape as a live view

class Rectangle(proto: GraphicShape | None = None, proto_ref: 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

classmethod from_coords(top_left: Vector2, bottom_right: Vector2) → Self¶: Create a rectangle from its top-left and bottom-right corners.

Added in version 0.9.0.

property top_left: Vector2¶

class Segment(proto: GraphicShape | None = None, proto_ref: 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¶

classmethod from_coords(start: Vector2, end: Vector2) → Self¶: Create a segment from its endpoints.

Added in version 0.9.0.

property start: Vector2¶

class SheetPath(proto: SheetPath | None = None, proto_ref: SheetPath | None = None)¶

Represents the path to a unique sheet instance or symbol instance in a schematic

property path: list[KIID]¶

property path_human_readable: str¶: The sheet path with human-readable sheet names. May not be available in all contexts (for example, is not present in contexts where the SheetPath is sourced from a board object)

class 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 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 TextAttributes(proto: TextAttributes | None = None, proto_ref: TextAttributes | None = None)¶

property angle: float¶: The orientation of the text in degrees

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: int¶

property underlined: bool¶

property vertical_alignment: int¶

property visible: bool¶: Deprecated since version 0.3.0: removed in KiCad 9.0.1

Text items are always visible as of 9.0.1, only Fields can be set to hidden

class 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 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¶

to_concrete_shape(shape: GraphicShape) → GraphicShape | None¶

class 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().