curved-text 0.1.0__tar.gz

curved_text-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph J. Thiebes
+
+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.

curved_text-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: curved-text
+Version: 0.1.0
+Summary: Draw text along an arbitrary curve in matplotlib, with arc-length positioning and a perpendicular offset.
+Author-email: Joseph Thiebes <joseph@thiebes.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thiebes/curved-text
+Project-URL: Source, https://github.com/thiebes/curved-text
+Project-URL: Issues, https://github.com/thiebes/curved-text/issues
+Project-URL: Changelog, https://github.com/thiebes/curved-text/blob/main/CHANGELOG.md
+Keywords: matplotlib,text,annotation,label,curve,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Matplotlib
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.20
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: examples
+Requires-Dist: seaborn>=0.11; extra == "examples"
+Requires-Dist: pandas>=1.3; extra == "examples"
+Dynamic: license-file
+
+# curved-text
+
+[![CI](https://github.com/thiebes/curved-text/actions/workflows/ci.yml/badge.svg)](https://github.com/thiebes/curved-text/actions/workflows/ci.yml)
+
+Draw text that follows an arbitrary curve in [matplotlib](https://matplotlib.org/).
+
+![Direct labeling versus a legend](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/01_direct_labeling.png)
+
+Label curves along their own paths instead of in a legend, so the eye never
+leaves the data to decode a colour key.
+
+Each character is placed in display coordinates and rotated to the local tangent
+of the curve, recomputed on every draw, so the label keeps following the curve
+through layout, resizing, and interactive panning or zooming. Placement is
+controlled by three independent parameters:
+
+- `pos` -- where the label is anchored along the curve, as a fraction of arc
+  length (`0.0` = first point, `1.0` = last).
+- `anchor` -- which part of the label lands at `pos`: `"start"`, `"center"`, or
+  `"end"`.
+- `offset` -- a perpendicular shift off the curve, in typographic points, along
+  the normal of the label's chord (positive is above a left-to-right curve).
+
+A label that overruns either end of the curve is not clipped: the curve is
+extended along its end tangent and the overrunning glyphs sit on that straight
+extension.
+
+## Install
+
+```bash
+pip install curved-text
+```
+
+Or, from a clone, an editable install:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from curved_text import curved_text
+
+x = np.linspace(0, 2 * np.pi, 400)
+y = np.sin(x)
+
+fig, ax = plt.subplots()
+ax.plot(x, y)
+curved_text(ax, x, y, "text that follows the curve",
+            pos=0.5, anchor="center", offset=6.0, color="C3")
+plt.show()
+```
+
+![A label following a sine wave](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/02_sine_hello.png)
+
+More worked examples -- the three placement controls, overrun behaviour, and
+integration with seaborn and pandas -- are in [examples/](examples/README.md).
+
+The object-oriented form is also available:
+
+```python
+from curved_text import CurvedText
+
+CurvedText(x, y, "along the curve", ax, pos=0.2, anchor="start", offset=4.0)
+```
+
+Note the axes argument position: the `CurvedText` class takes it after `x, y,
+text` (matching `matplotlib.text.Text`), while the `curved_text` function takes it
+first (matching matplotlib's axes-first helper functions).
+
+Any extra keyword arguments (`color`, `fontsize`, `alpha`, `fontfamily`, ...) are
+passed through to each character's `matplotlib.text.Text`.
+
+## Works with seaborn, pandas, and other matplotlib-backed libraries
+
+`curved_text` needs a `matplotlib.axes.Axes`, so it works with any library that
+draws on matplotlib. seaborn's axes-level functions return an `Axes`, its
+figure-level functions expose one through `.axes`, and `pandas` `DataFrame.plot`
+returns an `Axes` as well. Pass that axes in directly:
+
+```python
+import seaborn as sns
+
+ax = sns.lineplot(data=df, x="x", y="y")
+curved_text(ax, df["x"], df["y"], "along the curve",
+            pos=0.5, anchor="center", offset=6.0)
+```
+
+## Notes
+
+- The curve `(x, y)` should be ordered along the curve (monotonic in arc length)
+  and have at least two points.
+- Arc length and the offset are computed in display space, so spacing and the
+  offset are correct at any DPI and figure size.
+
+## License
+
+MIT

curved_text-0.1.0/README.md

@@ -0,0 +1,101 @@
+# curved-text
+
+[![CI](https://github.com/thiebes/curved-text/actions/workflows/ci.yml/badge.svg)](https://github.com/thiebes/curved-text/actions/workflows/ci.yml)
+
+Draw text that follows an arbitrary curve in [matplotlib](https://matplotlib.org/).
+
+![Direct labeling versus a legend](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/01_direct_labeling.png)
+
+Label curves along their own paths instead of in a legend, so the eye never
+leaves the data to decode a colour key.
+
+Each character is placed in display coordinates and rotated to the local tangent
+of the curve, recomputed on every draw, so the label keeps following the curve
+through layout, resizing, and interactive panning or zooming. Placement is
+controlled by three independent parameters:
+
+- `pos` -- where the label is anchored along the curve, as a fraction of arc
+  length (`0.0` = first point, `1.0` = last).
+- `anchor` -- which part of the label lands at `pos`: `"start"`, `"center"`, or
+  `"end"`.
+- `offset` -- a perpendicular shift off the curve, in typographic points, along
+  the normal of the label's chord (positive is above a left-to-right curve).
+
+A label that overruns either end of the curve is not clipped: the curve is
+extended along its end tangent and the overrunning glyphs sit on that straight
+extension.
+
+## Install
+
+```bash
+pip install curved-text
+```
+
+Or, from a clone, an editable install:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from curved_text import curved_text
+
+x = np.linspace(0, 2 * np.pi, 400)
+y = np.sin(x)
+
+fig, ax = plt.subplots()
+ax.plot(x, y)
+curved_text(ax, x, y, "text that follows the curve",
+            pos=0.5, anchor="center", offset=6.0, color="C3")
+plt.show()
+```
+
+![A label following a sine wave](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/02_sine_hello.png)
+
+More worked examples -- the three placement controls, overrun behaviour, and
+integration with seaborn and pandas -- are in [examples/](examples/README.md).
+
+The object-oriented form is also available:
+
+```python
+from curved_text import CurvedText
+
+CurvedText(x, y, "along the curve", ax, pos=0.2, anchor="start", offset=4.0)
+```
+
+Note the axes argument position: the `CurvedText` class takes it after `x, y,
+text` (matching `matplotlib.text.Text`), while the `curved_text` function takes it
+first (matching matplotlib's axes-first helper functions).
+
+Any extra keyword arguments (`color`, `fontsize`, `alpha`, `fontfamily`, ...) are
+passed through to each character's `matplotlib.text.Text`.
+
+## Works with seaborn, pandas, and other matplotlib-backed libraries
+
+`curved_text` needs a `matplotlib.axes.Axes`, so it works with any library that
+draws on matplotlib. seaborn's axes-level functions return an `Axes`, its
+figure-level functions expose one through `.axes`, and `pandas` `DataFrame.plot`
+returns an `Axes` as well. Pass that axes in directly:
+
+```python
+import seaborn as sns
+
+ax = sns.lineplot(data=df, x="x", y="y")
+curved_text(ax, df["x"], df["y"], "along the curve",
+            pos=0.5, anchor="center", offset=6.0)
+```
+
+## Notes
+
+- The curve `(x, y)` should be ordered along the curve (monotonic in arc length)
+  and have at least two points.
+- Arc length and the offset are computed in display space, so spacing and the
+  offset are correct at any DPI and figure size.
+
+## License
+
+MIT

curved_text-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "curved-text"
+version = "0.1.0"
+description = "Draw text along an arbitrary curve in matplotlib, with arc-length positioning and a perpendicular offset."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joseph Thiebes", email = "joseph@thiebes.org" }]
+keywords = ["matplotlib", "text", "annotation", "label", "curve", "visualization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Matplotlib",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Intended Audience :: Science/Research",
+]
+
+# Library dependencies use compatible lower bounds; a consuming application pins
+# exact versions in its own lockfile.
+dependencies = [
+    "matplotlib>=3.5",
+    "numpy>=1.20",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+# Extra renderers used only by the integration example (matplotlib is already a
+# core dependency). Lower bounds, like the rest of the project.
+examples = [
+    "seaborn>=0.11",
+    "pandas>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/thiebes/curved-text"
+Source = "https://github.com/thiebes/curved-text"
+Issues = "https://github.com/thiebes/curved-text/issues"
+Changelog = "https://github.com/thiebes/curved-text/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

curved_text-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

curved_text-0.1.0/src/curved_text/__init__.py

@@ -0,0 +1,11 @@
+"""curved-text: draw text along an arbitrary curve in matplotlib."""
+from importlib.metadata import PackageNotFoundError, version
+
+from ._core import CurvedText, curved_text
+
+__all__ = ["CurvedText", "curved_text"]
+
+try:
+    __version__ = version("curved-text")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"

curved_text-0.1.0/src/curved_text/_core.py

@@ -0,0 +1,176 @@
+"""Draw text along an arbitrary curve in a matplotlib Axes."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import matplotlib.text as mtext
+import numpy as np
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from numpy.typing import ArrayLike
+
+__all__ = ["CurvedText", "curved_text"]
+
+_ANCHORS = ("start", "center", "end")
+
+
+class CurvedText(mtext.Text):
+    """A string drawn along an (x, y) curve, one character at a time.
+
+    Each character is an independent :class:`matplotlib.text.Text`, centered
+    (``ha="center"``, ``va="center"``) on its own arc-length midpoint, placed in
+    display coordinates and rotated to the local tangent of the curve. The layout
+    is recomputed on every draw, so the label keeps following the curve through
+    figure layout, resizing, and interactive panning or zooming.
+
+    Placement has three independent controls:
+
+    ``pos``
+        Where the label is anchored along the curve, as a fraction of the curve's
+        arc length: ``0.0`` is the first point, ``1.0`` is the last.
+    ``anchor``
+        Which part of the label lands at ``pos``: ``"start"``, ``"center"``, or
+        ``"end"``.
+    ``offset``
+        A perpendicular shift off the curve, in typographic points, along the
+        normal of the label's chord (the line from its first to its last glyph).
+        Positive is to the left of the direction of travel, which is visually
+        above a left-to-right curve.
+
+    A label that overruns either end of the curve -- because of ``pos`` and
+    ``anchor`` -- is not clipped. The curve is extended along its end tangent and
+    the overrunning glyphs are placed on that straight extension.
+
+    Parameters
+    ----------
+    x, y : array-like
+        The curve in data coordinates: 1-D, equal length, at least two points,
+        finite, and ordered along the curve.
+    text : str
+        The string to draw.
+    axes : matplotlib.axes.Axes
+        The axes to draw into.
+    pos : float, default 0.5
+        Arc-length fraction in ``[0, 1]`` for the anchor point.
+    anchor : {"start", "center", "end"}, default "center"
+        Which part of the label sits at ``pos``.
+    offset : float, default 0.0
+        Perpendicular offset off the curve, in points.
+    **kwargs
+        Passed to each per-character :class:`~matplotlib.text.Text` (for example
+        ``color``, ``fontsize``, ``alpha``, ``fontfamily``).
+    """
+
+    def __init__(self, x: ArrayLike, y: ArrayLike, text: str, axes: Axes, *,
+                 pos: float = 0.5, anchor: str = "center", offset: float = 0.0,
+                 **kwargs: Any) -> None:
+        if anchor not in _ANCHORS:
+            raise ValueError(f"anchor must be one of {_ANCHORS}, got {anchor!r}")
+        x = np.asarray(x, dtype=float)
+        y = np.asarray(y, dtype=float)
+        if x.ndim != 1 or x.shape != y.shape or x.size < 2:
+            raise ValueError("x and y must be 1-D arrays of equal length >= 2")
+        if not (np.isfinite(x).all() and np.isfinite(y).all()):
+            raise ValueError("x and y must contain only finite values")
+        super().__init__(float(x[0]), float(y[0]), " ", **kwargs)
+        self._cx = x
+        self._cy = y
+        self._pos = float(pos)
+        self._anchor = anchor
+        self._offset = float(offset)
+        axes.add_artist(self)
+        self._chars: list[mtext.Text] = []
+        for ch in text:
+            t = mtext.Text(0.0, 0.0, " " if ch == " " else ch, **kwargs)
+            t.set_ha("center")
+            t.set_va("center")
+            axes.add_artist(t)
+            self._chars.append(t)
+
+    def set_zorder(self, zorder) -> None:
+        # Keep the glyphs one level above the container so they sit on top of it.
+        # ``super().__init__`` may set the zorder before ``_chars`` exists, so
+        # guard against running during base-class construction.
+        super().set_zorder(zorder)
+        for t in getattr(self, "_chars", ()):
+            t.set_zorder(self.get_zorder() + 1)
+
+    def remove(self) -> None:
+        # The glyphs are independent artists on the axes; remove them with the
+        # container so removal does not leave them behind as orphans.
+        for t in self._chars:
+            t.remove()
+        self._chars = []
+        super().remove()
+
+    def draw(self, renderer, *args, **kwargs) -> None:
+        if not self._chars:
+            return
+        axes = self.axes
+        # Work in display pixels: project the curve, accumulate cumulative arc
+        # length along it, and the tangent angle of each segment.
+        pts = axes.transData.transform(np.column_stack([self._cx, self._cy]))
+        xf, yf = pts[:, 0], pts[:, 1]
+        arc = np.insert(np.cumsum(np.hypot(np.diff(xf), np.diff(yf))), 0, 0.0)
+        if not np.isfinite(arc[-1]) or arc[-1] <= 0.0:
+            return
+        rads = np.arctan2(np.diff(yf), np.diff(xf))
+        inv = axes.transData.inverted()
+
+        # Reset any rotation left by the previous draw before measuring, so each
+        # width is the unrotated advance, not the wider rotated bounding box.
+        for t in self._chars:
+            t.set_rotation(0)
+        widths = [t.get_window_extent(renderer=renderer).width for t in self._chars]
+        total = float(sum(widths))
+
+        def _point(s):
+            # Position at arc length ``s``. ``i`` is the segment it falls in, which
+            # the caller also uses to read the local tangent ``rads[i]``. Clipping
+            # the index extrapolates past either end along the terminal segment.
+            i = int(np.clip(np.searchsorted(arc, s) - 1, 0, len(arc) - 2))
+            d = arc[i + 1] - arc[i]
+            f = (s - arc[i]) / d if d else 0.0
+            return i, xf[i] + f * (xf[i + 1] - xf[i]), yf[i] + f * (yf[i + 1] - yf[i])
+
+        s0 = self._pos * arc[-1]
+        if self._anchor == "center":
+            cursor = s0 - total / 2.0
+        elif self._anchor == "end":
+            cursor = s0 - total
+        else:
+            cursor = s0
+
+        # Offset the whole label along the normal of its chord (first to last
+        # glyph); ``_point`` extrapolates past the curve ends along their tangents.
+        _, x0, y0 = _point(cursor)
+        _, x1, y1 = _point(cursor + total)
+        dx, dy = x1 - x0, y1 - y0
+        norm = float(np.hypot(dx, dy))
+        nx, ny = (-dy / norm, dx / norm) if norm else (0.0, 1.0)
+        scale = self._offset * renderer.points_to_pixels(1.0)
+        ox, oy = nx * scale, ny * scale
+
+        # ``cursor`` walks the label's left edge along the arc; each glyph is
+        # centered on its own midpoint and rotated to the local tangent.
+        for t, w in zip(self._chars, widths):
+            i, px, py = _point(cursor + w / 2.0)
+            t.set_position(inv.transform((px + ox, py + oy)))
+            t.set_rotation(np.degrees(rads[i]))
+            t.set_visible(True)
+            cursor += w
+
+
+def curved_text(ax: Axes, x: ArrayLike, y: ArrayLike, text: str, *,
+                pos: float = 0.5, anchor: str = "center", offset: float = 0.0,
+                **kwargs: Any) -> CurvedText:
+    """Draw ``text`` along the curve ``(x, y)`` on ``ax`` and return the artist.
+
+    Thin convenience wrapper around :class:`CurvedText`; see it for the meaning of
+    ``pos``, ``anchor``, and ``offset``. The axes is the first argument here,
+    matching matplotlib's axes-first helper functions, whereas :class:`CurvedText`
+    takes it after ``x, y, text`` to match :class:`matplotlib.text.Text`.
+    """
+    return CurvedText(x, y, text, ax, pos=pos, anchor=anchor, offset=offset,
+                      **kwargs)

curved_text-0.1.0/src/curved_text.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: curved-text
+Version: 0.1.0
+Summary: Draw text along an arbitrary curve in matplotlib, with arc-length positioning and a perpendicular offset.
+Author-email: Joseph Thiebes <joseph@thiebes.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thiebes/curved-text
+Project-URL: Source, https://github.com/thiebes/curved-text
+Project-URL: Issues, https://github.com/thiebes/curved-text/issues
+Project-URL: Changelog, https://github.com/thiebes/curved-text/blob/main/CHANGELOG.md
+Keywords: matplotlib,text,annotation,label,curve,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Matplotlib
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.20
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: examples
+Requires-Dist: seaborn>=0.11; extra == "examples"
+Requires-Dist: pandas>=1.3; extra == "examples"
+Dynamic: license-file
+
+# curved-text
+
+[![CI](https://github.com/thiebes/curved-text/actions/workflows/ci.yml/badge.svg)](https://github.com/thiebes/curved-text/actions/workflows/ci.yml)
+
+Draw text that follows an arbitrary curve in [matplotlib](https://matplotlib.org/).
+
+![Direct labeling versus a legend](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/01_direct_labeling.png)
+
+Label curves along their own paths instead of in a legend, so the eye never
+leaves the data to decode a colour key.
+
+Each character is placed in display coordinates and rotated to the local tangent
+of the curve, recomputed on every draw, so the label keeps following the curve
+through layout, resizing, and interactive panning or zooming. Placement is
+controlled by three independent parameters:
+
+- `pos` -- where the label is anchored along the curve, as a fraction of arc
+  length (`0.0` = first point, `1.0` = last).
+- `anchor` -- which part of the label lands at `pos`: `"start"`, `"center"`, or
+  `"end"`.
+- `offset` -- a perpendicular shift off the curve, in typographic points, along
+  the normal of the label's chord (positive is above a left-to-right curve).
+
+A label that overruns either end of the curve is not clipped: the curve is
+extended along its end tangent and the overrunning glyphs sit on that straight
+extension.
+
+## Install
+
+```bash
+pip install curved-text
+```
+
+Or, from a clone, an editable install:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from curved_text import curved_text
+
+x = np.linspace(0, 2 * np.pi, 400)
+y = np.sin(x)
+
+fig, ax = plt.subplots()
+ax.plot(x, y)
+curved_text(ax, x, y, "text that follows the curve",
+            pos=0.5, anchor="center", offset=6.0, color="C3")
+plt.show()
+```
+
+![A label following a sine wave](https://raw.githubusercontent.com/thiebes/curved-text/main/examples/images/02_sine_hello.png)
+
+More worked examples -- the three placement controls, overrun behaviour, and
+integration with seaborn and pandas -- are in [examples/](examples/README.md).
+
+The object-oriented form is also available:
+
+```python
+from curved_text import CurvedText
+
+CurvedText(x, y, "along the curve", ax, pos=0.2, anchor="start", offset=4.0)
+```
+
+Note the axes argument position: the `CurvedText` class takes it after `x, y,
+text` (matching `matplotlib.text.Text`), while the `curved_text` function takes it
+first (matching matplotlib's axes-first helper functions).
+
+Any extra keyword arguments (`color`, `fontsize`, `alpha`, `fontfamily`, ...) are
+passed through to each character's `matplotlib.text.Text`.
+
+## Works with seaborn, pandas, and other matplotlib-backed libraries
+
+`curved_text` needs a `matplotlib.axes.Axes`, so it works with any library that
+draws on matplotlib. seaborn's axes-level functions return an `Axes`, its
+figure-level functions expose one through `.axes`, and `pandas` `DataFrame.plot`
+returns an `Axes` as well. Pass that axes in directly:
+
+```python
+import seaborn as sns
+
+ax = sns.lineplot(data=df, x="x", y="y")
+curved_text(ax, df["x"], df["y"], "along the curve",
+            pos=0.5, anchor="center", offset=6.0)
+```
+
+## Notes
+
+- The curve `(x, y)` should be ordered along the curve (monotonic in arc length)
+  and have at least two points.
+- Arc length and the offset are computed in display space, so spacing and the
+  offset are correct at any DPI and figure size.
+
+## License
+
+MIT

curved_text-0.1.0/src/curved_text.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/curved_text/__init__.py
+src/curved_text/_core.py
+src/curved_text.egg-info/PKG-INFO
+src/curved_text.egg-info/SOURCES.txt
+src/curved_text.egg-info/dependency_links.txt
+src/curved_text.egg-info/requires.txt
+src/curved_text.egg-info/top_level.txt
+tests/test_core.py

curved_text-0.1.0/src/curved_text.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

curved_text-0.1.0/src/curved_text.egg-info/requires.txt

@@ -0,0 +1,9 @@
+matplotlib>=3.5
+numpy>=1.20
+
+[examples]
+seaborn>=0.11
+pandas>=1.3
+
+[test]
+pytest>=7.0

curved_text-0.1.0/src/curved_text.egg-info/top_level.txt

@@ -0,0 +1 @@
+curved_text

curved_text-0.1.0/tests/test_core.py

@@ -0,0 +1,188 @@
+"""Smoke and behaviour tests for curved_text.
+
+The Agg backend is selected in conftest.py before pyplot is imported.
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+
+from curved_text import CurvedText, curved_text
+
+
+def _draw(fig):
+    """Force a draw so CurvedText positions its glyphs."""
+    fig.canvas.draw()
+
+
+def test_places_one_artist_per_character():
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 1, 50)
+    ct = curved_text(ax, x, np.sin(x), "abc", pos=0.5, anchor="center")
+    assert len(ct._chars) == 3
+    _draw(fig)
+    assert all(t.get_visible() for t in ct._chars)
+    plt.close(fig)
+
+
+def test_anchor_shifts_label_along_curve():
+    # A straight horizontal curve so arc length maps to x directly.
+    fig, ax = plt.subplots()
+    ax.set_xlim(0, 10)
+    ax.set_ylim(0, 1)
+    x = np.linspace(0, 10, 100)
+    y = np.full_like(x, 0.5)
+    start = curved_text(ax, x, y, "word", pos=0.5, anchor="start")
+    end = curved_text(ax, x, y, "word", pos=0.5, anchor="end")
+    _draw(fig)
+    # "start" puts the text to the right of "end" at the same pos.
+    sx = np.mean([t.get_position()[0] for t in start._chars])
+    ex = np.mean([t.get_position()[0] for t in end._chars])
+    assert sx > ex
+    plt.close(fig)
+
+
+def test_offset_moves_perpendicular():
+    fig, ax = plt.subplots()
+    ax.set_xlim(0, 10)
+    ax.set_ylim(0, 10)
+    x = np.linspace(0, 10, 100)
+    y = np.full_like(x, 5.0)
+    flat = curved_text(ax, x, y, "word", pos=0.5, anchor="center", offset=0.0)
+    lifted = curved_text(ax, x, y, "word", pos=0.5, anchor="center", offset=10.0)
+    _draw(fig)
+    fy = np.mean([t.get_position()[1] for t in flat._chars])
+    ly = np.mean([t.get_position()[1] for t in lifted._chars])
+    # Positive offset is above a left-to-right curve.
+    assert ly > fy
+    plt.close(fig)
+
+
+def test_offset_is_dpi_invariant_in_points():
+    # The offset is specified in typographic points, so the same point value must
+    # produce the same data-space displacement regardless of figure DPI.
+    def displacement(dpi):
+        fig, ax = plt.subplots(dpi=dpi)
+        ax.set_xlim(0, 10)
+        ax.set_ylim(0, 10)
+        x = np.linspace(0, 10, 100)
+        y = np.full_like(x, 5.0)
+        flat = curved_text(ax, x, y, "word", pos=0.5, anchor="center", offset=0.0)
+        lifted = curved_text(ax, x, y, "word", pos=0.5, anchor="center",
+                             offset=10.0)
+        _draw(fig)
+        fy = np.mean([t.get_position()[1] for t in flat._chars])
+        ly = np.mean([t.get_position()[1] for t in lifted._chars])
+        plt.close(fig)
+        return ly - fy
+
+    assert displacement(72) == pytest.approx(displacement(144), rel=0.02)
+
+
+def test_overrun_is_not_clipped():
+    # Anchor the start of a long label past the right end of a short curve; the
+    # overrunning glyphs should ride the tangent extension, all still visible.
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 1, 20)
+    ct = curved_text(ax, x, np.zeros_like(x), "a long label", pos=1.0,
+                     anchor="start")
+    _draw(fig)
+    assert all(t.get_visible() for t in ct._chars)
+    plt.close(fig)
+
+
+def test_left_overrun_is_not_clipped():
+    # The symmetric case: anchor the end of a long label before the left end of a
+    # short curve so the label rides the left tangent extension.
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 1, 20)
+    ct = curved_text(ax, x, np.zeros_like(x), "a long label", pos=0.0,
+                     anchor="end")
+    _draw(fig)
+    assert all(t.get_visible() for t in ct._chars)
+    plt.close(fig)
+
+
+def test_degenerate_curve_does_not_raise():
+    # A curve whose points are all identical has zero arc length; drawing must
+    # short-circuit cleanly rather than raising.
+    fig, ax = plt.subplots()
+    x = np.full(10, 3.0)
+    y = np.full(10, 3.0)
+    ct = curved_text(ax, x, y, "abc", pos=0.5, anchor="center")
+    _draw(fig)
+    assert len(ct._chars) == 3
+    plt.close(fig)
+
+
+def test_wrapper_matches_class():
+    # curved_text is a thin wrapper; for the same inputs the two forms must place
+    # glyphs identically despite the different argument order.
+    fig, ax = plt.subplots()
+    ax.set_xlim(0, 10)
+    ax.set_ylim(0, 1)
+    x = np.linspace(0, 10, 100)
+    y = np.full_like(x, 0.5)
+    via_fn = curved_text(ax, x, y, "word", pos=0.5, anchor="center")
+    via_cls = CurvedText(x, y, "word", ax, pos=0.5, anchor="center")
+    _draw(fig)
+    for a, b in zip(via_fn._chars, via_cls._chars):
+        assert a.get_position() == pytest.approx(b.get_position())
+    plt.close(fig)
+
+
+def test_set_zorder_lifts_glyphs_above_container():
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 1, 10)
+    ct = curved_text(ax, x, np.zeros_like(x), "ab", pos=0.5, anchor="center")
+    ct.set_zorder(5)
+    assert ct.get_zorder() == 5
+    assert all(t.get_zorder() == 6 for t in ct._chars)
+    plt.close(fig)
+
+
+def test_remove_drops_child_glyphs():
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 1, 10)
+    ct = curved_text(ax, x, np.zeros_like(x), "ab", pos=0.5, anchor="center")
+    chars = list(ct._chars)
+    ct.remove()
+    children = ax.get_children()
+    assert ct not in children
+    assert all(t not in children for t in chars)
+    plt.close(fig)
+
+
+def test_redraw_is_idempotent():
+    # Layout is recomputed every draw; two draws of an unchanged figure must yield
+    # the same glyph positions.
+    fig, ax = plt.subplots()
+    ax.set_xlim(0, 10)
+    ax.set_ylim(0, 10)
+    x = np.linspace(0, 10, 100)
+    ct = curved_text(ax, x, np.sin(x) + 5.0, "stable", pos=0.5, anchor="center",
+                     offset=8.0)
+    _draw(fig)
+    first = [t.get_position() for t in ct._chars]
+    _draw(fig)
+    second = [t.get_position() for t in ct._chars]
+    for a, b in zip(first, second):
+        assert a == pytest.approx(b)
+    plt.close(fig)
+
+
+def test_validates_inputs():
+    fig, ax = plt.subplots()
+    with pytest.raises(ValueError):
+        CurvedText([0.0], [0.0], "x", ax)            # too few points
+    with pytest.raises(ValueError):
+        CurvedText([0, 1], [0, 1], "x", ax, anchor="middle")  # bad anchor
+    plt.close(fig)
+
+
+def test_rejects_non_finite_input():
+    fig, ax = plt.subplots()
+    with pytest.raises(ValueError):
+        CurvedText([0.0, np.nan, 1.0], [0.0, 0.0, 0.0], "x", ax)
+    with pytest.raises(ValueError):
+        CurvedText([0.0, 1.0], [0.0, np.inf], "x", ax)
+    plt.close(fig)