kicad-python 0.2.0__tar.gz → 0.3.0__tar.gz

{kicad_python-0.2.0 → kicad_python-0.3.0}/PKG-INFO

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: kicad-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: KiCad API Python Bindings
-Home-page: https://kicad.org/
 License: MIT
 Author: The KiCad Development Team
 Requires-Python: >=3.9,<4.0
@@ -14,9 +13,12 @@ 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: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Dist: deprecated (>=1.2,<2.0)
 Requires-Dist: protobuf (>=5.29,<6.0)
 Requires-Dist: pynng (>=0.8.0,<0.9.0)
+Project-URL: Homepage, https://kicad.org/
 Project-URL: Repository, https://gitlab.com/kicad/code/kicad-python
 Description-Content-Type: text/markdown
 
@@ -81,8 +83,11 @@ This should print out the version of KiCad you have connected to.
 
 ## 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.
+The documentation created from this repository (via the `docs` directory and the docstrings in the
+source code) is hosted at https://docs.kicad.org/kicad-python-main
+
+Many things are still not documented or underdocumented -- contributions that expand the
+documentation or add docstrings are welcomed.
 
 ## Examples
 
@@ -93,6 +98,20 @@ plugins, copy or symlink them into the appropriate plugins path in order for KiC
 
 ## Release History
 
