add arch, pie shapes and charts module with donut chart

Author: dronperminov

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0 (2025-05-15)
+
+### Added
+- New shape `Arch`: a `blockArc`-like ring with configurable thickness, and angular range.
+- New shape `Pie`: a filled sector of a circle.
+- New module: `charts` with initial support for `DonutChart`, a circular chart with customizable radii, gaps, and total value label.
+- New example: `charts/donut_chart.py` showcasing `DonutChart` usage
+
+### Changed
+- `Ellipse` now uses `width` and `height` instead of `dx` and `dy` for clarity and consistency.
+
+### Fixed
+- Minor internal refactoring for better consistency of shape parameter naming.
+
+
 ## 0.1.4 (2025-05-14)
 
 - Added `family` field to `FontStyle` for specifying font family (default: `"Calibri"`)

README.md

@@ -37,7 +37,7 @@ with Presentation(presentation_path="empty.pptx") as presentation:
     ))
 
     presentation.add(shape=Ellipse(
-        x=20, y=2, dx=4, dy=4,
+        x=20, y=2, width=4, height=4,
         fill=FillStyle(color="#7699d4")
     ))
 
@@ -74,9 +74,11 @@ Currently, `pptx-shapes` supports the following geometric shapes:
 |------------------------------------------------------------------------------------------------------|-------------|------------------------------------------------------------------------------|
 | [Line](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/line.py)           | `Line`      | Straight line between two points                                             |
 | [Arrow](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/arrow.py)         | `Arrow`     | Straight arrow between two points                                            |
-| [Arc](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/arc.py)             | `Arc`       | Curved segment defined by the bounding box and start/end angles.             |
-| [Ellipse](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/ellipse.py)     | `Ellipse`   | Ellipse defined by top-left corner, diameters, and rotation angle            |
+| [Arc](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/arc.py)             | `Arc`       | Curved segment defined by the bounding box and start/end angles              |
+| [Arch](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/arch.py)           | `Arch`      | Ring-shaped arc defined by the bounding box, thickness and start/end angles  |
+| [Ellipse](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/ellipse.py)     | `Ellipse`   | Ellipse defined by top-left corner, size, and rotation angle                 |
 | [Rectangle](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/rectangle.py) | `Rectangle` | Rectangle defined by top-left corner, size, corner radius and rotation angle |
