drawlib.charts.pie（円・ドーナツグラフ）

スライスの切り出し強調（explode）、ドーナツ中央の KPI テキスト（center_text）、狭小スライス（4% 未満）のラベル自動抑制、分離型凡例描画を備えた 2D 円・ドーナツグラフビルダーです。drawlib.charts.pie からインポートします（from drawlib.charts.pie import PieChart, Slice）。

from drawlib.canvas import save, setup
from drawlib.charts.pie import PieChart
from drawlib.shapes import rectangle
from drawlib.styles import Colors, Styles

setup(width=120, height=58)

card_style = Styles.Neutral.patch(shape_r=2.0, shape_line_color=Colors.Gray4, shape_fill_color=Colors.White)
rectangle((31.5, 29.0), width=53.0, height=50.0, style=card_style)
rectangle((88.5, 29.0), width=53.0, height=50.0, style=card_style)

# Left: Solid Exploded PieChart
solid = PieChart(
    radius=12.5,
    width=48.0,
    height=37.0,
    hole_ratio=0.0,
    title="Exploded Budget Share",
    title_style=Styles.BlackBold.patch(text_size=11.5),
    value_text_style=Styles.BlackBold.patch(text_size=10.0),
    value_format="{:.0f}%",
)
solid.add_slice("AI Core", 44.0, style=Styles.PrimaryFlat, explode=1.8)
solid.add_slice("Infra", 32.0, style=Styles.PrimaryNeutral)
solid.add_slice("Tooling", 24.0, style=Styles.SecondaryNeutral)
solid.draw(xy=(7.5, 13.5))
solid.draw_legend(xy=(12.5, 8.5), text_style=Styles.DarkBold.patch(text_size=10.0), orientation="horizontal", item_gap=2.0)

# Right: Donut PieChart with Center KPI Badge
donut = PieChart(
    radius=12.5,
    width=48.0,
    height=37.0,
    hole_ratio=0.60,
    center_text="99.9%\nSLA",
    center_text_style=Styles.BlackBold.patch(text_size=10.5),
    title="Donut Traffic Mix",
    title_style=Styles.BlackBold.patch(text_size=11.5),
    value_text_style=Styles.BlackBold.patch(text_size=10.0),
    value_format="{:.0f}%",
)
donut.add_slice("Edge", 48.0, style=Styles.PrimaryFlat)
donut.add_slice("API", 32.0, style=Styles.PrimaryNeutral)
donut.add_slice("Batch", 20.0, style=Styles.SecondaryNeutral)
donut.draw(xy=(64.5, 13.5))
donut.draw_legend(xy=(71.5, 8.5), text_style=Styles.DarkBold.patch(text_size=10.0), orientation="horizontal", item_gap=2.2)

save()

typeDrawDirection#

Slice.draw_ratio（0.0〜1.0）と組み合わせて円・ドーナツスライスの部分描画方向を指定するリテラル型です。

DrawDirection = Literal["bottom_to_top", "left_to_right"]

typeFormatterType#

スライス上の構成比ラベル（PieChart.value_format）のフォーマットを指定するユニオン型です。

FormatterType = str | Callable[[float], str] | None

• str: スライスの百分率（0.0〜100.0）を受け取る Python フォーマット文字列（デフォルトは "{:.1f}%"）。
• Callable[[float], str]: 百分率 float を受け取り文字列を返すカスタム関数（例: lambda pct: f"{pct:.0f}%"）。
• None: コンパクトな自動パーセンテージ表記を使用します。

classPieChart#

全体（$100%$）に対する各要素の構成比を可視化する 2D 円グラフ・ドーナツグラフビルダーです。

• 座標アンカー: draw(xy=..., align="bottom_left") のデフォルトは左下 (x0, y0)（align="center" 指定時は中心）。
• 狭小スライスの文字重なり防止: 合計の $4%$ 未満のスライスでは、ラベル同士の衝突を防ぐためインライン数値ラベル（value_text_style）が自動的に省略されます。

class PieChart:
    def __init__(
        self,
        *,
        radius: float = 20.0,
        hole_ratio: float = 0.0,
        start_angle: float = 90.0,
        clockwise: bool = True,
        value_text_style: Style | None = None,
        value_format: FormatterType = "{:.1f}%",
        center_text: str = "",
        center_text_style: Style | None = None,
        background_style: Style | None = None,
        title: str = "",
        title_style: Style | None = None,
        width: float | None = None,
        height: float | None = None,
    ) -> None: ...

パラメータ#

メソッド・プロパティ#

add_slice

def add_slice(
    self,
    name: str,
    value: float,
    style: Style,
    explode: float = 0.0,
    legend_text_style: Style | None = None,
    *,
    show: bool = True,
    draw_ratio: float = 1.0,
    draw_direction: DrawDirection = "left_to_right",
) -> Slice

比率スライスを追加し、変更可能な Slice インスタンスを返します。explode > 0.0 を指定すると二等分角方向に沿って外側へオフセット強調されます。

draw

def draw(
    self,
    xy: tuple[float, float] = (0.0, 0.0),
    *,
    radius: float | None = None,
    width: float | None = None,
    height: float | None = None,
    align: Literal["bottom_left", "center"] = "bottom_left",
    scale: float = 1.0,
) -> None

基準座標 xy（デフォルトは左下 (x0, y0)、align="center" で中心）に円・ドーナツグラフを描画します。一時的な radius・width・height・scale 上書きに対応します。

draw_legend

def draw_legend(
    self,
    xy: tuple[float, float],
    text_style: Style,
    orientation: Literal["vertical", "horizontal"] = "vertical",
    swatch_width: float = 2.4,
    swatch_height: float = 1.2,
    item_gap: float = 4.0,
    *,
    scale: float = 1.0,
) -> None

座標 xy に独立したスライス凡例を描画します（"vertical" または "horizontal"）。

get_size

def get_size(self) -> tuple[float, float]

この円形チャートコンテナの全体寸法 (width, height) を算出して返します。

slices *(property)*

@property
def slices(self) -> list[Slice]

登録済みの Slice インスタンスのリストコピーを返します。

classSlice#

PieChart 内の単一スライス（扇形）を表す変更可能なデータモデルです。

class Slice:
    def __init__(
        self,
        name: str,
        value: float,
        style: Style,
        explode: float = 0.0,
        legend_text_style: Style | None = None,
        show: bool = True,
        draw_ratio: float = 1.0,
        draw_direction: DrawDirection = "left_to_right",
    ) -> None: ...

パラメータ・属性#