+### 0.3.0 (March 29, 2025)
+
+- Add support for footprint mounting style attribute (#19) (Thanh Duong, !10)
+- Added `visible` property to `Field` and deprecate it from `TextAttributes` to match KiCad changes
+- Improve version checking functions(Lucas Gerads, !11)
+- Add missing board layers User.10 through User.45 (#23)
+- Improve padstack-related APIs for creating new vias and pads (#21)
+- Change arc angle methods to return normalized angles; add degrees versions (#22)
+- Add `board.get_origin` and `board.set_origin` (#20)
+- Add `ArcTrack.length` (Thanh Duong, !12)
+- Add `Footprint.models` (#31)
+- Fix ability to create new graphic shapes on boards
+- Fix the return value of `Board.update_items` and document it (#35)
+
 ### 0.2.0 (February 19, 2025)
 
 - Updates for KiCad 9.0.0 release

{kicad_python-0.2.0 → kicad_python-0.3.0}/README.md

@@ -59,8 +59,11 @@ This should print out the version of KiCad you have connected to.
 
 ## 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.
+The documentation created from this repository (via the `docs` directory and the docstrings in the
+source code) is hosted at https://docs.kicad.org/kicad-python-main
+
+Many things are still not documented or underdocumented -- contributions that expand the
+documentation or add docstrings are welcomed.
 
 ## Examples
 
@@ -71,6 +74,20 @@ plugins, copy or symlink them into the appropriate plugins path in order for KiC
 
 ## Release History
 
+### 0.3.0 (March 29, 2025)
+
+- Add support for footprint mounting style attribute (#19) (Thanh Duong, !10)
+- Added `visible` property to `Field` and deprecate it from `TextAttributes` to match KiCad changes
+- Improve version checking functions(Lucas Gerads, !11)
+- Add missing board layers User.10 through User.45 (#23)
+- Improve padstack-related APIs for creating new vias and pads (#21)
+- Change arc angle methods to return normalized angles; add degrees versions (#22)
+- Add `board.get_origin` and `board.set_origin` (#20)
+- Add `ArcTrack.length` (Thanh Duong, !12)
+- Add `Footprint.models` (#31)
+- Fix ability to create new graphic shapes on boards
+- Fix the return value of `Board.update_items` and document it (#35)
+
 ### 0.2.0 (February 19, 2025)
 
 - Updates for KiCad 9.0.0 release

{kicad_python-0.2.0 → kicad_python-0.3.0}/build/lib/kipy/board.py

@@ -71,6 +71,9 @@ from kipy.proto.board.board_pb2 import (    # noqa
 from kipy.proto.board.board_types_pb2 import ( #noqa
     BoardLayer
 )
+from kipy.proto.board.board_commands_pb2 import ( #noqa
+    BoardOriginType
+)
 
 class BoardLayerGraphicsDefaults(Wrapper):
     """The default properties for graphic items added on a given class of board layer"""
@@ -444,10 +447,13 @@ class Board:
         command = editor_commands_pb2.SaveSelectionToString()
         return self._kicad.send(command, editor_commands_pb2.SavedSelectionResponse).contents
 
-    def update_items(self, items: Union[BoardItem, Sequence[BoardItem]]):
+    def update_items(self, items: Union[BoardItem, Sequence[BoardItem]]) -> List[BoardItem]:
         """Updates the properties of one or more items on the board.  The items must already exist
         on the board, and are matched by internal UUID.  All other properties of the items are
-        updated from those passed in this call."""
+        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)"""
         command = UpdateItems()
         command.header.document.CopyFrom(self._doc)
 
@@ -457,12 +463,16 @@ class Board:
             command.items.extend([pack_any(i.proto) for i in items])
 
         if len(command.items) == 0:
-            return
+            return []
 
-        return [
-            unwrap(result.item)
-            for result in self._kicad.send(command, UpdateItemsResponse).updated_items
-        ]
+        return self._to_concrete_items(
+            [
+                unwrap(result.item)
+                for result in self._kicad.send(
+                    command, UpdateItemsResponse
+                ).updated_items
+            ]
+        )
 
     def remove_items(self, items: Union[BoardItem, Sequence[BoardItem]]):
         """Deletes one or more items from the board"""
@@ -608,6 +618,26 @@ class Board:
         cmd.document.CopyFrom(self._doc)
         return TitleBlockInfo(self._kicad.send(cmd, base_types_pb2.TitleBlockInfo))
 
+    def get_origin(self, origin_type: board_commands_pb2.BoardOriginType.ValueType) -> Vector2:
+        """Retrieves the specified (grid or drill/place) board origin
+
+        .. versionadded:: 0.3.0"""
+        cmd = board_commands_pb2.GetBoardOrigin()
+        cmd.board.CopyFrom(self._doc)
+        cmd.type = origin_type
+        return Vector2(self._kicad.send(cmd, base_types_pb2.Vector2))
+
+    def set_origin(self, origin_type: board_commands_pb2.BoardOriginType.ValueType,
+                   origin: Vector2):
+        """Sets the specified (grid or drill/place) board origin
+
+        .. versionadded:: 0.3.0"""
+        cmd = board_commands_pb2.SetBoardOrigin()
+        cmd.board.CopyFrom(self._doc)
+        cmd.type = origin_type
+        cmd.origin.CopyFrom(origin.proto)
+        self._kicad.send(cmd, Empty)
+
     @overload
     def expand_text_variables(self, text: str) -> str:
         ...

{kicad_python-0.2.0 → kicad_python-0.3.0}/build/lib/kipy/board_types.py

@@ -51,12 +51,14 @@ from kipy.geometry import (
     arc_end_angle,
 )
 from kipy.util import unpack_any
-from kipy.util.board_layer import is_copper_layer
+from kipy.util.board_layer import is_copper_layer, iter_copper_layers
 from kipy.util.units import from_mm
 from kipy.wrapper import Item, Wrapper
 
 # Re-exported protobuf enum types
 from kipy.proto.board.board_types_pb2 import (  # noqa
+    PSS_CIRCLE,
+    PST_NORMAL,
     BoardLayer,
     ChamferedRectCorners,
     DrillShape,
@@ -264,6 +266,21 @@ class ArcTrack(BoardItem):
     def end_angle(self) -> Optional[float]:
         return arc_end_angle(self.start, self.mid, self.end)
 
+    def length(self) -> float:
+        """Calculates arc track length in nanometers
+
+        :return: The length of the arc, or the distance between the start and end points if the
+                 arc is degenerate
+        .. versionadded:: 0.3.0"""
+        start = self.start_angle()
+        end = self.end_angle()
+
+        if start is None or end is None:
+            return (self.end - self.start).length()
+
+        delta_angle = abs(end - start)
+        return delta_angle*self.radius()
+
     def bounding_box(self) -> Box2:
         box = Box2()
         box.merge(self.start)
@@ -327,10 +344,12 @@ class BoardSegment(BoardShape, Segment):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "segment"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.segment.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "segment"
-        Segment.__init__(self, self._proto.shape)
+        Segment.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -351,10 +370,12 @@ class BoardArc(BoardShape, Arc):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "arc"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.arc.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "arc"
-        Arc.__init__(self, self._proto.shape)
+        Arc.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -375,10 +396,12 @@ class BoardCircle(BoardShape, Circle):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "circle"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.circle.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "circle"
-        Circle.__init__(self, self._proto.shape)
+        Circle.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -399,10 +422,12 @@ class BoardRectangle(BoardShape, Rectangle):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "rectangle"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.rectangle.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "rectangle"
-        Rectangle.__init__(self, self._proto.shape)
+        Rectangle.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -423,10 +448,12 @@ class BoardPolygon(BoardShape, Polygon):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "polygon"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.polygon.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "polygon"
-        Polygon.__init__(self, self._proto.shape)
+        Polygon.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -447,10 +474,12 @@ class BoardBezier(BoardShape, Bezier):
         self._proto = board_types_pb2.BoardGraphicShape()
 
         if proto is not None:
+            assert proto.shape.WhichOneof("geometry") == "bezier"
             self._proto.CopyFrom(proto)
+        else:
+            self._proto.shape.bezier.SetInParent()
 
-        assert self._proto.shape.WhichOneof("geometry") == "bezier"
-        Bezier.__init__(self, self._proto.shape)
+        Bezier.__init__(self, proto_ref=self._proto.shape)
 
     def __repr__(self) -> str:
         net_repr = (
@@ -652,6 +681,17 @@ class Field(BoardItem):
     def text(self, text: BoardText):
         self._proto.text.CopyFrom(text.proto)
 
+    @property
+    def visible(self) -> bool:
+        """
+        .. versionadded:: 0.3.0 with KiCad 9.0.1
+        """
+        return self._proto.visible
+
+    @visible.setter
+    def visible(self, visible: bool):
+        self._proto.visible = visible
+
 
 class ThermalSpokeSettings(Wrapper):
     def __init__(
@@ -1004,6 +1044,26 @@ class PadStack(BoardItem):
     def type(self, type: board_types_pb2.PadStackType.ValueType):
         self._proto.type = type
 
+        layer_map = {layer.layer: layer for layer in self._proto.copper_layers}
+
+        required_layers = {
+            board_types_pb2.PadStackType.PST_NORMAL: [BoardLayer.BL_F_Cu],
+            board_types_pb2.PadStackType.PST_FRONT_INNER_BACK: [
+                BoardLayer.BL_F_Cu,
+                BoardLayer.BL_In1_Cu,
+                BoardLayer.BL_B_Cu,
+            ],
+            board_types_pb2.PadStackType.PST_CUSTOM: [layer for layer in iter_copper_layers()]
+        }.get(type, [])
+
+        for layer in layer_map.keys():
+            if layer not in required_layers:
+                self._proto.copper_layers.remove(layer_map[layer])
+
+        for layer in required_layers:
+            if layer not in layer_map:
+                self._add_copper_layer(layer)
+
     @property
     def layers(self) -> Sequence[BoardLayer.ValueType]:
         return self._proto.layers
@@ -1071,6 +1131,10 @@ class PadStack(BoardItem):
             return self.back_outer_layers.solder_mask_mode == SolderMaskMode.SMM_MASKED
         return False
 
+    def _add_copper_layer(self, layer: BoardLayer.ValueType) -> board_types_pb2.PadStackLayer:
+        self._proto.copper_layers.append(board_types_pb2.PadStackLayer())
+        self._proto.copper_layers[-1].layer = layer
+        return self._proto.copper_layers[-1]
 
 class Pad(BoardItem):
     def __init__(self, proto: Optional[board_types_pb2.Pad] = None):
@@ -1078,6 +1142,8 @@ class Pad(BoardItem):
 
         if proto is not None:
             self._proto.CopyFrom(proto)
+        else:
+            self.padstack.type = PST_NORMAL
 
     @property
     def id(self) -> KIID:
@@ -1122,6 +1188,9 @@ class Via(BoardItem):
 
         if proto is not None:
             self._proto.CopyFrom(proto)
+        else:
+            self.type = ViaType.VT_THROUGH
+            self.padstack.type = PST_NORMAL
 
     def __repr__(self) -> str:
         return (
@@ -1157,16 +1226,61 @@ class Via(BoardItem):
 
     @property
     def type(self) -> ViaType.ValueType:
+        """The type of the via (through, blind/buried, or micro)
+
+        Setting this property will also update the padstack drill start and end layers as a
+        side effect.
+
+        .. versionadded:: 0.3.0 with KiCad 9.0.1
+        """
         return self._proto.type
 
     @type.setter
     def type(self, type: ViaType.ValueType):
         self._proto.type = type
 
+        if (
+            type == ViaType.VT_THROUGH
+            or self.padstack.drill.start_layer == BoardLayer.BL_UNKNOWN
+            or self.padstack.drill.end_layer == BoardLayer.BL_UNKNOWN
+        ):
+            self.padstack.drill.start_layer = BoardLayer.BL_F_Cu
+            self.padstack.drill.end_layer = BoardLayer.BL_B_Cu
+
     @property
     def padstack(self) -> PadStack:
         return PadStack(proto_ref=self._proto.pad_stack)
 
+    @property
+    def diameter(self) -> int:
+        """A helper property to get or set the diameter of the via on all copper layers.
+
+        Warning: only makes sense if the via's padstack mode is PST_NORMAL.  This will return the
+        pad diameter on the front copper layer otherwise.  Setting this property will set the
+        padstack mode to PST_NORMAL as a side-effect.
+
+        To get or set the diameter for other padstack types, use the padstack property directly.
+
+        .. versionadded:: 0.3.0 with KiCad 9.0.1"""
+        if len(self.padstack.copper_layers) == 0:
+            raise ValueError("Unexpected empty padstack for via!")
+
+        return self.padstack.copper_layers[0].size.x
+
+    @diameter.setter
+    def diameter(self, diameter: int):
+        self.padstack.type = PST_NORMAL
+        self.padstack.copper_layers[0].size = Vector2.from_xy(diameter, diameter)
+
+    @property
+    def drill_diameter(self) -> int:
+        """The diameter of the via's drill (KiCad only supports circular drills in vias)"""
+        return self.padstack.drill.diameter.x
+
+    @drill_diameter.setter
+    def drill_diameter(self, diameter: int):
+        self.padstack.drill.diameter = Vector2.from_xy(diameter, diameter)
+
 
 class FootprintAttributes(Wrapper):
     """The built-in attributes that a Footprint or FootprintInstance may have"""
@@ -1209,6 +1323,27 @@ class FootprintAttributes(Wrapper):
     def exclude_from_position_files(self, exclude: bool):
         self._proto.exclude_from_position_files = exclude
 
+    @property
+    def do_not_populate(self) -> bool:
+        return self._proto.do_not_populate
+
+    @do_not_populate.setter
+    def do_not_populate(self, do_not_populate: bool):
+        self._proto.do_not_populate = do_not_populate
+
+    @property
+    def mounting_style(self) -> board_types_pb2.FootprintMountingStyle.ValueType:
+        """
+        The mounting style of the footprint (SMD, through-hole, or unspecified)
+
+        .. versionadded:: 0.3.0 with KiCad 9.0.1
+        """
+        return self._proto.mounting_style
+
+    @mounting_style.setter
+    def mounting_style(self, style: board_types_pb2.FootprintMountingStyle.ValueType):
+        self._proto.mounting_style = style
+
 class Footprint3DModel(Wrapper):
     """Represents a 3D model associated with a footprint"""
 
@@ -1218,6 +1353,14 @@ class Footprint3DModel(Wrapper):
         if proto is not None:
             self._proto.CopyFrom(proto)
 
+    def __repr__(self) -> str:
+        return (
+            f"Footprint3DModel(filename='{self.filename}', "
+            f"visisble={self.visible}, opacity={self.opacity}, "
+            f"rotation=({self.rotation.x}, {self.rotation.y}, {self.rotation.z}), "
+            f"scale=({self.scale.x}, {self.scale.y}, {self.scale.z}))"
+        )
+
     @property
     def filename(self) -> str:
         return self._proto.filename
@@ -1324,6 +1467,13 @@ class Footprint(Wrapper):
             or isinstance(item, Field)
         ]
 
+    @property
+    def models(self) -> Sequence[Footprint3DModel]:
+        """Returns all 3D models in the footprint
+
+        .. versionadded:: 0.3.0"""
+        return [item for item in self.items if isinstance(item, Footprint3DModel)]
+
     def add_item(self, item: Wrapper):
         any = Any()
         any.Pack(item.proto)
@@ -1810,9 +1960,10 @@ class AlignedDimension(Dimension):
         self._proto = board_types_pb2.Dimension()
 
         if proto is not None:
+            assert proto.WhichOneof("dimension_style") == "aligned"
             self._proto.CopyFrom(proto)
-
-        assert self._proto.WhichOneof("dimension_style") == "aligned"
+        else:
+            self._proto.aligned.SetInParent()
 
     def __repr__(self) -> str:
         return (
@@ -1858,9 +2009,10 @@ class OrthogonalDimension(Dimension):
         self._proto = board_types_pb2.Dimension()
 
         if proto is not None:
+            assert proto.WhichOneof("dimension_style") == "orthogonal"
             self._proto.CopyFrom(proto)
-
-        assert self._proto.WhichOneof("dimension_style") == "orthogonal"
+        else:
+            self._proto.orthogonal.SetInParent()
 
     def __repr__(self) -> str:
         return f"OrthogonalDimension(start={self.start}, end={self.end}, alignment={self.alignment})"
@@ -1910,9 +2062,10 @@ class RadialDimension(Dimension):
         self._proto = board_types_pb2.Dimension()
 
         if proto is not None:
+            assert proto.WhichOneof("dimension_style") == "radial"
             self._proto.CopyFrom(proto)
-
-        assert self._proto.WhichOneof("dimension_style") == "radial"
+        else:
+            self._proto.radial.SetInParent()
 
     def __repr__(self) -> str:
         return (
@@ -1950,9 +2103,10 @@ class LeaderDimension(Dimension):
         self._proto = board_types_pb2.Dimension()
 
         if proto is not None:
+            assert proto.WhichOneof("dimension_style") == "leader"
             self._proto.CopyFrom(proto)
-
-        assert self._proto.WhichOneof("dimension_style") == "leader"
+        else:
+            self._proto.leader.SetInParent()
 
     def __repr__(self) -> str:
         return (
@@ -1990,9 +2144,10 @@ class CenterDimension(Dimension):
         self._proto = board_types_pb2.Dimension()
 
         if proto is not None:
+            assert proto.WhichOneof("dimension_style") == "center"
             self._proto.CopyFrom(proto)
-
-        assert self._proto.WhichOneof("dimension_style") == "center"
+        else:
+            self._proto.center.SetInParent()
 
     def __repr__(self) -> str:
         return f"CenterDimension(center={self.center}, end={self.end})"

{kicad_python-0.2.0 → kicad_python-0.3.0/build/lib}/kipy/common_types.py

@@ -18,6 +18,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+from deprecated import deprecated
 from typing import Optional, Sequence
 from kipy.proto.common import types
 from kipy.proto.common.types import base_types_pb2
@@ -104,8 +105,21 @@ class TextAttributes(Wrapper):
         if proto is not None:
             self._proto.CopyFrom(proto)
 
+    def __repr__(self) -> str:
+        return (
+            f"TextAttributes(font_name={self.font_name}, angle={self.angle}, "
+            f"line_spacing={self.line_spacing}, italic={self.italic}, bold={self.bold}, "
+            f"underlined={self.underlined}, mirrored={self.mirrored}, multiline={self.multiline}, "
+            f"keep_upright={self.keep_upright}, size={self.size})"
+        )
+
     @property
+    @deprecated("This property will always return True in KiCad 9, and will be removed in KiCad 10")
     def visible(self) -> bool:
+        """
+        .. deprecated:: 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
+        """
         return self._proto.visible
 
     @visible.setter
@@ -121,12 +135,13 @@ class TextAttributes(Wrapper):
         self._proto.font_name = font_name
 
     @property
-    def angle(self) -> types.Angle:
-        return self._proto.angle
+    def angle(self) -> float:
+        """The orientation of the text in degrees"""
+        return self._proto.angle.value_degrees
 
     @angle.setter
-    def angle(self, angle: types.Angle):
-        self._proto.angle.CopyFrom(angle)
+    def angle(self, angle: float):
+        self._proto.angle.value_degrees = angle
 
     @property
     def line_spacing(self) -> float:
@@ -137,12 +152,12 @@ class TextAttributes(Wrapper):
         self._proto.line_spacing = line_spacing
 
     @property
-    def stroke_width(self) -> types.Distance:
-        return self._proto.stroke_width
+    def stroke_width(self) -> int:
+        return self._proto.stroke_width.value_nm
 
     @stroke_width.setter
-    def stroke_width(self, stroke_width: types.Distance):
-        self._proto.stroke_width.CopyFrom(stroke_width)
+    def stroke_width(self, stroke_width: int):
+        self._proto.stroke_width.value_nm = stroke_width
 
     @property
     def italic(self) -> bool:
@@ -461,8 +476,9 @@ class GraphicShape(Wrapper):
 class Segment(GraphicShape):
     """Represents a base graphic segment (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)
@@ -496,8 +512,9 @@ class Segment(GraphicShape):
 class Arc(GraphicShape):
     """Represents a generic graphical arc (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)
@@ -569,8 +586,9 @@ class Arc(GraphicShape):
 class Circle(GraphicShape):
     """Represents a graphic circle (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)
@@ -608,8 +626,9 @@ class Circle(GraphicShape):
 class Rectangle(GraphicShape):
     """Represents a graphic rectangle (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)
@@ -640,8 +659,9 @@ class Rectangle(GraphicShape):
 class Polygon(GraphicShape):
     """Represents a graphic polygon (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)
@@ -666,8 +686,9 @@ class Polygon(GraphicShape):
 class Bezier(GraphicShape):
     """Represents a graphic bezier curve (not a board or schematic item)"""
 
-    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None):
-        self._graphic_proto = base_types_pb2.GraphicShape()
+    def __init__(self, proto: Optional[base_types_pb2.GraphicShape] = None,
+                 proto_ref: Optional[base_types_pb2.GraphicShape] = None):
+        self._graphic_proto = proto_ref if proto_ref is not None else base_types_pb2.GraphicShape()
 
         if proto is not None:
             self._graphic_proto.CopyFrom(proto)