densitty 0.8.2__tar.gz

densitty-0.8.2/.gitignore

@@ -0,0 +1,13 @@
+# pyenv version file
+.python-version
+
+# uv
+uv.lock
+
+# test and build artifacts
+.coverage
+.pytest_cache/
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/

densitty-0.8.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Tompkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

densitty-0.8.2/Makefile

@@ -0,0 +1,57 @@
+.PHONY: test
+test:
+	PYTHONPATH=. uv run --with numpy,pytest,readchar,rich python -m pytest tests/*.py
+	PYTHONPATH=. uv run --with numpy,pytest,readchar,pytest-cov python -m pytest --cov=densitty tests/*.py
+
+.PHONY: testcov
+testcov:
+	PYTHONPATH=. uv run --with numpy,pytest,pytest-cov,readchar python -m pytest --cov=densitty --cov-report=html tests/*.py
+
+.PHONY: golden-accept
+golden-accept:
+	PYTHONPATH=. uv run --with readchar python tests/golden_diff.py
+
+.PHONY: lint
+lint:
+	PYTHONPATH=. uv run --with pylint,rich python -m pylint densitty
+
+.PHONY: format
+format:
+	uv run --with black python -m black -l 99 densitty/*.py
+	uv run --with black python -m black -l 99 tests/*.py
+
+.PHONY: typecheck
+typecheck:
+	PYTHONPATH=. uv run --with mypy,rich python -m mypy densitty
+	PYTHONPATH=. uv run --with mypy,numpy,rich python -m mypy tests/numpy_tests.py
+	PYTHONPATH=. uv run --with mypy,rich python -m mypy tests/axis_tests.py
+
+.PHONY: colors
+colors:
+	PYTHONPATH=. uv run --with pytest,rich python tests/color_tests.py
+
+.PHONY: build
+build: ## Build wheel file
+	rm -rf ./dist
+	uvx --from build pyproject-build --installer uv
+
+.PHONY: tag
+tag: ## Add a Git tag and push it to origin with syntax: make tag TAG=tag_name
+ifeq ($(origin TAG),undefined)
+	$(error "ERROR: use like 'make tag TAG=tag_name'")
+else
+	@echo "Creating git tag: ${TAG}"
+	git tag -a ${TAG} -m ""
+	@echo "Pushing tag to origin: ${TAG}"
+	git push origin ${TAG}
+endif
+
+.PHONY: publish-test
+publish-test: build
+	@echo "Publishing to testpypi"
+	uvx twine upload --repository testpypi dist/*
+
+.PHONY: publish
+publish: build
+	@echo "Publishing to REAL pypi"
+	uvx twine upload dist/*

densitty-0.8.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: densitty
+Version: 0.8.2
+Summary: densitty - create textual 2-D density plots, heatmaps, and 2-D histograms in Python
+Author: Bill Tompkins
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BillTompkins/densitty
+Keywords: densitty,ascii,ascii-art,plotting,terminal,Python
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<h1 align="center">densitty</h1>
+<h2 align="center"> Terminal-based 2-D Histogram, Density Plots, and Heatmaps</h2>
+
+Generate 2-D histograms (density plots, heat maps, eye diagrams) similar to [matplotlib's hist2d](https://matplotlib.org/stable/gallery/statistics/hist.html "hist2d"), but with output in the terminal, and no external dependencies.
+
+![Plot Output](https://billtompkins.github.io/densitty/docs/inline-histplot2d.png "example output image")
+
+## [Examples/Gallery](https://billtompkins.github.io/densitty/docs/examples.html)
+
+## [Sub-modules / Usage Notes](https://billtompkins.github.io/densitty/docs/usage.html)
+
+## [Color, Size, and Glyph Support](https://billtompkins.github.io/densitty/docs/terminal_support.html)
+
+## API (TODO)

densitty-0.8.2/README.md

@@ -0,0 +1,14 @@
+<h1 align="center">densitty</h1>
+<h2 align="center"> Terminal-based 2-D Histogram, Density Plots, and Heatmaps</h2>
+
+Generate 2-D histograms (density plots, heat maps, eye diagrams) similar to [matplotlib's hist2d](https://matplotlib.org/stable/gallery/statistics/hist.html "hist2d"), but with output in the terminal, and no external dependencies.
+
+![Plot Output](https://billtompkins.github.io/densitty/docs/inline-histplot2d.png "example output image")
+
+## [Examples/Gallery](https://billtompkins.github.io/densitty/docs/examples.html)
+
+## [Sub-modules / Usage Notes](https://billtompkins.github.io/densitty/docs/usage.html)
+
+## [Color, Size, and Glyph Support](https://billtompkins.github.io/densitty/docs/terminal_support.html)
+
+## API (TODO)

densitty-0.8.2/densitty/ansi.py

@@ -0,0 +1,109 @@
+"""ANSI code/color support"""
+
+# <pedantic> that the 256-color support here is not actually ANSI X3.64, though it uses ANSI-ish
+# escape sequences. I believe it was originally done in Xterm. And 4b colors (16-color)
+# are really an aixterm extension to the ANSI-specified 8-color standard. </pedantic>
+
+from typing import Optional, Sequence
+
+from .util import nearest
+
+
+RESET = "\033[0m"
+
+
+def compose(codes: Sequence[str]) -> str:
+    """Given a list of individual color codes, produce the full escape sequence."""
+    return f"\033[{';'.join(codes)}m"
+
+
+def colormap_16(colors):
+    """Produce a function that returns closest 4b/16color ANSI color codes from colormap.
+    Parameters
+    ----------
+    colors: Sequence[int]
+            Ordered 16-color ANSI colors corresponding to the 0.0..1.0 range
+    """
+
+    def as_colorcodes(bg_frac: Optional[float], fg_frac: Optional[float]) -> str:
+        """Return ANSI color code for 16-color value(s)
+        Parameters
+        ----------
+        fg_frac: Optional[float]
+                 Value 0.0..1.0 for foreground, or None if background-only
+        fg_frac: Optional[float]
+                 Value 0.0..1.0 for background, or None for foreground-only
+        """
+        codes = []
+        if fg_frac is not None:
+            codes += [f"{30 + nearest(colors, fg_frac)}"]
+        if bg_frac is not None:
+            codes += [f"{40 + nearest(colors, bg_frac)}"]
+        return compose(codes)
+
+    return as_colorcodes
+
+
+def colormap_256(colors):
+    """Produce a function that returns closest 8b/256color ANSI color codes from colormap.
+    Parameters
+    ----------
+    colors: Sequence[int]
+            Ordered 256-color ANSI colors corresponding to the 0.0..1.0 range
+    """
+
+    def as_colorcodes(bg_frac: Optional[float], fg_frac: Optional[float]):
+        """Return ANSI color code for 256-color value(s)
+        Parameters
+        ----------
+        fg_frac: Optional[float]
+                 Value 0.0..1.0 for foreground, or None if background-only
+        fg_frac: Optional[float]
+                 Value 0.0..1.0 for background, or None for foreground-only
+        """
+        codes = []
+        if fg_frac is not None:
+            fg = nearest(colors, fg_frac)
+            codes += [f"38;5;{fg}"]
+        if bg_frac is not None:
+            bg = nearest(colors, bg_frac)
+            codes += [f"48;5;{bg}"]
+        return compose(codes)
+
+    return as_colorcodes
+
+
+########################################################
+# Colormaps. Assumed 256-color unless suffixed with _16
+# pylint: disable=invalid-name
+
+
+# ANSI 16-color map colors in ROYGBIV order: Red, Yellow, Green, Cyan, Blue
+RAINBOW_16 = colormap_16((5, 1, 3, 2, 6))
+
+# ANSI 16-color 'rainbow', Reversed:
+REV_RAINBOW_16 = colormap_16((6, 2, 3, 1, 5))
+
+# ANSI 16-color map colors: Black, Blue, Cyan, Green, Yellow, Red, Magenta, White
+FADE_IN_16 = colormap_16((0, 4, 6, 2, 3, 1, 5, 7))
+
+# ANSI 256-color map colors in a grayscale black->white
+GRAYSCALE = colormap_256([0] + list(range(232, 256)) + [15])
+
+rainbow_256_colors = (
+    # fmt: off
+    (196, 202, 208, 214, 220, 190, 154, 118, 82, 46, 47, 48, 43, 80, 81, 39, 27, 21, 56, 91)
+    # fmt: on
+)
+RAINBOW = colormap_256(rainbow_256_colors)
+REV_RAINBOW = colormap_256(tuple(reversed(rainbow_256_colors)))
+
+BLUE_RED = colormap_256((21, 56, 91, 126, 161, 196))
+FADE_IN = colormap_256(
+    # fmt: off
+    (16, 53, 54, 55, 56, 57, 21, 21, 27, 39, 81, 80, 43, 48, 47,
+     46, 82, 118, 154, 190, 220, 214, 208, 202, 196)
+    # fmt: on
+)
+HOT = colormap_256((16, 52, 88, 124, 160, 196, 202, 208, 214, 220, 226, 227, 228, 229, 230, 231))
+COOL = colormap_256((50, 81, 111, 141, 171, 201))

densitty-0.8.2/densitty/ascii_art.py

@@ -0,0 +1,24 @@
+"""ASCII-art support"""
+
+from typing import Callable, Sequence
+
+from .util import nearest
+
+
+def color_map(values: Sequence[str]) -> Callable:
+    """Returns the closest ascii-art pixel."""
+
+    def compute_pixel_value(frac: float, _=None) -> str:
+        return nearest(values, frac)
+
+    return compute_pixel_value
+
+
+#
+# Some example/useful color scales
+# Character (glyph) density is dependent on font choice, unfortunately
+
+# Allow the all-caps colormap names:
+# pylint: disable=invalid-name
+DEFAULT = color_map(" .:-=+*#%@")
+EXTENDED = color_map(" .'`^\",:;Il!i>~+?[{1(|/o*#MW&8%B$@")

densitty-0.8.2/densitty/axis.py

@@ -0,0 +1,265 @@
+"""Axis-generation support."""
+
+import dataclasses
+from decimal import Decimal
+import itertools
+import math
+from typing import Optional
+
+from . import lineart
+from .util import FloatLike, ValueRange, pick_step_size
+
+MIN_X_TICKS_PER_LABEL = 4
+MIN_Y_TICKS_PER_LABEL = 2
+DEFAULT_X_COLS_PER_TICK = 4
+DEFAULT_Y_ROWS_PER_TICK = 2
+
+
+@dataclasses.dataclass
+class BorderChars:
+    """Characters to use for X/Y border"""
+
+    first: str
+    middle: str
+    last: str
+
+
+y_border = {False: BorderChars(" ", " ", " "), True: BorderChars("╷", "│", "╵")}
+x_border = {False: BorderChars(" ", " ", " "), True: BorderChars("╶", "─", "╴")}
+
+###############################################
+# Helper functions used by the Axis class below
+
+
+def add_label(line: list[str], label: str, ctr_pos: int):
+    """Adds the label string to the output line, centered at specified position
+    The output line is a list of single-character strings, to make this kind of thing
+    straightforward"""
+    width = len(label)
+    start_col = max(ctr_pos - width // 2, 0)
+    end_col = start_col + width
+    line[start_col:end_col] = list(label)
+
+
+def gen_tick_values(value_range, tick_step):
+    """Produce tick values in the specified range. Basically numpy.arange"""
+
+    tick = math.ceil(value_range.min / tick_step) * tick_step
+    while tick <= value_range.max:
+        yield tick
+        tick += tick_step
+
+
+def gen_labels(
+    value_range: ValueRange, num_ticks, min_ticks_per_label, fmt, label_end_ticks=False
+):
+    """Generate positions for labels (plain ticks & ticks with value)"""
+    tick_step, label_step = pick_step_size(value_range, num_ticks, min_ticks_per_label)
+
+    ticks = list(gen_tick_values(value_range, tick_step))
+    label_values = list(gen_tick_values(value_range, label_step))
+    if label_end_ticks or len(label_values) <= 2:
+        # ensure that first & last ticks have labels:
+        if label_values[0] != ticks[0]:
+            label_values = ticks[:1] + label_values
+        if label_values[-1] != ticks[-1]:
+            label_values += ticks[-1:]
+
+    # sanity: if all but one ticks have labels, just label them all
+    if len(label_values) >= len(ticks) - 1:
+        label_values = ticks
+
+    ticks_only = {value: "" for value in ticks}
+    labeled_ticks = {value: fmt.format(value) for value in label_values}
+
+    return ticks_only | labeled_ticks
+
+
+def calc_edges(value_range, num_bins, values_are_edges):
+    """Calculate the top/bottom or left/right values for each of 'num_bins' bins
+
+    Parameters
+    ----------
+    value_range: util.ValueRange
+                 Coordinate values for first/last bin
+                 Can be center of bin, or outside edge (see values_are_edges)
+    num_bins:    int
+                 Number of bins/intervals to produce edges for
+    values_are_edges: bool
+                 Indicates that value_range specifies outside edges rather than bin centers
+    """
+    if values_are_edges:
+        bin_delta = (value_range.max - value_range.min) / num_bins
+        first_bin_min = value_range.min
+    else:
+        bin_delta = (value_range.max - value_range.min) / (num_bins - 1)
+        first_bin_min = value_range.min - (bin_delta / 2)
+    bin_edges = tuple(first_bin_min + i * bin_delta for i in range(num_bins + 1))
+    return itertools.pairwise(bin_edges)
+
+
+###############################################
+# The User-facing interface: the Axis class
+
+
+@dataclasses.dataclass
+class Axis:
+    """Options for axis generation."""
+
+    value_range: ValueRange  # can also specify as a tuple of (min, max)
+    labels: Optional[dict[float, str]] = None  # map axis value to label (plus tick) at that value
+    label_fmt: str = "{}"  # format for generated labels
+    border_line: bool = False  # embed ticks in a horizontal X-axis or vertical Y-axis line
+    values_are_edges: bool = False  # N+1 values, indicating boundaries between pixels, not centers
+    fractional_tick_pos: bool = False  # Use "▔", "▁", or "╱╲" for non-centered ticks
+
+    def __init__(
+        self,
+        value_range: ValueRange | tuple[FloatLike, FloatLike],
+        labels: Optional[dict[float, str]] = None,
+        label_fmt: str = "{}",
+        border_line: bool = False,
+        values_are_edges: bool = False,
+        fractional_tick_pos: bool = False,
+        # pylint: disable=too-many-arguments,too-many-positional-arguments
+    ):
+        # Sanitize value_range: allow user to provide it as a tuple of FloatLike (without
+        # needing to import ValueRange), and convert to ValueRange(Decimal, Decimal)
+        self.value_range = ValueRange(
+            Decimal(float(value_range[0])), Decimal(float(value_range[1]))
+        )
+        self.labels = labels
+        self.label_fmt = label_fmt
+        self.border_line = border_line
+        self.values_are_edges = values_are_edges
+        self.fractional_tick_pos = fractional_tick_pos
+
+    def _unjustified_y_axis(self, num_rows: int):
+        """Returns the Y axis string for each line of the plot"""
+        if self.labels is None:
+            labels = gen_labels(
+                self.value_range,
+                num_rows // DEFAULT_Y_ROWS_PER_TICK,
+                MIN_Y_TICKS_PER_LABEL,
+                self.label_fmt,
+            )
+        else:
+            labels = self.labels
+
+        label_values = sorted(labels.keys())
+        bins = calc_edges(self.value_range, num_rows, self.values_are_edges)
+
+        use_combining = self.border_line and self.fractional_tick_pos
+        for row_min, row_max in bins:
+            if label_values and row_min <= label_values[0] <= row_max:
+                label_str = labels[label_values[0]]
+
+                offset_frac = (label_values[0] - row_min) / (row_max - row_min)
+                if offset_frac < 0.25 and self.fractional_tick_pos:
+                    tick_char = "▔"
+                elif offset_frac > 0.75 and self.fractional_tick_pos:
+                    tick_char = "▁"
+                else:
+                    tick_char = "─"
+                label_str += lineart.merge_chars(
+                    tick_char,
+                    y_border[self.border_line].middle,
+                    use_combining_unicode=use_combining,
+                )
+                yield label_str
+                label_values = label_values[1:]
+            else:
+                yield y_border[self.border_line].middle
+
+    def render_as_y(self, num_rows: int, pad_top: bool, pad_bot: bool, flip: bool):
+        """Create a Y axis as a list of strings for the left margin of a plot
+
+        Parameters
+        ----------
+        num_rows: int
+                  Number of data rows
+        pad_top:  bool
+                  Emit a line for an X axis line/row at the top
+        pad_bot:  bool
+                  Emit a line for an X axis line/row at the bottom
+        flip:     bool
+                  Put the minimum Y on the last line rather than the first
+        """
+        unpadded_labels = list(self._unjustified_y_axis(num_rows))
+        if flip:
+            unpadded_labels = [
+                s.translate(lineart.flip_vertical) for s in reversed(unpadded_labels)
+            ]
+
+        if pad_top:
+            unpadded_labels = [y_border[self.border_line].first] + unpadded_labels
+        if pad_bot:
+            unpadded_labels = unpadded_labels + [y_border[self.border_line].last]
+
+        lengths = [lineart.display_len(label_str) for label_str in unpadded_labels]
+        max_width = max(lengths)
+        pad_lengths = [max_width - length for length in lengths]
+        padded_labels = [
+            " " * pad_length + label_str
+            for (label_str, pad_length) in zip(unpadded_labels, pad_lengths)
+        ]
+        return padded_labels
+
+    def render_as_x(self, num_cols: int, left_margin: int):
+        """Generate X tick line and X label line.
+
+        Parameters
+        ----------
+        num_cols:    int
+                     Number of data columns
+        left_margin: int
+                     chars to the left of leftmost data col. May have Labels/border-line.
+        """
+
+        if self.labels is None:
+            labels = gen_labels(
+                self.value_range,
+                num_cols // DEFAULT_X_COLS_PER_TICK,
+                MIN_X_TICKS_PER_LABEL,
+                self.label_fmt,
+            )
+        else:
+            labels = self.labels
+
+        label_values = sorted(labels.keys())
+
+        bins = calc_edges(self.value_range, num_cols, self.values_are_edges)
+
+        tick_line = list(
+            " " * (left_margin - 1)
+            + x_border[self.border_line].first
+            + x_border[self.border_line].middle * num_cols
+            + x_border[self.border_line].last
+        )
+
+        label_line = [" "] * len(tick_line)  # labels under the ticks
+
+        for col_idx, (col_min, col_max) in enumerate(bins):
+            # use Decimal.next_plus to accomodate rounding error/truncation
+            if label_values and col_min <= label_values[0] <= col_max.next_plus():
+                add_label(label_line, labels[label_values[0]], col_idx + left_margin)
+                tick_idx = left_margin + col_idx
+                offset_frac = (label_values[0] - col_min) / (col_max - col_min)
+                if self.fractional_tick_pos and offset_frac < 0.25:
+                    if col_idx == 0:
+                        tick_line[tick_idx - 1] = lineart.merge_chars("│", tick_line[tick_idx - 1])
+                    else:
+                        tick_line[tick_idx - 1] = "╱"
+                    tick_line[tick_idx] = "╲"
+                elif self.fractional_tick_pos and offset_frac > 0.75:
+                    tick_line[tick_idx] = "╱"
+                    if col_idx < num_cols - 1:
+                        tick_line[tick_idx + 1] = "╲"
+                    else:
+                        tick_line[tick_idx + 1] = lineart.merge_chars("│", tick_line[tick_idx + 1])
+                else:
+                    tick_line[tick_idx] = lineart.merge_chars("│", tick_line[tick_idx])
+
+                label_values = label_values[1:]  # pop that first label since we added it
+
+        return "".join(tick_line), "".join(label_line)