kicad-python 0.6.0__tar.gz → 0.7.1__tar.gz

{kicad_python-0.6.0 → kicad_python-0.7.1}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: kicad-python
-Version: 0.6.0
+Version: 0.7.1
 Summary: KiCad API Python Bindings
 License-Expression: MIT
 License-File: LICENSE
 Author: The KiCad Development Team
 Requires-Python: >=3.9
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
 Classifier: Typing :: Typed
+Requires-Dist: jsonschema (>=4.23.0,<5)
 Requires-Dist: protobuf (>=5.29,<6)
 Requires-Dist: pynng (>=0.9.0,<0.10.0)
 Requires-Dist: typing_extensions (>=4.13.2) ; python_version < "3.13"
@@ -24,9 +25,8 @@ Description-Content-Type: text/markdown
 `kicad-python` is the official Python bindings for the [KiCad](https://kicad.org) IPC API.  This
 library makes it possible to develop scripts and tools that interact with a running KiCad session.
 
-The KiCad IPC API can be considered in "public beta" state with the release of KiCad 9 (currently
-planned for on or around February 1, 2025).  The existing SWIG-based Python bindings for KiCad's
-PCB editor still exist in KiCad 9, but are in maintenance mode and will not be expanded.
+The KiCad IPC API replaces the legacy SWIG-based Python bindings for KiCad's PCB editor.
+The SWIG bindings still exist in KiCad 9 and 10, but are removed in KiCad 11.
 
 For more information about the IPC API, please see the
 [KiCad developer documentation](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/index.html).
@@ -98,6 +98,20 @@ plugins, copy or symlink them into the appropriate plugins path in order for KiC
 
 ## Release History
 
+### 0.7.1 (April 17, 2026)
+
+- Fix `KiCad.run_action` (leommxj)
+
+### 0.7.0 (April 17, 2026)
+
+- Add `Board.get_items_by_id` and groups support via `Board.get_groups` (requires KiCad 10) (Anthonypark, !15)
+- Add support for barcodes and `Board.get_barcodes` (requires KiCad 10.0.1)
+- Add support for reference images and `Board.get_reference_images` (requires KiCad 10.0.1)
+- Add `Board.set_title_block_info` (requires KiCad 10.0.1)
+- Add `Board.get_connected_items`, `Board.get_items_by_net`, and `Board.get_items_by_netclass` (requires KiCad 10.0.1)
+- Fix several bounding box calculation bugs
+- Support building with older versions of protoc
+
 ### 0.6.0 (March 15, 2026)
 
 - Fix missing conversion of rectangles into polygons when rotating by non-cardinal amounts (#86)

{kicad_python-0.6.0 → kicad_python-0.7.1}/README.md

@@ -3,9 +3,8 @@
 `kicad-python` is the official Python bindings for the [KiCad](https://kicad.org) IPC API.  This
 library makes it possible to develop scripts and tools that interact with a running KiCad session.
 
-The KiCad IPC API can be considered in "public beta" state with the release of KiCad 9 (currently
-planned for on or around February 1, 2025).  The existing SWIG-based Python bindings for KiCad's
-PCB editor still exist in KiCad 9, but are in maintenance mode and will not be expanded.
+The KiCad IPC API replaces the legacy SWIG-based Python bindings for KiCad's PCB editor.
+The SWIG bindings still exist in KiCad 9 and 10, but are removed in KiCad 11.
 
 For more information about the IPC API, please see the
 [KiCad developer documentation](https://dev-docs.kicad.org/en/apis-and-binding/ipc-api/index.html).
@@ -77,6 +76,20 @@ plugins, copy or symlink them into the appropriate plugins path in order for KiC
 
 ## Release History
 
+### 0.7.1 (April 17, 2026)
+
+- Fix `KiCad.run_action` (leommxj)
+
+### 0.7.0 (April 17, 2026)
+
+- Add `Board.get_items_by_id` and groups support via `Board.get_groups` (requires KiCad 10) (Anthonypark, !15)
+- Add support for barcodes and `Board.get_barcodes` (requires KiCad 10.0.1)
+- Add support for reference images and `Board.get_reference_images` (requires KiCad 10.0.1)
+- Add `Board.set_title_block_info` (requires KiCad 10.0.1)
+- Add `Board.get_connected_items`, `Board.get_items_by_net`, and `Board.get_items_by_netclass` (requires KiCad 10.0.1)
+- Fix several bounding box calculation bugs
+- Support building with older versions of protoc
+
 ### 0.6.0 (March 15, 2026)
 
 - Fix missing conversion of rectangles into polygons when rotating by non-cardinal amounts (#86)

{kicad_python-0.6.0 → kicad_python-0.7.1}/build/lib/kipy/board.py

@@ -24,8 +24,10 @@ from google.protobuf.empty_pb2 import Empty
 
 from kipy.board_types import (
     ArcTrack,
+    Barcode,
     BoardEditorAppearanceSettings,
     BoardItem,
+    ReferenceImage,
     BoardText,
     BoardTextBox,
     Dimension,
@@ -36,6 +38,7 @@ from kipy.board_types import (
     Track,
     Via,
     Zone,
+    Group,
     to_concrete_board_shape,
     to_concrete_dimension,
     unwrap
@@ -57,7 +60,7 @@ from kipy.proto.common.commands.editor_commands_pb2 import (
     EndCommit, EndCommitResponse,
     CreateItems, CreateItemsResponse,
     UpdateItems, UpdateItemsResponse,
-    GetItems, GetItemsResponse,
+    GetItems, GetItemsById, GetItemsResponse,
     DeleteItems, DeleteItemsResponse,
     HitTest, HitTestResponse, HitTestResult
 )
@@ -350,8 +353,10 @@ class Board:
         ]
 
     def _to_concrete_items(self, items: Sequence[Wrapper]) -> List[BoardItem]:
-        items_converted = []
+        items_converted: List[BoardItem] = []
         for it in items:
+            assert isinstance(it, BoardItem)
+
             if isinstance(it, BoardShape):
                 items_converted.append(to_concrete_board_shape(cast(BoardShape, it)))
             elif isinstance(it, Dimension):
@@ -362,7 +367,7 @@ class Board:
 
     def get_items(
         self, types: Union[KiCadObjectType.ValueType, Sequence[KiCadObjectType.ValueType]]
-    ) -> Sequence[Wrapper]:
+    ) -> Sequence[Item]:
         """Retrieves items from the board, optionally filtering to a single or set of types"""
         command = GetItems()
         command.header.document.CopyFrom(self._doc)
@@ -376,6 +381,105 @@ class Board:
             [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
         )
 
+    def get_items_by_id(
+        self, ids: Union[KIID, Sequence[KIID]]
+    ) -> Sequence[Item]:
+        """Retrieves items from the board by their KIID (internal unique identifier)
+
+        .. versionadded:: 0.7.0 (KiCad 10.0.0)
+        """
+        command = GetItemsById()
+        command.header.document.CopyFrom(self._doc)
+        if isinstance(ids, KIID):
+            command.items.append(ids)
+        else:
+            command.items.extend(ids)
+
+        return self._to_concrete_items(
+            [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
+        )
+
+    def get_items_by_net(
+        self,
+        nets: Union[Net, Sequence[Net]],
+        types: Optional[
+            Union[KiCadObjectType.ValueType, Sequence[KiCadObjectType.ValueType]]
+        ] = None,
+    ) -> Sequence[Item]:
+        """Retrieves items from the board, filtered by one or more nets
+
+        .. versionadded:: 0.7.0 (KiCad 10.0.1)"""
+        command = board_commands_pb2.GetItemsByNet()
+        command.header.document.CopyFrom(self._doc)
+
+        if isinstance(types, int):
+            command.types.append(types)
+        elif types is not None:
+            command.types.extend(types)
+
+        if isinstance(nets, Net):
+            command.nets.append(nets.proto)
+        else:
+            command.nets.extend([net.proto for net in nets])
+
+        return self._to_concrete_items(
+            [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
+        )
+
+    def get_items_by_netclass(
+        self,
+        net_classes: Union[str, Sequence[str]],
+        types: Optional[
+            Union[KiCadObjectType.ValueType, Sequence[KiCadObjectType.ValueType]]
+        ] = None,
+    ) -> Sequence[Item]:
+        """Retrieves items from the board, filtered by one or more net class names
+
+        .. versionadded:: 0.7.0 (KiCad 10.0.1)"""
+        command = board_commands_pb2.GetItemsByNetClass()
+        command.header.document.CopyFrom(self._doc)
+
+        if isinstance(types, int):
+            command.types.append(types)
+        elif types is not None:
+            command.types.extend(types)
+
+        if isinstance(net_classes, str):
+            command.net_classes.append(net_classes)
+        else:
+            command.net_classes.extend(net_classes)
+
+        return self._to_concrete_items(
+            [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
+        )
+
+    def get_connected_items(
+        self,
+        items: Union[BoardItem, KIID, Sequence[Union[BoardItem, KIID]]],
+        types: Optional[
+            Union[KiCadObjectType.ValueType, Sequence[KiCadObjectType.ValueType]]
+        ] = None,
+    ) -> Sequence[Item]:
+        """Retrieves items that are copper-connected to the given source item(s) or item IDs
+
+        .. versionadded:: 0.7.0 (KiCad 10.0.1)"""
+        command = board_commands_pb2.GetConnectedItems()
+        command.header.document.CopyFrom(self._doc)
+
+        if isinstance(types, int):
+            command.types.append(types)
+        elif types is not None:
+            command.types.extend(types)
+
+        source_items = [items] if isinstance(items, (BoardItem, KIID)) else items
+
+        for source in source_items:
+            command.items.append(source.id if isinstance(source, BoardItem) else source)
+
+        return self._to_concrete_items(
+            [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
+        )
+
     def get_tracks(self) -> Sequence[Union[Track, ArcTrack]]:
         """Retrieves all tracks and arc tracks on the board"""
         return [
@@ -432,10 +536,42 @@ class Board:
             )
         ]
 
+    def get_barcodes(self) -> Sequence[Barcode]:
+        """Retrieves all barcode objects on the board
+
+        .. versionadded:: 0.7.0"""
+        return [
+            cast(Barcode, item)
+            for item in self.get_items(types=[KiCadObjectType.KOT_PCB_BARCODE])
+        ]
+
+    def get_reference_images(self) -> Sequence[ReferenceImage]:
+        """Retrieves all reference image objects on the board
+
+        .. versionadded:: 0.7.0"""
+        return [
+            cast(ReferenceImage, item)
+            for item in self.get_items(types=[KiCadObjectType.KOT_PCB_REFERENCE_IMAGE])
+        ]
+
     def get_zones(self) -> Sequence[Zone]:
         """Retrieves all zones (including rule areas and graphic zones) on the board"""
         return [cast(Zone, item) for item in self.get_items(types=[KiCadObjectType.KOT_PCB_ZONE])]
 
+    def get_groups(self) -> Sequence[Group]:
+        """Retrieves all groups on the board
+
+        .. versionadded:: 0.7.0 (KiCad 10.0.0)"""
+        groups = [cast(Group, item) for item in self.get_items(types=[KiCadObjectType.KOT_PCB_GROUP])]
+
+        # Unwrap items in groups
+        if len(groups) > 0:
+            for group in groups:
+                items = self.get_items_by_id(group._item_ids)
+                group._unwrapped_items = items
+
+        return groups
+
     def get_as_string(self) -> str:
         """Returns the board as a string in KiCad's board file format"""
         command = editor_commands_pb2.SaveDocumentToString()
@@ -682,6 +818,15 @@ class Board:
         cmd.document.CopyFrom(self._doc)
         return TitleBlockInfo(self._kicad.send(cmd, base_types_pb2.TitleBlockInfo))
 
+    def set_title_block_info(self, title_block: TitleBlockInfo):
+        """Sets the title block information for the board
+
+        .. versionadded:: 0.7.0 (with KiCad 10.0.1)"""
+        cmd = editor_commands_pb2.SetTitleBlockInfo()
+        cmd.document.CopyFrom(self._doc)
+        cmd.title_block.CopyFrom(title_block.proto)
+        self._kicad.send(cmd, Empty)
+
     def get_origin(self, origin_type: board_commands_pb2.BoardOriginType.ValueType) -> Vector2:
         """Retrieves the specified (grid or drill/place) board origin
 
@@ -833,7 +978,7 @@ class Board:
         cmd = board_commands_pb2.CheckPadstackPresenceOnLayers()
         cmd.board.CopyFrom(self._doc)
 
-        items_map = {}
+        items_map: Dict[str, BoardItem] = {}
 
         if isinstance(items, BoardItem):
             cmd.items.append(items.id)
@@ -849,7 +994,7 @@ class Board:
 
         response = self._kicad.send(cmd, board_commands_pb2.PadstackPresenceResponse)
 
-        result = {}
+        result: Dict[BoardItem, Dict[board_types_pb2.BoardLayer.ValueType, bool]] = {}
         for entry in response.entries:
             if entry.item.value not in items_map:
                 continue