composeui 0.1.0__py3-none-any.whl

composeui/core/chartimage.py

@@ -0,0 +1,336 @@
+"""A chart as a report's figure, drawn by matplotlib alike on every backend, or with none.
+
+A screen chart follows its window and theme; a report's figure has its page's size and
+fonts, and a light background. So the figure is drawn from the `ChartView`'s data, e.g.
+by a batch run writing a report's figures:
+
+    save_chart_image(chart, Path("pressure.pdf"), ImageOptions(width_mm=80))
+
+It needs the `report` extra (matplotlib), imported only by these functions; without it
+they raise an `ImportError` naming the extra, and `is_available` is False.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import math
+from typing import TYPE_CHECKING, Any
+
+import attrs
+
+from composeui.core.view import ChartKind, ChartView, LineStyle
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+__all__ = ["ImageOptions", "chart_figure", "save_chart_image"]
+
+
+#: the formats of an image, by its file's suffix: vector ones, then PNG, a raster
+FORMATS = ("pdf", "svg", "eps", "png")
+MEDIA_TYPES = {
+    "pdf": "application/pdf",
+    "svg": "image/svg+xml",
+    "eps": "application/postscript",
+    "png": "image/png",
+}
+#: Okabe and Ito's colors, told apart with color blindness too, the yellow last: it is
+#: faint on white
+SERIES_COLORS = (
+    "#0072B2",
+    "#D55E00",
+    "#009E73",
+    "#CC79A7",
+    "#E69F00",
+    "#56B4E9",
+    "#000000",
+    "#F0E442",
+)
+#: a dash pattern, a marker and a hatch per series: printed in black and white, a figure
+#: still tells its series apart
+LINE_STYLES: tuple[Any, ...] = (
+    "-",
+    (0, (5, 2)),
+    (0, (5, 2, 1, 2)),
+    (0, (1, 1.5)),
+    (0, (8, 2, 2, 2)),
+    (0, (3, 1, 1, 1, 1, 1)),
+)
+MARKERS = ("o", "s", "^", "D", "v", "P", "X", "*")
+HATCHES = ("", "//", "..", "xx", "\\\\", "oo", "--", "++")
+#: a reference line's color, unless it has its own: the axes'
+REFERENCE_LINE_COLOR = "#333333"
+#: a reference line's dash pattern, by its style
+REFERENCE_LINE_STYLES: dict[LineStyle, Any] = {
+    LineStyle.SOLID: "-",
+    LineStyle.DASHED: (0, (5, 3)),
+    LineStyle.DOTTED: (0, (1, 2)),
+    LineStyle.DASH_DOT: (0, (5, 2, 1, 2)),
+}
+#: the series a legend lists inside the axes; more, and it goes beside them
+_INSIDE_LEGEND_MAX = 3
+_MM_PER_INCH = 25.4
+
+
+@attrs.frozen
+class ImageOptions:
+    """How a chart's image looks: its size, fonts and range."""
+
+    #: an A4 page's text width
+    width_mm: float = 160
+    height_mm: float = 100
+    #: the resolution of a PNG; a vector image has none
+    dpi: int = 300
+    #: points, as the report's body text
+    font_size: float = 9
+    #: a report usually captions its figures itself
+    show_title: bool = False
+    #: the region shown, e.g. the one the user zoomed into; None: all the data
+    x_range: tuple[float, float] | None = None
+    y_range: tuple[float, float] | None = None
+
+
+#: an image for a report's page, in its body text's font size
+DEFAULT_OPTIONS = ImageOptions()
+
+
+def is_available() -> bool:
+    """Check whether matplotlib, the `report` extra, is installed."""
+    return importlib.util.find_spec("matplotlib") is not None
+
+
+def _require() -> None:
+    if not is_available():
+        msg = (
+            "A chart's image is drawn by matplotlib: install composeui's `report` extra"
+            " (pip install 'composeui[report]')."
+        )
+        raise ImportError(msg)
+
+
+@contextlib.contextmanager
+def image_style(options: ImageOptions = DEFAULT_OPTIONS) -> Iterator[None]:
+    """Draw and save figures with the options' fonts while the block runs.
+
+    Text stays text in a vector image: TrueType fonts in a PDF or EPS, ``<text>`` in an
+    SVG. So its labels can still be edited or searched. Matplotlib's global settings are
+    left as they were: wrap a `chart_figure` saved with `Figure.savefig` in it too.
+    """
+    _require()
+    import matplotlib as mpl  # noqa: PLC0415
+
+    size = options.font_size
+    with mpl.rc_context(
+        {
+            "pdf.fonttype": 42,
+            "ps.fonttype": 42,
+            "svg.fonttype": "none",
+            "font.size": size,
+            "axes.titlesize": size * 1.1,
+            "axes.labelsize": size,
+            "xtick.labelsize": size * 0.9,
+            "ytick.labelsize": size * 0.9,
+            "legend.fontsize": size * 0.9,
+            "figure.facecolor": "white",
+            "axes.facecolor": "white",
+            "savefig.facecolor": "white",
+            "axes.edgecolor": "#333333",
+            "axes.grid": True,
+            "grid.color": "#e5e5e5",
+            "grid.linewidth": 0.5,
+            "axes.axisbelow": True,
+        }
+    ):
+        yield
+
+
+def chart_figure(chart: ChartView, options: ImageOptions = DEFAULT_OPTIONS) -> Figure:
+    """Draw `chart` as a report's figure, which app code can add to before saving it.
+
+    Save it in `image_style` for its text to stay text, or with `save_chart_image`.
+    """
+    _require()
+    from matplotlib.figure import Figure  # noqa: PLC0415
+
+    with image_style(options):
+        figure = Figure(
+            figsize=(options.width_mm / _MM_PER_INCH, options.height_mm / _MM_PER_INCH),
+            dpi=options.dpi,
+            layout="constrained",
+        )
+        axes = figure.add_subplot()
+        if chart.kind is ChartKind.BAR:
+            _draw_bars(axes, chart)
+        else:
+            _draw_curves(axes, chart)
+        _draw_reference_lines(axes, chart)
+        if options.show_title and chart.title:
+            axes.set_title(chart.title)
+        axes.set_xlabel(ChartView.axis_label(chart.x_title, chart.x_unit))
+        axes.set_ylabel(ChartView.axis_label(chart.y_title, chart.y_unit))
+        if options.x_range is not None:
+            axes.set_xlim(*options.x_range)
+        if options.y_range is not None:
+            axes.set_ylim(*options.y_range)
+        _add_legend(figure, axes, chart)
+    return figure
+
+
+def _draw_curves(axes: Axes, chart: ChartView) -> None:
+    if chart.x_log:
+        axes.set_xscale("log")
+    if chart.y_log:
+        axes.set_yscale("log")
+    for index, series in enumerate(chart.series):
+        x, y = ChartView.drawn_points(series, x_log=chart.x_log, y_log=chart.y_log)
+        color = series.color or SERIES_COLORS[index % len(SERIES_COLORS)]
+        if ChartView.kind_of(series, chart.kind) is ChartKind.SCATTER:
+            axes.plot(
+                x,
+                y,
+                linestyle="none",
+                marker=MARKERS[index % len(MARKERS)],
+                markersize=4,
+                markeredgewidth=0.5,
+                markeredgecolor="white",
+                color=color,
+                label=series.name,
+            )
+        else:
+            # a NaN is a gap in a matplotlib line too; its path simplification keeps what
+            # shows at the figure's resolution, so a long series needs no thinning
+            axes.plot(
+                x,
+                y,
+                linestyle=LINE_STYLES[index % len(LINE_STYLES)],
+                linewidth=1.2,
+                color=color,
+                label=series.name,
+                # each value held until the next point
+                drawstyle="steps-post" if series.step else "default",
+            )
+            if series.fill:  # down to 0, e.g. a shape
+                axes.fill_between(
+                    x, y, 0, color=color, linewidth=0, step="post" if series.step else None
+                )
+
+
+def _draw_bars(axes: Axes, chart: ChartView) -> None:
+    count = len(chart.categories)
+    if chart.y_log:
+        axes.set_yscale("log")
+    for index, series in enumerate(chart.series):
+        heights = ChartView.bar_heights(series, count, y_log=chart.y_log)
+        offset, width = ChartView.bar_slot(index, len(chart.series))
+        drawn = [category for category, height in enumerate(heights) if math.isfinite(height)]
+        axes.bar(
+            [category + offset for category in drawn],
+            [heights[category] for category in drawn],
+            width=width,
+            color=series.color or SERIES_COLORS[index % len(SERIES_COLORS)],
+            hatch=HATCHES[index % len(HATCHES)],
+            edgecolor="white",
+            linewidth=0.5,
+            label=series.name,
+        )
+    axes.set_xticks(range(count), chart.categories)
+    axes.grid(visible=False, axis="x")
+
+
+def _draw_reference_lines(axes: Axes, chart: ChartView) -> None:
+    """Draw the chart's reference lines, labeled inside the axes, at their ends."""
+    x_log = chart.x_log and chart.kind is not ChartKind.BAR
+    for line in ChartView.drawn_lines(chart.reference_lines, x_log=x_log, y_log=chart.y_log):
+        color = line.color or REFERENCE_LINE_COLOR
+        style = REFERENCE_LINE_STYLES[line.style]
+        # not in the legend, which names the series: its label is beside it
+        if line.vertical:
+            axes.axvline(line.value, color=color, linestyle=style, linewidth=1)
+            # at its top, left of it (now, after the data): the x in data, the y in the
+            # axes' share
+            axes.annotate(
+                line.label,
+                (line.value, 1),
+                xycoords=axes.get_xaxis_transform(),
+                xytext=(-3, -3),
+                textcoords="offset points",
+                ha="right",
+                va="top",
+                color=color,
+            )
+        else:
+            axes.axhline(line.value, color=color, linestyle=style, linewidth=1)
+            # at its right end, over it
+            axes.annotate(
+                line.label,
+                (1, line.value),
+                xycoords=axes.get_yaxis_transform(),
+                xytext=(-3, 2),
+                textcoords="offset points",
+                ha="right",
+                va="bottom",
+                color=color,
+            )
+
+
+def _add_legend(figure: Figure, axes: Axes, chart: ChartView) -> None:
+    """Name the series, beside the axes when there are more than a few of them."""
+    if len(chart.series) == 0:
+        return
+    if len(chart.series) <= _INSIDE_LEGEND_MAX:
+        axes.legend(frameon=False)
+    else:
+        figure.legend(loc="outside right upper", frameon=False)
+
+
+def save_figure(figure: Figure, path: Path, options: ImageOptions = DEFAULT_OPTIONS) -> None:
+    """Save `figure` to `path`, in the format its suffix names (see `FORMATS`)."""
+    image_format = _format_of(path.suffix.lstrip("."))
+    with image_style(options):
+        figure.savefig(path, format=image_format, dpi=options.dpi)
+
+
+def save_chart_image(
+    chart: ChartView,
+    path: Path,
+    options: ImageOptions = DEFAULT_OPTIONS,
+) -> None:
+    """Save `chart`'s figure to `path`, in the format its suffix names (see `FORMATS`)."""
+    _format_of(path.suffix.lstrip("."))  # before drawing a figure it can't save
+    save_figure(chart_figure(chart, options), path, options)
+
+
+def chart_image_bytes(
+    chart: ChartView,
+    image_format: str,
+    options: ImageOptions = DEFAULT_OPTIONS,
+) -> bytes:
+    """Get `chart`'s figure as a file of `image_format`'s (see `FORMATS`), e.g. to send."""
+    image_format = _format_of(image_format)
+    figure = chart_figure(chart, options)
+    buffer = io.BytesIO()
+    with image_style(options):
+        figure.savefig(buffer, format=image_format, dpi=options.dpi)
+    return buffer.getvalue()
+
+
+def image_name(title: str, image_format: str) -> str:
+    """Get a file name for the image of a chart of `title`, as a file can be named."""
+    stem = "".join(
+        character if character.isalnum() or character in " -_" else "_" for character in title
+    ).strip()
+    return f"{stem or 'chart'}.{image_format}"
+
+
+def _format_of(image_format: str) -> str:
+    image_format = image_format.lower()
+    if image_format not in FORMATS:
+        msg = f"Cannot save a chart's image as {image_format!r}: choose one of {FORMATS}."
+        raise ValueError(msg)
+    return image_format