+| [Pie](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/pie.py)             | `Pie`       | Filled sector of a circle, defined by the bounding box and start/end angles  |
 | [Polygon](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/polygon.py)     | `Polygon`   | Arbitrary polygon defined by a list of points and rotation angle             |
 | [TextBox](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/textbox.py)     | `TextBox`   | Text container with position, size, rotation, and font style                 |
 | [Group](https://github.com/dronperminov/pptx-shapes/blob/master/pptx_shapes/shapes/group.py)         | `Group`     | A group of multiple shapes                                                   |
@@ -148,24 +150,52 @@ Arc(
 * `stroke`: optional `StrokeStyle` for the border
 
 
+### Arch
+
+A ring-shaped arc defined by the bounding box, thickness, and angular range. It is based on PowerPoint’s `blockArc` shape.
+
+```python
+Arch(
+    x=5, y=5,           # center (cm)
+    width=3, height=3,  # sizes (cm)
+    thickness=1,        # ring thickness (cm)
+    start_angle=0,      # start angle (degrees)
+    end_angle=270,      # end angle (degrees)
+    angle=45,           # optional rotation angle (degrees)
+    fill=...,           # optional FillStyle
+    stroke=...          # optional StrokeStyle
+)
+```
+
+#### Parameters
+
+* `x`, `y`: top-left corner coordinates in centimeters
+* `width`, `height`: sizes in centimeters
+* `thickness`: width of the ring (distance between outer and inner radius) in centimeters
+* `start_angle`, `end_angle`: arc range in degrees (default `0` and `180`)
+* `angle`: the rotation angle of the arch in degrees (default is `0`)
+* `fill`: optional `FillStyle` to fill the arch
+* `stroke`: optional `StrokeStyle` for the border
+
+
 ### Ellipse
 
-An ellipse is defined by its top-left corner and the diameters in horizontal and vertical directions. It can be rotated by a given angle.
+An ellipse is defined by its top-left corner and its width and height. It can be rotated by a given angle.
 
 ```python
 Ellipse(
-    x=2, y=3.5, # top-left angle (cm)
-    dx=4, dy=6, # diameters (cm)
-    angle=30,   # optional rotation angle (degrees)
-    fill=...,   # optional FillStyle
-    stroke=...  # optional StrokeStyle
+    x=2, y=3.5,        # top-left angle (cm)
+    width=4, height=6, # sizes (cm)
+    angle=30,          # optional rotation angle (degrees)
+    fill=...,          # optional FillStyle
+    stroke=...         # optional StrokeStyle
 )
 ```
 
 #### Parameters
 * `x`, `y`: top-left corner coordinates in centimeters
-* `dx`, `dy`: diameters in centimeters
-* `angle`: the rotation angle of the ellipse in degrees (default is `0`).
+* `width`, `height`: sizes in centimeters
+* `angle`: the rotation angle of the ellipse in degrees (default is `0`)
 * `fill`: optional `FillStyle` to fill the ellipse
 * `stroke`: optional `StrokeStyle` for the border
 
@@ -192,6 +222,33 @@ Rectangle(
 * `fill`: fill style
 * `stroke`: stroke style
 
+
+### Pie
+
+A filled sector of an ellipse, defined by its bounding box and angular range.
+
+```python
+Pie(
+    x=5, y=5,           # center (cm)
+    width=3, height=3,  # sizes (cm)
+    start_angle=0,      # start angle (degrees)
+    end_angle=270,      # end angle (degrees)
+    angle=45,           # optional rotation angle (degrees)
+    fill=...,           # optional FillStyle
+    stroke=...          # optional StrokeStyle
+)
+```
+
+#### Parameters
+
+* `x`, `y`: top-left corner coordinates in centimeters
+* `width`, `height`: sizes in centimeters
+* `start_angle`, `end_angle`: the angular range of the slice in degrees (default `0` and `180`)
+* `angle`: the rotation angle of the pie in degrees (default is `0`)
+* `fill`: optional `FillStyle` to fill the arch
+* `stroke`: optional `StrokeStyle` for the border
+
+
 ### Polygon
 
 A polygon can be an arbitrary shape defined by a list of points. It can also be rotated by an angle.
@@ -440,6 +497,16 @@ This example demonstrates how to use different font families and styles in `Text
 Download .pptx: [examples/text_boxes.pptx](https://github.com/dronperminov/pptx-shapes/blob/master/examples/text_boxes.pptx)
 
 
+### Example 6. Donut charts example
+
+This example demonstrates how to use `DonutChart` from `charts` module
+([examples/charts/donut_chart.py](https://github.com/dronperminov/pptx-shapes/blob/master/examples/charts/donut_chart.py)).
+
+![Slide example](https://github.com/dronperminov/pptx-shapes/raw/master/examples/charts/donut_chart.png)
+
+Download .pptx: [examples/charts/donut_chart.pptx](https://github.com/dronperminov/pptx-shapes/blob/master/examples/charts/donut_chart.pptx)
+
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/dronperminov/pptx-shapes/blob/master/CHANGELOG.md) for version history.

examples/basic.pptx

@@ -18,7 +18,7 @@ def main() -> None:
         ))
 
         # ellipses
-        presentation.add(shape=Ellipse(x=20, y=2, dx=4, dy=4, fill=FillStyle(color="#7699d4")))
+        presentation.add(shape=Ellipse(x=20, y=2, width=4, height=4, fill=FillStyle(color="#7699d4")))
 
         # arrows
         presentation.add(shape=Arrow(x1=10, y1=9, x2=14, y2=11, start_type=ArrowType.OVAL, end_type=ArrowType.ARROW, stroke=StrokeStyle(thickness=2)))
@@ -61,9 +61,9 @@ def main() -> None:
         ]))
 
         presentation.add(shape=Group(shapes=[
-            Ellipse(x=4.5, y=6.0, dx=2.0, dy=3.5, fill=FillStyle(color="#dd7373", opacity=0.5), stroke=StrokeStyle(color="black", thickness=2, opacity=0.75)),
-            Ellipse(x=3.0, y=8.5, dx=3.5, dy=2.0, fill=FillStyle(color="#dd7373", opacity=0.25), stroke=StrokeStyle(color="black", opacity=0.25), angle=-45),
-            Ellipse(x=5.0, y=8.5, dx=3.5, dy=2.0, fill=FillStyle(color="#dd7373", opacity=0.85), stroke=StrokeStyle(color="black", opacity=0.85), angle=45)
+            Ellipse(x=4.5, y=6.0, width=2.0, height=3.5, fill=FillStyle(color="#dd7373", opacity=0.5), stroke=StrokeStyle(color="black", thickness=2, opacity=0.75)),
+            Ellipse(x=3.0, y=8.5, width=3.5, height=2.0, fill=FillStyle(color="#dd7373", opacity=0.25), stroke=StrokeStyle(color="black", opacity=0.25), angle=-45),
+            Ellipse(x=5.0, y=8.5, width=3.5, height=2.0, fill=FillStyle(color="#dd7373", opacity=0.85), stroke=StrokeStyle(color="black", opacity=0.85), angle=45)
         ]))
 
         presentation.add(shape=Group(shapes=[

examples/basic.py

@@ -0,0 +1,32 @@
+from pptx_shapes import Presentation
+from pptx_shapes.charts.donut import DonutChart, DonutChartConfig, GapConfig, LabelConfig
+from pptx_shapes.shapes import Group
+
+
+def main() -> None:
+    x0, y0 = 1, 2
+    gap = 1
+
+    configs = [
+        DonutChartConfig(inner_radius=3, outer_radius=5, gap=GapConfig(thickness=2), label=LabelConfig(size=75)),
+        DonutChartConfig(inner_radius=0, outer_radius=5, gap=GapConfig(thickness=2), label=None),
+        DonutChartConfig(inner_radius=4.5, outer_radius=5, gap=None, label=None),
+    ]
+
+    data = [
+        {"value": 180, "color": "#f39c12"},
+        {"value": 95, "color": "#2ecc71"},
+        {"value": 150, "color": "#e74c3c"},
+        {"value": 75, "color": "#3498db"}
+    ]
+
+    with Presentation(presentation_path="../empty.pptx") as presentation:
+        for i, config in enumerate(configs):
+            chart = DonutChart(config=config)
+            presentation.add(shape=Group(chart.render(data=data, x=x0 + i * (gap + chart.size), y=y0)))
+
+        presentation.save("donut_chart.pptx")
+
+
+if __name__ == "__main__":
+    main()