Project¶

class Project(kicad: KiCadClient, document: DocumentSpecifier)¶

property document: DocumentSpecifier¶

expand_text_variables(text: str, *, expand_env_vars: bool = False) → str¶

expand_text_variables(text: list[str], *, expand_env_vars: bool = False) → list[str]

Expands text variables in the given text, optionally expanding environment variables

Parameters:: expand_env_vars – will expand environment variables in addition to built-in KiCad text variables when True.

get_net_class_assignments() → NetClassAssignments¶: Returns the netclass membership assignments stored in the project settings. Note that the effective netclass assignments for a project consist of

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

get_net_classes() → list[NetClass]¶

get_text_variables() → TextVariables¶

property name: str¶: Returns the name of the project

property path: str¶

set_net_class_assignments(assignments: NetClassAssignments, merge_mode: int = 1)¶

Sets the project netclass membership assignments, merging with existing assignments by default

In MMM_MERGE mode, each given direct assignment replaces the full set of netclasses for that net (an assignment with an empty netclasses list removes all assignments for that net), and each given pattern assignment replaces the netclass for that pattern (an assignment with an empty netclass name removes the pattern). In MMM_REPLACE mode, the given assignments represent the complete desired state: any existing assignments or patterns not present in the request are removed.

Parameters:

assignments – the netclass assignments to set
merge_mode – MMM_MERGE merges the given assignments into the existing set, MMM_REPLACE replaces the existing set of assignments

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

set_net_classes(net_classes: list[NetClass], merge_mode: int = 1)¶

Sets the project net classes, merging with existing classes by default

Parameters:

net_classes – the net classes to set
merge_mode – MMM_MERGE merges the given classes into the existing set, MMM_REPLACE replaces the existing set of net classes

Added in version 0.9.0.

set_text_variables(variables: TextVariables, merge_mode: int = 1)¶

Document Management¶

Shared commands for document editors (board, schematic, etc).

class EditorCommandsHandler¶

Mixin implementing the commands that KiCad handles identically for every open editor document.

Subclasses must provide _kicad (a KiCadClient), _doc (the DocumentSpecifier of the open document), and _item_from_message, which converts a generic unwrapped message into the document’s concrete type.

add_to_selection(items: _ItemT_co | Sequence[_ItemT_co]) → Sequence[_ItemT_co]¶

Adds one or more items to the current selection

Parameters:: items – The items to add to the selection
Returns:: The updated selection

begin_commit() → Commit¶

Begins a commit transaction on the document, 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 document 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 document 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()¶

create_items(items: Wrapper | Iterable[Wrapper]) → list[_ItemT_co]¶

drop_commit(commit: Commit)¶: Cancels a commit, discarding any changes made since the commit was opened

get_as_string() → str¶: Returns the document as a string in KiCad’s native file format

get_items(types: int | Sequence[int] | None = None) → Sequence[_ItemT_co]¶

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

Providing no types filter will result in all valid types for the given document being retrieved on KiCad 10.0.7 and newer, and is an error on older versions.

get_items_by_id(ids: KIID | Sequence[KIID]) → Sequence[_ItemT_co]¶: Retrieves items from the document by their KIID (internal unique identifier)

Added in version 0.7.0: (KiCad 10.0.0)

get_selection(types: int | Sequence[int] | None = None) → Sequence[_ItemT_co]¶: Retrieves the items in the current selection, optionally filtering by type

get_selection_as_string() → str¶: Returns the current selection as a string in KiCad’s native file format

is_document_modified() → bool¶: Returns true if this document has been modified (either interactively or by the API) since it was last saved.

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

push_commit(commit: Commit, message: str = '')¶: If a commit is open, pushes the changes to the document and closes the commit. This will result in a single undo step being added to the undo history.

remove_from_selection(items: _ItemT_co | Sequence[_ItemT_co]) → Sequence[_ItemT_co]¶

Removes one or more items from the current selection

Parameters:: items – The items to remove from the selection
Returns:: The updated selection

remove_items(items: _ItemT_co | Sequence[_ItemT_co])¶: Deletes one or more items from the document

remove_items_by_id(items: KIID | Sequence[KIID])¶: Deletes one or more items from the document using their unique IDs

Added in version 0.4.0.

revert()¶: Reverts the document to the last saved state

save()¶

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

Saves the document to a new file. Does not open the newly-saved file.

Parameters:

filename – The path to save the document 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 document

update_items(items: _ItemT_co | Sequence[_ItemT_co]) → list[_ItemT_co]¶

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

Returns the updated items, which may be different from the input items if any updates failed to apply (for example, if any properties were out of range and were clamped)