composeui/core/dataframesource.py

@@ -0,0 +1,307 @@
+"""A dataframe's rows in a large table, a chart or a map: pandas, Polars, PyArrow, lazy...
+
+`narwhals` (the ``dataframe`` extra) reads each library's frame through one API, so the
+library sorts and filters the rows with its own expressions, never row by row in Python.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+import narwhals as nw
+
+from composeui.core.signal import SignalNoArgs
+from composeui.core.view import (
+    MAP_LATITUDE_LIMIT,
+    ColumnKind,
+    FilterOperator,
+    MapPoint,
+    Series,
+    SourceColumn,
+    column_kind,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Mapping, Sequence
+
+    from narwhals.typing import IntoFrame
+
+    from composeui.core.view import Filter, Sort
+
+__all__ = ["DataFrameSource", "points_of", "series_of"]
+
+#: the column of the rows' ids added to a frame without an `id_column`
+ROW_ID = "__composeui_id"
+_EMPTY_KEY = "__composeui_empty"
+_SORT_KEY = "__composeui_key"
+
+_TEXT_OPERATORS = (
+    FilterOperator.CONTAINS,
+    FilterOperator.NOT_CONTAINS,
+    FilterOperator.TEXT_EQUAL,
+    FilterOperator.TEXT_NOT_EQUAL,
+    FilterOperator.STARTS_WITH,
+    FilterOperator.ENDS_WITH,
+)
+
+
+def _python_type(dtype: Any) -> Any:
+    """Get the Python type of a column's values, which sets how it sorts and filters."""
+    if dtype == nw.Boolean:
+        return bool
+    if dtype.is_integer():
+        return int
+    if dtype.is_numeric():  # a float or a decimal
+        return float
+    if dtype == nw.Datetime:
+        return datetime.datetime
+    if dtype == nw.Date:
+        return datetime.date
+    return str  # a text, a category, or a type shown as its text
+
+
+class DataFrameSource:
+    """A `TableSource` of a dataframe's rows, which a large table reads a window at a time.
+
+    Build it with any frame `narwhals` reads (pandas, Polars, PyArrow, a Polars
+    ``LazyFrame``...) and the headers by column: ``DataFrameSource(frame, {"lat":
+    T("Latitude")})``, every column under its name without them. A row's id is its
+    position in the frame, or its `id_column` when it has one: a lazy frame needs one, its
+    rows having no position of their own. Assign a new `frame` to change the rows, which
+    emits `changed`.
+
+    The frame's library sorts and filters: a text compares in lower case, which isn't
+    Python's ``casefold`` ("ß" doesn't find "SS"), and a ``/regex/`` is in the library's
+    syntax (Rust's ``regex`` for Polars, ``re`` for pandas). Equal cells, and the rows
+    unsorted, keep the frame's order.
+    """
+
+    def __init__(
+        self,
+        frame: IntoFrame,
+        headers: Optional[Mapping[str, str]] = None,
+        *,
+        id_column: Optional[str] = None,
+    ) -> None:
+        self._id_column = id_column
+        self._changed = SignalNoArgs()
+        self._native = frame
+        self._frame = self._wrapped(frame)
+        schema = self._frame.collect_schema()
+        names = list(schema) if headers is None else list(headers)
+        for name in [*names, *([] if id_column is None else [id_column])]:
+            if name not in schema:
+                msg = f"Cannot build a DataFrameSource: the frame has no column {name!r}."
+                raise ValueError(msg)
+        self._columns = {
+            name: SourceColumn(
+                name, name if headers is None else headers[name], _python_type(schema[name])
+            )
+            for name in names
+            if name != ROW_ID
+        }
+
+    @property
+    def columns(self) -> Sequence[SourceColumn]:
+        return tuple(self._columns.values())
+
+    @property
+    def changed(self) -> SignalNoArgs:
+        return self._changed
+
+    @property
+    def frame(self) -> IntoFrame:
+        """Get the frame given, in its own library."""
+        return self._native
+
+    @frame.setter
+    def frame(self, frame: IntoFrame) -> None:
+        wrapped = self._wrapped(frame)
+        self._native, self._frame = frame, wrapped
+        self._changed.emit()
+
+    @property
+    def _id(self) -> str:
+        return ROW_ID if self._id_column is None else self._id_column
+
+    def _wrapped(self, frame: IntoFrame) -> Union[nw.DataFrame[Any], nw.LazyFrame[Any]]:
+        wrapped = nw.from_native(frame)
+        if self._id_column is not None:
+            return wrapped
+        if isinstance(wrapped, nw.LazyFrame):
+            msg = "Cannot build a DataFrameSource of a lazy frame without an id_column."
+            raise TypeError(msg)
+        return wrapped.with_row_index(ROW_ID)
+
+    def count(self) -> int:
+        return int(_collected(self._frame.select(nw.len())).item())
+
+    def ordered_ids(
+        self, sort: Optional[Sort], search: str, filters: Mapping[str, Filter]
+    ) -> list[Hashable]:
+        for name in [*filters, *([] if sort is None else [sort.column])]:
+            self._column(name)
+        # the frame once: in a job, the main thread may assign a new one meanwhile
+        frame = self._frame
+        conditions = [
+            self._condition(self._column(name), row_filter) for name, row_filter in filters.items()
+        ]
+        needle = search.strip().casefold()
+        if needle != "":
+            texts = [
+                _text(name)
+                for name, column in self._columns.items()
+                if column_kind(column.type) is ColumnKind.TEXT
+            ]
+            if len(texts) == 0:
+                return []  # no text column holds it, as a `ListSource` finds
+            conditions.append(
+                nw.any_horizontal(
+                    *(text.str.contains(needle, literal=True) for text in texts),
+                    ignore_nulls=True,
+                )
+            )
+        if len(conditions) > 0:
+            frame = frame.filter(*conditions)
+        if sort is None:
+            ordered = frame.select(self._id)
+        else:
+            column = self._column(sort.column)
+            is_text = column_kind(column.type) is ColumnKind.TEXT
+            cell = nw.col(column.name)
+            empty = cell.is_null() | (cell.cast(nw.String) == "") if is_text else cell.is_null()
+            key = cell.cast(nw.String).str.to_lowercase() if is_text else cell
+            ordered = (
+                frame.select(self._id, empty.alias(_EMPTY_KEY), key.alias(_SORT_KEY))
+                # the empty cells last in both orders, equal cells in the frame's order
+                .sort(
+                    _EMPTY_KEY,
+                    _SORT_KEY,
+                    self._id,
+                    descending=[False, sort.descending, False],
+                    nulls_last=True,
+                )
+                .select(self._id)
+            )
+        return list(_collected(ordered).get_column(self._id).to_list())
+
+    def cells(self, ids: Sequence[Hashable], columns: Sequence[str]) -> dict[Hashable, list[Any]]:
+        names = [self._column(name).name for name in columns]
+        rows = _collected(
+            self._frame.filter(nw.col(self._id).is_in(list(ids))).select(self._id, *names)
+        )
+        return {
+            _python_value(row[0]): [_python_value(value) for value in row[1:]]
+            for row in rows.iter_rows()
+        }
+
+    def _column(self, name: str) -> SourceColumn:
+        column = self._columns.get(name)
+        if column is None:
+            msg = f"Cannot read the column {name!r} of a DataFrameSource: it has none so."
+            raise ValueError(msg)
+        return column
+
+    @staticmethod
+    def _condition(column: SourceColumn, row_filter: Filter) -> nw.Expr:
+        """Get the expression of `row_filter` on `column`, as `Filter.matches` reads a cell.
+
+        An empty cell's text is "", and it fails a comparison.
+        """
+        cell = nw.col(column.name)
+        operator, value = row_filter.operator, row_filter.value
+        if operator is FilterOperator.EMPTY:
+            if column_kind(column.type) is ColumnKind.TEXT:
+                return cell.is_null() | (cell.cast(nw.String) == "")
+            return cell.is_null()
+        if operator in _TEXT_OPERATORS:
+            return _text_condition(_text(column.name), operator, value)
+        if operator is FilterOperator.MATCHES:
+            text = cell.cast(nw.String).fill_null("")
+            return text.str.contains(f"(?i){value.pattern}")
+        if operator is FilterOperator.RANGE:
+            compared = cell.is_between(value, row_filter.upper)
+        else:
+            compared = _comparison(cell, operator, value)
+        # an empty cell fails, though pandas' NaN differs from any value
+        return ~cell.is_null() & compared
+
+
+def series_of(frame: IntoFrame, x: str, y: str, *, name: Optional[str] = None) -> Series:
+    """Make a chart's series of a frame's columns `x` and `y`, under `name`, else `y`.
+
+    The rows missing either value are left out, in the frame's order otherwise.
+    """
+    rows = _collected(nw.from_native(frame).select(x, y).drop_nulls())
+    return Series(
+        y if name is None else name, rows.get_column(x).to_list(), rows.get_column(y).to_list()
+    )
+
+
+def points_of(frame: IntoFrame, latitude: str, longitude: str) -> list[MapPoint]:
+    """Get a map's points of a frame's columns `latitude` and `longitude`, in degrees.
+
+    The rows missing either value, or out of a Web Mercator map (see `MapPoint`), are left out.
+    """
+    rows = _collected(
+        nw.from_native(frame)
+        .select(latitude, longitude)
+        .drop_nulls()
+        .filter(
+            nw.col(latitude).is_between(-MAP_LATITUDE_LIMIT, MAP_LATITUDE_LIMIT),
+            nw.col(longitude).is_between(-180, 180),
+        )
+    )
+    return [MapPoint(latitude=lat, longitude=lon) for lat, lon in rows.iter_rows()]
+
+
+def _text(name: str) -> nw.Expr:
+    """Get a cell's text in lower case, an empty cell's being ""."""
+    return nw.col(name).cast(nw.String).fill_null("").str.to_lowercase()
+
+
+def _text_condition(text: nw.Expr, operator: FilterOperator, value: str) -> nw.Expr:
+    if operator is FilterOperator.CONTAINS:
+        return text.str.contains(value, literal=True)
+    if operator is FilterOperator.NOT_CONTAINS:
+        return ~text.str.contains(value, literal=True)
+    if operator is FilterOperator.TEXT_EQUAL:
+        return text == value
+    if operator is FilterOperator.TEXT_NOT_EQUAL:
+        return text != value
+    if operator is FilterOperator.STARTS_WITH:
+        return text.str.starts_with(value)
+    return text.str.ends_with(value)
+
+
+def _comparison(cell: nw.Expr, operator: FilterOperator, value: Any) -> nw.Expr:
+    if operator is FilterOperator.EQUAL:
+        return cell == value
+    if operator is FilterOperator.NOT_EQUAL:
+        return cell != value
+    if operator is FilterOperator.LESS:
+        return cell < value
+    if operator is FilterOperator.LESS_OR_EQUAL:
+        return cell <= value
+    if operator is FilterOperator.GREATER:
+        return cell > value
+    return cell >= value
+
+
+def _python_value(value: Any) -> Any:
+    """Get a cell as Python's value: pandas gives numpy's scalars, and NaN or NaT for none."""
+    try:
+        if value is None or bool(value != value):  # noqa: PLR0124 (NaN and NaT differ from themselves)
+            return None
+    except TypeError:  # pandas' NA, which is neither true nor false
+        return None
+    if hasattr(value, "to_pydatetime"):  # a pandas Timestamp
+        return value.to_pydatetime()
+    if hasattr(value, "item"):  # a numpy scalar
+        return value.item()
+    return value
+
+
+def _collected(frame: Union[nw.DataFrame[Any], nw.LazyFrame[Any]]) -> nw.DataFrame[Any]:
+    return frame.collect() if isinstance(frame, nw.LazyFrame) else frame