Extra models

Model classes provide structured configuration for chart elements and features.

Annotations

Multiple Column Panels

Column Format

class datawrapper.charts.models.ColumnFormat(*, column: Annotated[str, MinLen(min_length=1)], type: Literal['auto', 'text', 'number', 'date'] = 'auto', ignore: bool = False, number_prepend: str = '', number_append: str = '', number_divisor: NumberDivisor | int | str = 0, number_format: DateFormat | NumberFormat | str = '-')[source]

Bases: BaseModel

A data class for the Datawrapper API’s ‘column_format’ attribute.

classmethod validate_number_divisor(v: NumberDivisor | int | str) → NumberDivisor | int | str[source]

Validate number_divisor is a valid value.

Accepts NumberDivisor enum values or raw API values (int or str).

column: str: “The name of the data column for the line”

ignore: bool: Whether to ignore the column

model_config = {'json_schema_extra': {'examples': [{'column': 'sales', 'ignore': False, 'number-append': '', 'number-prepend': '$', 'type': 'number'}]}, 'populate_by_name': True, 'strict': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_append: str: What to append after the number

number_divisor: NumberDivisor | int | str: Number divisor for scaling values (use NumberDivisor enum or raw API values)

number_format: DateFormat | NumberFormat | str: Number/date format for the column (use DateFormat or NumberFormat enum or raw format strings)

number_prepend: str: What to prepend before the number

type: Literal['auto', 'text', 'number', 'date']: The data type of the column

class datawrapper.charts.models.ColumnFormatList(*, formats: list[ColumnFormat] = <factory>)[source]

Bases: BaseModel

A wrapper for a list of ColumnFormat objects that handles API serialization.

The Datawrapper API expects column-format as a dictionary where column names are keys and format configs are values. This model handles the conversion between the user-friendly list format and the API’s dict format.

classmethod convert_from_dict_or_list(data: Any) → dict[str, Any][source]

Convert dict format (from API) or list format to internal structure.

Handles three input formats: 1. Dict with ‘formats’ key (already in correct format) 2. Dict without ‘formats’ key (API format - column names as keys) 3. List of ColumnFormat objects or dicts (direct list format)

serialize_to_dict() → dict[str, dict[str, Any]][source]

Serialize to API format (dict with column names as keys).

Converts the internal list format to the dictionary format expected by the Datawrapper API, filtering out default values.

formats: list[ColumnFormat]: The list of column format configurations

model_config = {'json_schema_extra': {'examples': [{'formats': [{'column': 'sales', 'number-prepend': '$', 'type': 'number'}, {'column': 'date', 'type': 'date'}]}]}, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Data Changes

DataChange models individual cell corrections made in Datawrapper’s Check & Describe tab. Datawrapper stores these corrections under metadata.data.changes as zero-based row/column indexes, the replacement value, an edit time in Unix milliseconds when available, and previous for overwritten cells. The previous field is optional because Datawrapper omits it for entries such as added-column headers.

Datawrapper’s developer docs show changes as a list. Existing API responses can also return an object keyed by internal change IDs, with fields such as id, ignored, and _index. Transform accepts both shapes and round-trips object-shaped API responses without converting them to lists.

Live API smoke verification for this behavior used an authorized unpublished Datawrapper test chart. The API accepted an object-map changes payload, returned that object-map shape on read-back, and preserved the relevant id, ignored, and _index fields after a Transform deserialize/serialize write-back. The documented list-shaped compatibility input was also accepted and read back as a list. The smoke restored the test chart’s corrections to an empty object and did not publish or verify behavior for production-facing charts.

chart = dw.BarChart(
    title="Corrected values",
    data=df,
    transformations=dw.Transform(
        changes=[
            dw.DataChange(
                row=9,
                column=3,
                value="1.7",
                time=1573134075869,
                previous="0.7",
            )
        ]
    ),
)

Line Configuration

For practical workflow guidance, examples, and migration notes, see the LineChart guide.

class datawrapper.charts.line.Line(*, column: str, title: str = '', interpolation: LineInterpolation | str = 'linear', width: LineWidth | str = 'style1', dash: LineDash | str | None = None, colorKey: bool = False, directLabel: bool = False, bgStroke: bool = False, symbols: LineSymbol | None = None, valueLabels: LineValueLabel | None = None, connectMissingPoints: bool = False)[source]

Bases: BaseModel

Configure a line on a Datawrapper line chart.

classmethod deserialize_model(line_name: str, line_config: dict) → dict[str, Any][source]

Deserialize API line config to Line initialization dict.

Parameters:

line_name – The column name for this line
line_config – The line configuration from the API

Returns:

Dictionary that can be used to initialize a Line instance

classmethod validate_dash(v: LineDash | str | None) → LineDash | str | None[source]

Validate dash is a valid value.

Accepts LineDash enum values, raw API string values, or None.

classmethod validate_interpolation(v: LineInterpolation | str) → LineInterpolation | str[source]: Validate that interpolation is a valid LineInterpolation value.

classmethod validate_width(v: LineWidth | str) → LineWidth | str[source]

Validate width is a valid value.

Accepts LineWidth enum values or raw API string values.

static serialize_model(line: Line) → dict[str, Any][source]

Serialize a Line instance to API format.

Parameters:: line – The Line instance to serialize
Returns:: Dictionary in the API’s expected format

color_key: bool: Whether or not to show in the color key

column: str: The name of the data column for the line

connect_missing_points: bool: Whether or not to connect missing points

dash: LineDash | str | None: The dashing of the line (use LineDash enum or raw API values)

direct_label: bool: Whether or not to show a direct label for the line in the right hand margin

interpolation: LineInterpolation | str: The interpolation method to use when drawing lines

model_config = {'populate_by_name': True, 'strict': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

outline: bool: Line outline

symbols: LineSymbol | None: Symbols to display on the line (None = disabled, object = enabled)

title: str: The title to display in tooltips and legends

value_labels: LineValueLabel | None: The value labels for the line (None = disabled, object = enabled)

width: LineWidth | str: The width of the line (use LineWidth enum or raw API values)

Bases: BaseModel

Configure the symbols for an individual line on a Datawrapper line chart.

Note: The presence of this object implies symbols are enabled. The enabled field is automatically set to True and should not be set to False.

classmethod validate_enabled(v: bool) → bool[source]: Validate that enabled is not explicitly set to False.

enabled: bool: Whether or not to show symbols (automatically set to True when object exists)

model_config = {'populate_by_name': True, 'strict': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

on: SymbolDisplay | str: Where to show the symbols

opacity: int | float: The opacity of the symbols between 0 and 1

shape: SymbolShape | str: The shape of the symbol

size: int | float: The size of the symbols

style: SymbolStyle | str: The style of the symbol

class datawrapper.charts.line.LineValueLabel(*, enabled: bool = True, last: bool = False, first: bool = False, showCircles: bool = False, maxInnerLabels: int = 0)[source]

Bases: BaseModel

Configure the value labels for an individual line on a Datawrapper line chart.

Note: The presence of this object implies value labels are enabled. The enabled field is automatically set to True and should not be set to False.

classmethod validate_enabled(v: bool) → bool[source]: Validate that enabled is not explicitly set to False.

enabled: bool: Whether to show the value labels (automatically set to True when object exists)

first: bool: Whether to show the first value label

last: bool: Whether to show the last value label

max_inner_labels: int: The maximum number of inner value labels to show

model_config = {'populate_by_name': True, 'strict': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

show_circles: bool: Whether to show circles at automatically drawn inner value labels