kicad-python 0.1.0a0__tar.gz → 0.1.1__tar.gz

{kicad_python-0.1.0a0 → kicad_python-0.1.1}/PKG-INFO

@@ -1,24 +1,25 @@
 Metadata-Version: 2.1
 Name: kicad-python
-Version: 0.1.0a0
+Version: 0.1.1
 Summary: KiCad API Python Bindings
 Home-page: https://kicad.org/
 License: GPL-3
 Author: The KiCad Development Team
-Requires-Python: >=3.8,<4.0
-Classifier: Development Status :: 2 - Pre-Alpha
+Requires-Python: >=3.9,<3.13
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
-Requires-Dist: protobuf (>=4.21.12,<5.0.0)
-Requires-Dist: pynng (>=0.7.2,<0.8.0)
+Requires-Dist: furo (>=2024.8.6,<2025.0.0)
+Requires-Dist: protobuf (>=5.29,<6.0)
+Requires-Dist: pynng (>=0.8.0,<0.9.0)
+Requires-Dist: sphinx (==7.4)
 Project-URL: Repository, https://gitlab.com/kicad/code/kicad-python
 Description-Content-Type: text/markdown
 
@@ -27,10 +28,24 @@ 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.
+
 For more information about the IPC API, please see the [KiCad developer documentation](https://dev-docs.kicad.org).
 
-Note: Version 0.0.2 and prior of this package are an obsolete earlier effort and are unrelated to
-this codebase.
+> Note: Version 0.0.2 and prior of this package are an obsolete earlier effort and are unrelated to
+> this codebase.
+
+## Requirements
+
+Using the IPC API requires a suitable version of KiCad (9.0 or higher) and requires that KiCad be
+running with the API server enabled in Preferences > Plugins.  This package also depends on the
+`protobuf` and `pynng` packages for communication with KiCad.
+
+> Note: Unlike the SWIG-based Python bindings, the IPC API requires communication with a running
+> instance of KiCad.  It is not possible to use `kicad-python` to manipulate KiCad design files
+> without KiCad running.
 
 ## Contributing
 
@@ -49,10 +64,28 @@ See COMPILING.md
 
 ## API Documentation
 
-There is no documentation yet, sorry.  We expect things to be stable enough to begin documentation
-for general use in late 2024.
+There is no documentation separate from the code comments and examples yet, sorry!  This will be
+more of a priority once the KiCad 9 release is stable.
 
 ## Examples
 
 Check out the repository for some example scripts that may serve as a starting point.
 
+## Release History
+
+### 0.1.1 (December 24, 2024)
+
+- Bump dependency versions to fix compilation with newer protoc
+
+### 0.1.0 (December 21, 2024)
+
+*Corresponding KiCad version: 9.0.0-rc1*
+
+First formal release of the new IPC-API version of this package.  Contains support for most of the
+KiCad API functionality that is currently exposed, which is focused around the PCB editor to enable
+a transition path from existing SWIG-based plugins.
+
+Caveats / Known Issues:
+
+- Compatibility limited to Python 3.9 ~ 3.12 due to `pynng` not yet being updated for 3.13
+

kicad_python-0.1.1/README.md

@@ -0,0 +1,65 @@
+# KiCad API Python Bindings
+
+`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.
+
+For more information about the IPC API, please see the [KiCad developer documentation](https://dev-docs.kicad.org).
+
+> Note: Version 0.0.2 and prior of this package are an obsolete earlier effort and are unrelated to
+> this codebase.
+
+## Requirements
+
+Using the IPC API requires a suitable version of KiCad (9.0 or higher) and requires that KiCad be
+running with the API server enabled in Preferences > Plugins.  This package also depends on the
+`protobuf` and `pynng` packages for communication with KiCad.
+
+> Note: Unlike the SWIG-based Python bindings, the IPC API requires communication with a running
+> instance of KiCad.  It is not possible to use `kicad-python` to manipulate KiCad design files
+> without KiCad running.
+
+## Contributing
+
+At the moment, these bindings are being developed in parallel with the IPC API itself, and
+development is being coordinated by the KiCad team (main point of contact: Jon Evans / @craftyjon).
+Expect rapid change and instability during this development period, and please do not send merge
+requests without discussing your idea for changes with the team ahead of time.
+
+Once the initial stable API is released (planned for KiCad 9.0 in February 2025), this Python
+library will also have its first stable release and be considered fully supported.  Until that
+time, please consider this a development preview.
+
+## Building
+
+See COMPILING.md
+
+## API Documentation
+
+There is no documentation separate from the code comments and examples yet, sorry!  This will be
+more of a priority once the KiCad 9 release is stable.
+
+## Examples
+
+Check out the repository for some example scripts that may serve as a starting point.
+
+## Release History
+
+### 0.1.1 (December 24, 2024)
+
+- Bump dependency versions to fix compilation with newer protoc
+
+### 0.1.0 (December 21, 2024)
+
+*Corresponding KiCad version: 9.0.0-rc1*
+
+First formal release of the new IPC-API version of this package.  Contains support for most of the
+KiCad API functionality that is currently exposed, which is focused around the PCB editor to enable
+a transition path from existing SWIG-based plugins.
+
+Caveats / Known Issues:
+
+- Compatibility limited to Python 3.9 ~ 3.12 due to `pynng` not yet being updated for 3.13

{kicad_python-0.1.0a0 → kicad_python-0.1.1/build/lib}/kipy/board.py

@@ -16,29 +16,38 @@
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from time import sleep
-from typing import List, Dict, Union, Iterable, Optional, Sequence, cast
+from typing import List, Dict, Union, Iterable, Optional, Sequence, cast, overload
 from google.protobuf.empty_pb2 import Empty
 
 from kipy.board_types import (
-    Arc,
+    ArcTrack,
     BoardItem,
+    BoardText,
+    BoardTextBox,
+    Dimension,
     FootprintInstance,
     Net,
     Pad,
-    Text,
+    BoardShape,
     Track,
     Via,
+    Zone,
+    to_concrete_board_shape,
+    to_concrete_dimension,
     unwrap
 )
 from kipy.client import ApiError, KiCadClient
-from kipy.common_types import Commit, TextAttributes
-from kipy.geometry import Box2, Vector2
+from kipy.common_types import Commit, TitleBlockInfo, TextAttributes
+from kipy.geometry import Box2, PolygonWithHoles, Vector2
+from kipy.project import Project
+from kipy.proto.board import board_types_pb2
+from kipy.proto.common.commands import editor_commands_pb2, project_commands_pb2
 from kipy.proto.common.envelope_pb2 import ApiStatusCode
 from kipy.util import pack_any
 from kipy.wrapper import Item, Wrapper
 
 from kipy.proto.common.commands import Ping
-from kipy.proto.common.types import DocumentSpecifier, KIID, KiCadObjectType
+from kipy.proto.common.types import DocumentSpecifier, KIID, KiCadObjectType, base_types_pb2
 from kipy.proto.common.commands.editor_commands_pb2 import (
     BeginCommit, BeginCommitResponse, CommitAction,
     EndCommit, EndCommitResponse,
@@ -46,7 +55,6 @@ from kipy.proto.common.commands.editor_commands_pb2 import (
     UpdateItems, UpdateItemsResponse,
     GetItems, GetItemsResponse,
     DeleteItems, DeleteItemsResponse,
-    BoundingBoxResponse,
     HitTest, HitTestResponse, HitTestResult
 )
 from kipy.proto.board import board_pb2
@@ -54,7 +62,7 @@ from kipy.proto.board import board_commands_pb2
 
 # Re-exported protobuf enum types
 from kipy.proto.board.board_pb2 import (    # noqa
-    BoardLayerClass 
+    BoardLayerClass
 )
 from kipy.proto.board.board_types_pb2 import ( #noqa
     BoardLayer
@@ -64,28 +72,35 @@ class BoardLayerGraphicsDefaults(Wrapper):
     """Wraps a kiapi.board.types.BoardLayerGraphicsDefaults object"""
     def __init__(self, proto: Optional[board_pb2.BoardLayerGraphicsDefaults] = None):
         self._proto = board_pb2.BoardLayerGraphicsDefaults()
-    
+
         if proto is not None:
             self._proto.CopyFrom(proto)
 
     @property
     def text(self) -> TextAttributes:
         return TextAttributes(self._proto.text)
-        
+
 class Board:
     def __init__(self, kicad: KiCadClient, document: DocumentSpecifier):
         self._kicad = kicad
         self._doc = document
 
+    @property
+    def client(self) -> KiCadClient:
+        return self._kicad
+
     @property
     def document(self) -> DocumentSpecifier:
         return self._doc
 
+    def project(self) -> Project:
+        return Project(self._kicad, self._doc)
+
     @property
     def name(self) -> str:
         """Returns the file name of the board"""
         return self._doc.board_filename
-    
+
     def save(self):
         pass
 
@@ -108,7 +123,7 @@ class Board:
         command.id.CopyFrom(commit.id)
         command.action = CommitAction.CMA_DROP
         self._kicad.send(command, EndCommitResponse)
-    
+
     def create_items(self, items: Union[Wrapper, Iterable[Wrapper]]) -> List[Wrapper]:
         command = CreateItems()
         command.header.document.CopyFrom(self._doc)
@@ -137,9 +152,9 @@ class Board:
 
         return [unwrap(item) for item in self._kicad.send(command, GetItemsResponse).items]
 
-    def get_tracks(self) -> Sequence[Union[Track, Arc]]:
+    def get_tracks(self) -> Sequence[Union[Track, ArcTrack]]:
         return [
-            cast(Track, item) if isinstance(item, Track) else cast(Arc, item)
+            cast(Track, item) if isinstance(item, Track) else cast(ArcTrack, item)
             for item in self.get_items(
                 types=[KiCadObjectType.KOT_PCB_TRACE, KiCadObjectType.KOT_PCB_ARC]
             )
@@ -147,16 +162,58 @@ class Board:
 
     def get_vias(self) -> Sequence[Via]:
         return [cast(Via, item) for item in self.get_items(types=[KiCadObjectType.KOT_PCB_VIA])]
-    
+
     def get_pads(self) -> Sequence[Pad]:
         return [cast(Pad, item) for item in self.get_items(types=[KiCadObjectType.KOT_PCB_PAD])]
-    
+
     def get_footprints(self) -> Sequence[FootprintInstance]:
         return [
             cast(FootprintInstance, item)
             for item in self.get_items(types=[KiCadObjectType.KOT_PCB_FOOTPRINT])
         ]
-    
+
+    def get_shapes(self) -> Sequence[BoardShape]:
+        """Retrieves all graphic shapes (not including tracks or text) on the board"""
+        return [
+            item
+            for item in (
+                to_concrete_board_shape(cast(BoardShape, item))
+                for item in self.get_items(types=[KiCadObjectType.KOT_PCB_SHAPE])
+            )
+            if item is not None
+        ]
+
+    def get_dimensions(self) -> Sequence[Dimension]:
+        """Retrieves all dimension objects on the board"""
+        return [
+            item
+            for item in (
+                to_concrete_dimension(cast(Dimension, item))
+                for item in self.get_items(types=[KiCadObjectType.KOT_PCB_DIMENSION])
+            )
+            if item is not None
+        ]
+
+    def get_text(self) -> Sequence[Union[BoardText, BoardTextBox]]:
+        return [
+            cast(BoardText, item) if isinstance(item, BoardText) else cast(BoardTextBox, item)
+            for item in self.get_items(
+                types=[KiCadObjectType.KOT_PCB_TEXT, KiCadObjectType.KOT_PCB_TEXTBOX]
+            )
+        ]
+
+    def get_zones(self) -> Sequence[Zone]:
+        return [cast(Zone, item) for item in self.get_items(types=[KiCadObjectType.KOT_PCB_ZONE])]
+
+    def get_as_string(self) -> str:
+        command = editor_commands_pb2.SaveDocumentToString()
+        command.document.CopyFrom(self._doc)
+        return self._kicad.send(command, editor_commands_pb2.SavedDocumentResponse).contents
+
+    def get_selection_as_string(self) -> str:
+        command = editor_commands_pb2.SaveSelectionToString()
+        return self._kicad.send(command, editor_commands_pb2.SavedSelectionResponse).contents
+
     def update_items(self, items: Union[BoardItem, Sequence[BoardItem]]):
         command = UpdateItems()
         command.header.document.CopyFrom(self._doc)
@@ -220,7 +277,7 @@ class Board:
         command = board_commands_pb2.GetBoardStackup()
         command.board.CopyFrom(self._doc)
         return self._kicad.send(command, board_commands_pb2.BoardStackupResponse).stackup
-    
+
     def get_graphics_defaults(self) -> Dict[int, BoardLayerGraphicsDefaults]:
         cmd = board_commands_pb2.GetGraphicsDefaults()
         cmd.board.CopyFrom(self._doc)
@@ -233,13 +290,112 @@ class Board:
             board_pb2.BoardLayerClass.BLC_FABRICATION: BoardLayerGraphicsDefaults(reply.defaults.layers[4]),
             board_pb2.BoardLayerClass.BLC_OTHER:       BoardLayerGraphicsDefaults(reply.defaults.layers[5])
         }
-    
-    def get_text_extents(self, text: Text) -> Box2:
-        cmd = board_commands_pb2.GetTextExtents()
-        cmd.text.CopyFrom(text.proto)
-        reply = self._kicad.send(cmd, BoundingBoxResponse)
-        return Box2(reply.position, reply.size)
-    
+
+    def get_title_block_info(self) -> TitleBlockInfo:
+        cmd = editor_commands_pb2.GetTitleBlockInfo()
+        cmd.document.CopyFrom(self._doc)
+        return TitleBlockInfo(self._kicad.send(cmd, base_types_pb2.TitleBlockInfo))
+
+    @overload
+    def expand_text_variables(self, text: str) -> str:
+        ...
+
+    @overload
+    def expand_text_variables(self, text: List[str]) -> List[str]:
+        ...
+
+    def expand_text_variables(self, text: Union[str, List[str]]) -> Union[str, List[str]]:
+        command = project_commands_pb2.ExpandTextVariables()
+        command.document.CopyFrom(self._doc)
+        if isinstance(text, list):
+            command.text.extend(text)
+        else:
+            command.text.append(text)
+        response = self._kicad.send(command, project_commands_pb2.ExpandTextVariablesResponse)
+        return (
+            [text for text in response.text]
+            if isinstance(text, list)
+            else response.text[0]
+            if len(response.text) > 0
+            else ""
+        )
+
+    @overload
+    def get_item_bounding_box(
+        self, items: BoardItem, include_text: bool = False
+    ) -> Optional[Box2]: ...
+
+    @overload
+    def get_item_bounding_box(
+        self, items: Sequence[BoardItem], include_text: bool = False
+    ) -> List[Optional[Box2]]: ...
+
+    def get_item_bounding_box(
+        self,
+        items: Union[BoardItem, Sequence[BoardItem]],
+        include_text: bool = False
+    ) -> Union[Optional[Box2], List[Optional[Box2]]]:
+        """Gets the KiCad-calculated bounding box for an item or items, returning None if the item
+        does not exist or has no bounding box"""
+        cmd = editor_commands_pb2.GetBoundingBox()
+        cmd.header.document.CopyFrom(self._doc)
+        cmd.mode = (
+            editor_commands_pb2.BoundingBoxMode.BBM_ITEM_AND_CHILD_TEXT
+            if include_text
+            else editor_commands_pb2.BoundingBoxMode.BBM_ITEM_ONLY
+        )
+
+        if isinstance(items, BoardItem):
+            cmd.items.append(items.id)
+        else:
+            cmd.items.extend([i.id for i in items])
+
+        response = self._kicad.send(cmd, editor_commands_pb2.GetBoundingBoxResponse)
+
+        if isinstance(items, BoardItem):
+            return Box2.from_proto(response.boxes[0]) if len(response.boxes) == 1 else None
+
+        item_to_bbox = {item: bbox for item, bbox in zip(response.items, response.boxes)}
+        return [
+            Box2.from_proto(box)
+            for box in (item_to_bbox.get(item.id, None) for item in items)
+            if box is not None
+        ]
+
+    @overload
+    def get_pad_shapes_as_polygons(
+        self, pads: Pad, layer: BoardLayer.ValueType = BoardLayer.BL_F_Cu
+    ) -> Optional[PolygonWithHoles]: ...
+
+    @overload
+    def get_pad_shapes_as_polygons(
+        self, pads: Sequence[Pad], layer: BoardLayer.ValueType = BoardLayer.BL_F_Cu
+    ) -> List[Optional[PolygonWithHoles]]: ...
+
+    def get_pad_shapes_as_polygons(
+        self, pads: Union[Pad, Sequence[Pad]], layer: BoardLayer.ValueType = BoardLayer.BL_F_Cu
+    ) -> Union[Optional[PolygonWithHoles], List[Optional[PolygonWithHoles]]]:
+        cmd = board_commands_pb2.GetPadShapeAsPolygon()
+        cmd.board.CopyFrom(self._doc)
+        cmd.layer = layer
+
+        if isinstance(pads, Pad):
+            cmd.pads.append(pads.id)
+        else:
+            cmd.pads.extend([pad.id for pad in pads])
+
+        response = self._kicad.send(cmd, board_commands_pb2.PadShapeAsPolygonResponse)
+
+        if isinstance(pads, Pad):
+            return PolygonWithHoles(response.polygons[0]) if len(response.polygons) == 1 else None
+
+        pad_to_polygon = {pad: polygon for pad, polygon in zip(response.pads, response.polygons)}
+        return [
+            PolygonWithHoles(p)
+            for p in (pad_to_polygon.get(pad.id, None) for pad in pads)
+            if p is not None
+        ]
+
     def interactive_move(self, items: Union[KIID, Iterable[KIID]]):
         cmd = board_commands_pb2.InteractiveMoveItems()
         cmd.board.CopyFrom(self._doc)
@@ -285,3 +441,27 @@ class Board:
         cmd.position.CopyFrom(position.proto)
         cmd.tolerance = tolerance
         return self._kicad.send(cmd, HitTestResponse).result == HitTestResult.HTR_HIT
+
+    def get_visible_layers(self) -> Sequence[board_types_pb2.BoardLayer.ValueType]:
+        cmd = board_commands_pb2.GetVisibleLayers()
+        cmd.board.CopyFrom(self._doc)
+        response = self._kicad.send(cmd, board_commands_pb2.BoardLayers)
+        return response.layers
+
+    def set_visible_layers(self, layers: Sequence[board_types_pb2.BoardLayer.ValueType]):
+        cmd = board_commands_pb2.SetVisibleLayers()
+        cmd.board.CopyFrom(self._doc)
+        cmd.layers.extend(layers)
+        self._kicad.send(cmd, Empty)
+
+    def get_active_layer(self) -> board_types_pb2.BoardLayer.ValueType:
+        cmd = board_commands_pb2.GetActiveLayer()
+        cmd.board.CopyFrom(self._doc)
+        response = self._kicad.send(cmd, board_commands_pb2.BoardLayerResponse)
+        return response.layer
+
+    def set_active_layer(self, layer: board_types_pb2.BoardLayer.ValueType):
+        cmd = board_commands_pb2.SetActiveLayer()
+        cmd.board.CopyFrom(self._doc)
+        cmd.layer = layer
+        self._kicad.send(cmd, Empty)