flet-charts 0.2.0.dev35__tar.gz → 0.2.0.dev84__tar.gz

{flet_charts-0.2.0.dev35/src/flet_charts.egg-info → flet_charts-0.2.0.dev84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet-charts
-Version: 0.2.0.dev35
+Version: 0.2.0.dev84
 Summary: A Flet extension for creating interactive charts and graphs.
 Author-email: Flet contributors <hello@flet.dev>
 License-Expression: Apache-2.0
@@ -12,13 +12,6 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: flet>=0.70.0.dev0
-Provides-Extra: all
-Requires-Dist: plotly>=6.0.1; extra == "all"
-Requires-Dist: matplotlib>=3.10.1; extra == "all"
-Provides-Extra: plotly
-Requires-Dist: plotly>=6.0.1; extra == "plotly"
-Provides-Extra: matplotlib
-Requires-Dist: matplotlib>=3.10.1; extra == "matplotlib"
 Dynamic: license-file
 
 # flet-charts
@@ -48,7 +41,9 @@ This package supports the following platforms:
 | Android  |     ✅     |
 | Web      |     ✅     |
 
-## Installation
+## Usage
+
+### Installation
 
 To install the `flet-charts` package and add it to your project dependencies:
 
@@ -67,3 +62,7 @@ To install the `flet-charts` package and add it to your project dependencies:
     ```bash
     poetry add flet-charts
     ```
+
+### Examples
+
+For examples, see [these](./examples).

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/README.md

@@ -25,7 +25,9 @@ This package supports the following platforms:
 | Android  |     ✅     |
 | Web      |     ✅     |
 
-## Installation
+## Usage
+
+### Installation
 
 To install the `flet-charts` package and add it to your project dependencies:
 
@@ -44,3 +46,7 @@ To install the `flet-charts` package and add it to your project dependencies:
     ```bash
     poetry add flet-charts
     ```
+
+### Examples
+
+For examples, see [these](./examples).

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flet-charts"
-version = "0.2.0.dev35"
+version = "0.2.0.dev84"
 description = "A Flet extension for creating interactive charts and graphs."
 readme = "README.md"
 authors = [{ name = "Flet contributors", email = "hello@flet.dev" }]
@@ -19,11 +19,6 @@ Issues = "https://github.com/flet-dev/flet-charts/issues"
 [tool.setuptools.package-data]
 "flutter.flet_charts" = ["**/*"]
 
-[project.optional-dependencies]
-all = ["plotly>=6.0.1", "matplotlib>=3.10.1"]
-plotly = ["plotly>=6.0.1"]
-matplotlib = ["matplotlib>=3.10.1"]
-
 [dependency-groups]
 test = [
     "pytest >=7.2.0",
@@ -57,6 +52,7 @@ docs = [
     "markdown-exec[ansi] >=1.11.0",
     "pydocstyle >=6.3.0",
     "linkcheckmd >=1.4.0",
+    "mkdocs-external-images",
     { include-group = 'docs-coverage' },
 ]
 all = [
@@ -64,6 +60,10 @@ all = [
     { include-group = 'docs' },
 ]
 
+[tool.uv.sources]
+mkdocs-external-images = { git = "https://github.com/flet-dev/mkdocs-external-images", tag = "v0.2.0" }
+
+
 [tool.ruff]
 line-length = 88
 target-version = "py39"

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/__init__.py

@@ -1,37 +1,44 @@
-from .bar_chart import (
+from flet_charts.bar_chart import (
     BarChart,
     BarChartEvent,
     BarChartTooltip,
     BarChartTooltipDirection,
 )
-from .bar_chart_group import BarChartGroup
-from .bar_chart_rod import BarChartRod, BarChartRodTooltip
-from .bar_chart_rod_stack_item import BarChartRodStackItem
-from .chart_axis import ChartAxis, ChartAxisLabel
-from .line_chart import (
+from flet_charts.bar_chart_group import BarChartGroup
+from flet_charts.bar_chart_rod import BarChartRod, BarChartRodTooltip
+from flet_charts.bar_chart_rod_stack_item import BarChartRodStackItem
+from flet_charts.chart_axis import ChartAxis, ChartAxisLabel
+from flet_charts.line_chart import (
     LineChart,
     LineChartEvent,
     LineChartEventSpot,
     LineChartTooltip,
 )
-from .line_chart_data import LineChartData
-from .line_chart_data_point import LineChartDataPoint, LineChartDataPointTooltip
-from .matplotlib_chart import MatplotlibChart
-from .pie_chart import PieChart, PieChartEvent
-from .pie_chart_section import PieChartSection
-from .plotly_chart import PlotlyChart
-from .scatter_chart import ScatterChart, ScatterChartEvent, ScatterChartTooltip
-from .scatter_chart_spot import ScatterChartSpot, ScatterChartSpotTooltip
-from .types import (
+from flet_charts.line_chart_data import LineChartData
+from flet_charts.line_chart_data_point import (
+    LineChartDataPoint,
+    LineChartDataPointTooltip,
+)
+from flet_charts.matplotlib_chart import MatplotlibChart
+from flet_charts.pie_chart import PieChart, PieChartEvent
+from flet_charts.pie_chart_section import PieChartSection
+from flet_charts.plotly_chart import PlotlyChart
+from flet_charts.scatter_chart import (
+    ScatterChart,
+    ScatterChartEvent,
+    ScatterChartTooltip,
+)
+from flet_charts.scatter_chart_spot import ScatterChartSpot, ScatterChartSpotTooltip
+from flet_charts.types import (
     ChartCirclePoint,
     ChartCrossPoint,
     ChartDataPointTooltip,
     ChartEventType,
     ChartGridLines,
-    ChartHorizontalAlignment,
     ChartPointLine,
     ChartPointShape,
     ChartSquarePoint,
+    HorizontalAlignment,
 )
 
 __all__ = [
@@ -50,10 +57,10 @@ __all__ = [
     "ChartDataPointTooltip",
     "ChartEventType",
     "ChartGridLines",
-    "ChartHorizontalAlignment",
     "ChartPointLine",
     "ChartPointShape",
     "ChartSquarePoint",
+    "HorizontalAlignment",
     "LineChart",
     "LineChartData",
     "LineChartDataPoint",

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/bar_chart.py

@@ -4,9 +4,9 @@ from typing import Any, Optional
 
 import flet as ft
 
-from .bar_chart_group import BarChartGroup
-from .chart_axis import ChartAxis
-from .types import ChartEventType, ChartGridLines
+from flet_charts.bar_chart_group import BarChartGroup
+from flet_charts.chart_axis import ChartAxis
+from flet_charts.types import ChartEventType, ChartGridLines, HorizontalAlignment
 
 __all__ = [
     "BarChart",
@@ -43,12 +43,14 @@ class BarChartTooltip:
     The border radius of the tooltip.
     """
 
-    margin: Optional[ft.Number] = None
+    margin: ft.Number = 16
     """
     Applies a bottom margin for showing tooltip on top of rods.
     """
 
-    padding: Optional[ft.PaddingValue] = None
+    padding: ft.PaddingValue = field(
+        default_factory=lambda: ft.Padding.symmetric(vertical=8, horizontal=16)
+    )
     """
     Applies a padding for showing contents inside the tooltip.
     """
@@ -58,14 +60,14 @@ class BarChartTooltip:
     Restricts the tooltip's width.
     """
 
-    rotate_angle: Optional[ft.Number] = None
+    rotation: ft.Number = 0.0
     """
     The rotation angle of the tooltip.
     """
 
-    horizontal_offset: Optional[ft.Number] = None
+    horizontal_offset: ft.Number = 0.0
     """
-    Applies horizontal offset for showing tooltip.
+    The horizontal offset of this tooltip.
     """
 
     border_side: Optional[ft.BorderSide] = None
@@ -73,20 +75,69 @@ class BarChartTooltip:
     The tooltip border side.
     """
 
-    fit_inside_horizontally: Optional[bool] = None
+    fit_inside_horizontally: bool = False
     """
     Forces the tooltip to shift horizontally inside the chart, if overflow happens.
     """
 
-    fit_inside_vertically: Optional[bool] = None
+    fit_inside_vertically: bool = False
     """
     Forces the tooltip to shift vertically inside the chart, if overflow happens.
     """
 
-    direction: Optional[BarChartTooltipDirection] = None
-    """
-    Controls showing tooltip on top or bottom, default is auto.
-    """
+    direction: BarChartTooltipDirection = BarChartTooltipDirection.AUTO
+    """
+    Defines the direction of this tooltip.
+    """
+
+    horizontal_alignment: HorizontalAlignment = HorizontalAlignment.CENTER
+    """
+    Defines the horizontal alignment of this tooltip.
+    """
+
+    def copy(
+        self,
+        *,
+        bgcolor: Optional[ft.ColorValue] = None,
+        border_radius: Optional[ft.BorderRadiusValue] = None,
+        margin: Optional[ft.Number] = None,
+        padding: Optional[ft.PaddingValue] = None,
+        max_width: Optional[ft.Number] = None,
+        rotation: Optional[ft.Number] = None,
+        horizontal_offset: Optional[ft.Number] = None,
+        border_side: Optional[ft.BorderSide] = None,
+        fit_inside_horizontally: Optional[bool] = None,
+        fit_inside_vertically: Optional[bool] = None,
+        direction: Optional[BarChartTooltipDirection] = None,
+        horizontal_alignment: Optional[HorizontalAlignment] = None,
+    ) -> "BarChartTooltip":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return BarChartTooltip(
+            bgcolor=bgcolor if bgcolor is not None else self.bgcolor,
+            border_radius=border_radius
+            if border_radius is not None
+            else self.border_radius,
+            margin=margin if margin is not None else self.margin,
+            padding=padding if padding is not None else self.padding,
+            max_width=max_width if max_width is not None else self.max_width,
+            rotation=rotation if rotation is not None else self.rotation,
+            horizontal_offset=horizontal_offset
+            if horizontal_offset is not None
+            else self.horizontal_offset,
+            border_side=border_side if border_side is not None else self.border_side,
+            fit_inside_horizontally=fit_inside_horizontally
+            if fit_inside_horizontally is not None
+            else self.fit_inside_horizontally,
+            fit_inside_vertically=fit_inside_vertically
+            if fit_inside_vertically is not None
+            else self.fit_inside_vertically,
+            direction=direction if direction is not None else self.direction,
+            horizontal_alignment=horizontal_alignment
+            if horizontal_alignment is not None
+            else self.horizontal_alignment,
+        )
 
 
 @dataclass
@@ -117,7 +168,7 @@ class BarChart(ft.ConstrainedControl):
     """
     Draws a bar chart.
 
-    ![Overview](assets/bar-chart/diagram.svg)
+    ![Overview](assets/bar-chart-diagram.svg)
     """
 
     groups: list[BarChartGroup] = field(default_factory=list)
@@ -125,9 +176,17 @@ class BarChart(ft.ConstrainedControl):
     The list of [`BarChartGroup`][(p).]s to draw.
     """
 
-    spacing: Optional[ft.Number] = None
+    group_spacing: ft.Number = 16.0
+    """
+    A amount of space between bar [`groups`][..].
     """
-    A amount of space between bar groups.
+
+    group_alignment: ft.MainAxisAlignment = ft.MainAxisAlignment.SPACE_EVENLY
+    """
+    A alignment of the bar [`groups`][..] within this chart.
+
+    If set to [`MainAxisAlignment.CENTER`][flet.MainAxisAlignment.CENTER],
+    the space between the `groups` can be specified using [`group_spacing`][..].
     """
 
     animation: ft.AnimationValue = field(
@@ -137,9 +196,6 @@ class BarChart(ft.ConstrainedControl):
     )
     """
     Controls chart implicit animation.
-
-    Value is of [`AnimationValue`](https://flet.dev/docs/reference/types/animationvalue)
-    type.
     """
 
     interactive: bool = True
@@ -202,14 +258,18 @@ class BarChart(ft.ConstrainedControl):
     The maximum displayed value for Y axis.
     """
 
-    tooltip: Optional[BarChartTooltip] = None
+    tooltip: Optional[BarChartTooltip] = field(
+        default_factory=lambda: BarChartTooltip()
+    )
     """
-    The tooltip configuration for the chart.
+    The tooltip configuration for this chart.
+
+    If set to `None`, tooltips will not shown throughout this chart.
     """
 
     on_event: Optional[ft.EventHandler[BarChartEvent]] = None
     """
-    Fires when a bar is hovered or clicked.
+    Called when an event occurs on this chart, such as a click or hover.
     """
 
     def __post_init__(self, ref: Optional[ft.Ref[Any]]):

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/bar_chart_group.py

@@ -3,7 +3,7 @@ from typing import Optional
 
 import flet as ft
 
-from .bar_chart_rod import BarChartRod
+from flet_charts.bar_chart_rod import BarChartRod
 
 __all__ = ["BarChartGroup"]
 

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/bar_chart_rod.py

@@ -1,10 +1,10 @@
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, Union
 
 import flet as ft
 
-from .bar_chart_rod_stack_item import BarChartRodStackItem
-from .types import ChartDataPointTooltip
+from flet_charts.bar_chart_rod_stack_item import BarChartRodStackItem
+from flet_charts.types import ChartDataPointTooltip
 
 __all__ = ["BarChartRod", "BarChartRodTooltip"]
 
@@ -22,6 +22,28 @@ class BarChartRodTooltip(ChartDataPointTooltip):
     When `None`, defaults to [`BarChartRod.to_y`][(p).].
     """
 
+    def copy(
+        self,
+        *,
+        text: Optional[str] = None,
+        text_style: Optional[ft.TextStyle] = None,
+        text_align: Optional[ft.TextAlign] = None,
+        text_spans: Optional[list[ft.TextSpan]] = None,
+        rtl: Optional[bool] = None,
+    ) -> "BarChartRodTooltip":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return BarChartRodTooltip(
+            text=text if text is not None else self.text,
+            text_style=text_style if text_style is not None else self.text_style,
+            text_align=text_align if text_align is not None else self.text_align,
+            text_spans=text_spans.copy()
+            if text_spans is not None
+            else (self.text_spans.copy() if self.text_spans is not None else None),
+            rtl=rtl if rtl is not None else self.rtl,
+        )
+
 
 @ft.control("BarChartRod")
 class BarChartRod(ft.BaseControl):
@@ -94,7 +116,9 @@ class BarChartRod(ft.BaseControl):
     [`BarChart.interactive`][(p).] is set to `False`.
     """
 
-    tooltip: BarChartRodTooltip = field(default_factory=lambda: BarChartRodTooltip())
+    tooltip: Union[BarChartRodTooltip, str] = field(
+        default_factory=lambda: BarChartRodTooltip()
+    )
     """
     The rod's tooltip configuration for this rod.
     """
@@ -103,3 +127,11 @@ class BarChartRod(ft.BaseControl):
     """
     Whether a tooltip should be shown on top of hovered bar.
     """
+
+    def before_update(self):
+        super().before_update()
+        self._internals["tooltip"] = (
+            BarChartRodTooltip(text=self.tooltip)
+            if isinstance(self.tooltip, str)
+            else self.tooltip
+        )

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/chart_axis.py

@@ -1,5 +1,5 @@
 from dataclasses import field
-from typing import Optional, Union
+from typing import Optional
 
 import flet as ft
 
@@ -17,11 +17,9 @@ class ChartAxisLabel(ft.BaseControl):
     A value to draw label for.
     """
 
-    label: Optional[Union[ft.Control, str]] = None
+    label: Optional[ft.StrOrControl] = None
     """
-    The label to display for the specified `value`.
-    
-    Can be a string or a `Control`.
+    The label to display for the specified [`value`][..].
     """
 
 
@@ -38,12 +36,12 @@ class ChartAxis(ft.BaseControl):
 
     title_size: ft.Number = 16
     """
-    Width or height of title area.
+    The size of title area.
     """
 
     show_labels: bool = True
     """
-    Whether to display the `labels` along the axis. 
+    Whether to display the [`labels`][..] along the axis.
     If `labels` is empty then automatic labels are displayed.
     """
 
@@ -55,10 +53,32 @@ class ChartAxis(ft.BaseControl):
 
     label_spacing: Optional[ft.Number] = None
     """
-    The interval between automatic labels.
+    The spacing/interval between labels.
+
+    If a value is not set, a suitable value
+    will be automatically calculated and used.
     """
 
     label_size: ft.Number = 22
     """
-    Width or height of labels area.
+    The maximum space for each label in [`labels`][..].
+
+    Each label will stretch to fit this space.
+    """
+
+    show_min: bool = True
+    """
+    Whether to display a label for the minimum value
+    independent of the sampling interval.
     """
+
+    show_max: bool = True
+    """
+    Whether to display a label for the maximum value
+    independent of the sampling interval.
+    """
+
+    def before_update(self):
+        super().before_update()
+        if self.label_spacing == 0:
+            raise ValueError("label_spacing cannot be 0")

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/line_chart.py

@@ -3,9 +3,9 @@ from typing import Any, Optional
 
 import flet as ft
 
-from .chart_axis import ChartAxis
-from .line_chart_data import LineChartData
-from .types import ChartEventType, ChartGridLines
+from flet_charts.chart_axis import ChartAxis
+from flet_charts.line_chart_data import LineChartData
+from flet_charts.types import ChartEventType, ChartGridLines, HorizontalAlignment
 
 __all__ = [
     "LineChart",
@@ -27,6 +27,20 @@ class LineChartEventSpot:
     The line's point index or `-1` if no point was hovered.
     """
 
+    def copy(
+        self,
+        *,
+        bar_index: Optional[int] = None,
+        spot_index: Optional[int] = None,
+    ) -> "LineChartEventSpot":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return LineChartEventSpot(
+            bar_index=bar_index if bar_index is not None else self.bar_index,
+            spot_index=spot_index if spot_index is not None else self.spot_index,
+        )
+
 
 @dataclass
 class LineChartEvent(ft.Event["LineChart"]):
@@ -72,7 +86,7 @@ class LineChartTooltip:
     Restricts the tooltip's width.
     """
 
-    rotate_angle: ft.Number = 0.0
+    rotation: ft.Number = 0.0
     """
     The tooltip's rotation angle in degrees.
     """
@@ -84,7 +98,7 @@ class LineChartTooltip:
 
     border_side: ft.BorderSide = field(default_factory=lambda: ft.BorderSide.none())
     """
-    The tooltip's border side.
+    Defines the borders of this tooltip.
     """
 
     fit_inside_horizontally: bool = False
@@ -102,13 +116,60 @@ class LineChartTooltip:
     Whether to force the tooltip container to top of the line.
     """
 
+    horizontal_alignment: HorizontalAlignment = HorizontalAlignment.CENTER
+    """
+    The horizontal alignment of this tooltip.
+    """
+
+    def copy(
+        self,
+        *,
+        bgcolor: Optional[ft.ColorValue] = None,
+        border_radius: Optional[ft.BorderRadiusValue] = None,
+        margin: Optional[ft.Number] = None,
+        padding: Optional[ft.PaddingValue] = None,
+        max_width: Optional[ft.Number] = None,
+        rotation: Optional[ft.Number] = None,
+        horizontal_offset: Optional[ft.Number] = None,
+        border_side: Optional[ft.BorderSide] = None,
+        fit_inside_horizontally: Optional[bool] = None,
+        fit_inside_vertically: Optional[bool] = None,
+        show_on_top_of_chart_box_area: Optional[bool] = None,
+    ) -> "LineChartTooltip":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return LineChartTooltip(
+            bgcolor=bgcolor if bgcolor is not None else self.bgcolor,
+            border_radius=border_radius
+            if border_radius is not None
+            else self.border_radius,
+            margin=margin if margin is not None else self.margin,
+            padding=padding if padding is not None else self.padding,
+            max_width=max_width if max_width is not None else self.max_width,
+            rotation=rotation if rotation is not None else self.rotation,
+            horizontal_offset=horizontal_offset
+            if horizontal_offset is not None
+            else self.horizontal_offset,
+            border_side=border_side if border_side is not None else self.border_side,
+            fit_inside_horizontally=fit_inside_horizontally
+            if fit_inside_horizontally is not None
+            else self.fit_inside_horizontally,
+            fit_inside_vertically=fit_inside_vertically
+            if fit_inside_vertically is not None
+            else self.fit_inside_vertically,
+            show_on_top_of_chart_box_area=show_on_top_of_chart_box_area
+            if show_on_top_of_chart_box_area is not None
+            else self.show_on_top_of_chart_box_area,
+        )
+
 
 @ft.control("LineChart")
 class LineChart(ft.ConstrainedControl):
     """
     Draws a line chart.
 
-    ![Overview](assets/line-chart/diagram.svg)
+    ![Overview](assets/line-chart-diagram.svg)
     """
 
     data_series: list[LineChartData] = field(default_factory=list)
@@ -215,9 +276,13 @@ class LineChart(ft.ConstrainedControl):
     Defines the maximum displayed value for Y axis.
     """
 
-    tooltip: LineChartTooltip = field(default_factory=lambda: LineChartTooltip())
+    tooltip: Optional[LineChartTooltip] = field(
+        default_factory=lambda: LineChartTooltip()
+    )
     """
     The tooltip configuration for this chart.
+
+    If set to `None`, no tooltips will be shown throughout this chart.
     """
 
     on_event: Optional[ft.EventHandler[LineChartEvent]] = None

{flet_charts-0.2.0.dev35 → flet_charts-0.2.0.dev84}/src/flet_charts/line_chart_data.py

@@ -3,8 +3,8 @@ from typing import Optional, Union
 
 import flet as ft
 
-from .line_chart_data_point import LineChartDataPoint
-from .types import ChartPointLine, ChartPointShape
+from flet_charts.line_chart_data_point import LineChartDataPoint
+from flet_charts.types import ChartPointLine, ChartPointShape
 
 __all__ = ["LineChartData"]
 
@@ -19,7 +19,7 @@ class LineChartData(ft.BaseControl):
 
     curved: bool = False
     """
-    Set to `True` to draw chart line as a curve.
+    Whether to draw this chart line as a curve.
     """
 
     color: ft.ColorValue = ft.Colors.CYAN
@@ -49,7 +49,7 @@ class LineChartData(ft.BaseControl):
 
     prevent_curve_over_shooting_threshold: ft.Number = 10.0
     """
-    Threshold to prevent overshooting algorithm.
+    Threshold for [`prevent_curve_over_shooting`][..] algorithm.
     """
 
     dash_pattern: Optional[list[int]] = None
@@ -128,3 +128,29 @@ class LineChartData(ft.BaseControl):
     """
     Defines the appearance and shape of a selected line point.
     """
+
+    curve_smoothness: ft.Number = 0.35
+    """
+    Defines the smoothness of a curve line,
+    when [`curved`][..] is set to `True`.
+    """
+
+    rounded_stroke_join: bool = False
+    """
+    Whether to draw rounded line joins.
+    """
+
+    step_direction: Optional[ft.Number] = None
+    """
+    Determines the direction of each step.
+
+    If not `None`, this chart will be drawn as a
+    [Step Line Chart](https://docs.anychart.com/Basic_Charts/Step_Line_Chart).
+
+    Below are some typical values:
+
+    - `0.0`: Go to the next spot directly, with the current point's y value.
+    - `0.5`: Go to the half with the current spot y, and with the next spot y
+        for the rest.
+    - `1.0`: Go to the next spot y and direct line to the next spot.
+    """