From 37f96f1760acf6e63eab94718cdebe921382c2b0 Mon Sep 17 00:00:00 2001 From: palewire Date: Mon, 3 Nov 2025 09:27:34 -0500 Subject: [PATCH] docs: clarify LineWidth enum non-sequential style numbering Improve documentation for LineWidth enum to highlight that style numbers do not correspond to line thickness in sequential order. Added warnings and examples to prevent confusion where style3 is the thinnest (1px) and style2 is the thickest (4px), contrary to what the numbering suggests. Changes: - Enhanced docstring with clear attribute descriptions and warnings - Added inline comments on enum values showing pixel widths - Expanded Field description with concrete examples - Emphasized using enum values over raw strings to avoid confusion This addresses potential developer confusion when using raw API values where higher style numbers don't mean thicker lines. --- datawrapper/charts/enums/line_width.py | 34 +++++++++++++++----------- datawrapper/charts/line.py | 11 ++++++++- 2 files changed, 30 insertions(+), 15 deletions(-) diff --git a/datawrapper/charts/enums/line_width.py b/datawrapper/charts/enums/line_width.py index 76b960ca..78a79cb9 100644 --- a/datawrapper/charts/enums/line_width.py +++ b/datawrapper/charts/enums/line_width.py @@ -4,23 +4,29 @@ class LineWidth(str, Enum): """Line width options for line charts. - These values control the stroke width of lines in charts: - - THINNEST (style3) = 1px stroke width - - THIN (style0) = 2px stroke width (default) - - MEDIUM (style1) = 3px stroke width - - THICK (style2) = 4px stroke width - - INVISIBLE = hidden line + These values control the stroke width of lines in charts. + + ⚠️ IMPORTANT: The style numbers DO NOT increase with thickness! + + Attributes: + THINNEST (style3): 1px stroke width - thinnest line + THIN (style0): 2px stroke width - default, despite being style0 + MEDIUM (style1): 3px stroke width + THICK (style2): 4px stroke width - thickest line + INVISIBLE: Hidden line Examples: - >>> # Using enum (recommended - more readable) - >>> Line(column="sales", width=LineWidth.THICK) + >>> # Using enum (recommended - avoids confusion) + >>> Line(column="sales", width=LineWidth.THICK) # ✓ Clearly 4px + >>> Line(column="sales", width=LineWidth.THINNEST) # ✓ Clearly 1px - >>> # Using raw API values (also supported for backwards compatibility) - >>> Line(column="sales", width="style3") + >>> # Using raw API values (works but confusing) + >>> Line(column="sales", width="style2") # 4px (thick, not thin!) + >>> Line(column="sales", width="style3") # 1px (thinnest, not thickest!) """ - THINNEST = "style3" - THIN = "style0" - MEDIUM = "style1" - THICK = "style2" + THINNEST = "style3" # 1px - ⚠️ Highest number, thinnest line! + THIN = "style0" # 2px (default) + MEDIUM = "style1" # 3px + THICK = "style2" # 4px - ⚠️ Not style3! INVISIBLE = "invisible" diff --git a/datawrapper/charts/line.py b/datawrapper/charts/line.py index 742132a7..a395405c 100644 --- a/datawrapper/charts/line.py +++ b/datawrapper/charts/line.py @@ -315,7 +315,16 @@ def validate_interpolation( #: The width of the line (use LineWidth enum or raw API values) width: LineWidth | str = Field( default="style1", - description="The width of the line. Use LineWidth enum for readability or raw API values (style0, style1, style2, style3, invisible).", + description=( + "The width of the line. Use LineWidth enum for readability or raw API values " + "(style0, style1, style2, style3, invisible).\n\n" + "Examples:\n" + " Line(column='sales', width=LineWidth.THICK) # style2 = 4px\n" + " Line(column='sales', width='style2') # Also 4px\n" + " Line(column='sales', width=LineWidth.THINNEST) # style3 = 1px\n\n" + "⚠️ Note: style numbers don't increase with thickness! " + "style0=2px (thin), style1=3px (medium), style2=4px (thick), style3=1px (thinnest)" + ), ) #: The dashing of the line (use LineDash enum or raw API values)