rsplotlib 0.1.9__cp313-cp313-win_amd64.whl

rsplotlib/ticker.py

@@ -0,0 +1,6 @@
+"""rsplotlib.ticker - 向后兼容的导入模块
+
+此模块提供从旧路径 `rsplotlib.ticker` 导入的支持。
+实际实现在 `rsplotlib.ticks.ticker` 中。
+"""
+from .ticks.ticker import *  # noqa: F403, F401

rsplotlib/ticks/__init__.py

@@ -0,0 +1,2 @@
+"""rsplotlib.ticks - 刻度管理"""
+from . import ticker  # noqa: F401

rsplotlib/ticks/ticker.py

@@ -0,0 +1,269 @@
+"""rsplotlib.ticker - Matplotlib ticker 兼容接口
+
+提供刻度定位器和格式化器类。
+底层实现已迁移至 Rust 层，此模块为保持完整 Python 接口的薄包装层。
+"""
+
+from .. import rsplotlib as _rs
+
+
+class Tick:
+    """刻度对象"""
+
+    def __init__(self, loc, label=''):
+        self.loc = loc
+        self.label = label
+
+
+# ==================== 定位器 ====================
+
+class Locator:
+    """刻度定位器基类"""
+
+    def tick_values(self, vmin, vmax):
+        raise NotImplementedError
+
+    def __call__(self):
+        return []
+
+
+class MultipleLocator(Locator):
+    """倍数定位器 - 刻度位置是基数的整数倍
+
+    底层实现: Rust MultipleLocator
+
+    Args:
+        base: 刻度间距
+    """
+
+    def __init__(self, base=1.0):
+        self.base = base
+        self._impl = _rs.MultipleLocator(base)
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+    def __repr__(self):
+        return f'MultipleLocator(base={self.base})'
+
+
+class MaxNLocator(Locator):
+    """最大数量定位器 - 最多 nbins+1 个刻度
+
+    底层实现: Rust MaxNLocator
+
+    Args:
+        nbins: 最大区间数 (默认: 10)
+        integer: 是否只使用整数 (默认: False)
+    """
+
+    def __init__(self, nbins=10, integer=False):
+        self.nbins = nbins
+        self.integer = integer
+        self._impl = _rs.MaxNLocator(nbins, integer)
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+    def __repr__(self):
+        return f'MaxNLocator(nbins={self.nbins}, integer={self.integer})'
+
+
+class AutoLocator(MaxNLocator):
+    """自动定位器
+
+    底层实现: Rust MaxNLocator(nbins=10)
+    """
+
+    def __init__(self):
+        super().__init__(nbins=10)
+
+
+class AutoMinorLocator(Locator):
+    """自动次要刻度定位器
+
+    底层实现: Rust AutoMinorLocator
+
+    Args:
+        n: 每个主要间隔中的次要刻度数 (默认: 5)
+    """
+
+    def __init__(self, n=5):
+        self.n = n
+        self._impl = _rs.AutoMinorLocator(n)
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+    def __repr__(self):
+        return f'AutoMinorLocator(n={self.n})'
+
+
+class FixedLocator(Locator):
+    """固定位置定位器
+
+    底层实现: Rust FixedLocator
+    """
+
+    def __init__(self, locs):
+        self.locs = list(locs)
+        self._impl = _rs.FixedLocator(list(locs))
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+
+class LinearLocator(Locator):
+    """线性定位器
+
+    底层实现: Rust LinearLocator
+    """
+
+    def __init__(self, numticks=10):
+        self.numticks = numticks
+        self._impl = _rs.LinearLocator(numticks)
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+
+class LogLocator(Locator):
+    """对数定位器
+
+    底层实现: Rust LogLocator
+    """
+
+    def __init__(self, base=10.0, numticks=10):
+        self.base = base
+        self.numticks = numticks
+        self._impl = _rs.LogLocator(base, numticks)
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+
+class NullLocator(Locator):
+    """空定位器 - 不显示刻度
+
+    底层实现: Rust NullLocator
+    """
+
+    def __init__(self):
+        self._impl = _rs.NullLocator()
+
+    def tick_values(self, vmin, vmax):
+        return self._impl.tick_values(vmin, vmax)
+
+
+# ==================== 格式化器 ====================
+
+class Formatter:
+    """刻度格式化器基类"""
+
+    def format_ticks(self, values):
+        return [self(val) for val in values]
+
+    def __call__(self, value):
+        return str(value)
+
+
+class NullFormatter(Formatter):
+    """不显示标签
+
+    底层实现: Rust NullFormatter
+    """
+
+    def __init__(self):
+        self._impl = _rs.NullFormatter()
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class FixedFormatter(Formatter):
+    """固定标签格式化器
+
+    底层实现: Rust FixedFormatter
+    """
+
+    def __init__(self, seq):
+        self.seq = list(seq)
+        self._impl = _rs.FixedFormatter([str(s) for s in seq])
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class FormatStrFormatter(Formatter):
+    """格式化字符串
+
+    底层实现: Rust FormatStrFormatter
+    """
+
+    def __init__(self, fmt):
+        self.fmt = fmt
+        self._impl = _rs.FormatStrFormatter(fmt)
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class ScalarFormatter(Formatter):
+    """标量格式化器
+
+    底层实现: Rust ScalarFormatter
+    """
+
+    def __init__(self):
+        self._impl = _rs.ScalarFormatter()
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class LogFormatterSciNotation(Formatter):
+    """科学计数法格式化器
+
+    底层实现: Rust LogFormatterSciNotation
+    """
+
+    def __init__(self):
+        self._impl = _rs.LogFormatterSciNotation()
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class FuncFormatter(Formatter):
+    """函数格式化器
+
+    底层实现: Rust FuncFormatter
+    """
+
+    def __init__(self, func):
+        self.func = func
+        self._impl = _rs.FuncFormatter(func)
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+class StrMethodFormatter(Formatter):
+    """字符串方法格式化器
+
+    底层实现: Rust StrMethodFormatter
+    """
+
+    def __init__(self, fmt):
+        self.fmt = fmt
+        self._impl = _rs.StrMethodFormatter(fmt)
+
+    def __call__(self, value):
+        return self._impl.__call__(value)
+
+
+# ==================== 便捷函数 ====================
+
+def auto_locator():
+    """创建自动定位器"""
+    return MaxNLocator(nbins=10, integer=False)

rsplotlib/utils/__init__.py

@@ -0,0 +1,2 @@
+"""rsplotlib.utils - 工具模块"""
+from . import _font_resolver, _rcparams, style  # noqa: F401

rsplotlib/utils/_font_resolver.py

@@ -0,0 +1,34 @@
+"""rsplotlib._font_resolver - 字体族名 → 字体文件路径解析
+
+将 matplotlib 风格的无衬线字体族名（如 "Arial Unicode MS"、"Helvetica Neue"）
+映射到本地字体文件路径。找不到时返回 None，由调用方决定回退到默认字体。
+
+底层实现: Rust font_resolver
+"""
+
+from .. import rsplotlib as _rs
+
+
+def resolve_font_path(family: str) -> str or None:
+    """根据字体族名查找本地的字体文件路径。
+
+    底层实现: Rust resolve_font_path
+
+    Args:
+        family: 字体族名
+
+    Returns:
+        字体文件路径，找不到时返回 None
+    """
+    return _rs.resolve_font_path(family)
+
+
+def apply_rcparams_font() -> str or None:
+    """读取 rcParams["font.sans-serif"]，把第一个能解析到本地文件的字体注册到 plotters。
+
+    底层实现: Rust apply_rcparams_font
+
+    Returns:
+        实际注册的字体文件路径，如果没找到任何字体则返回 None
+    """
+    return _rs.apply_rcparams_font()

rsplotlib/utils/_rcparams.py

@@ -0,0 +1,101 @@
+"""rsplotlib._rcparams - Matplotlib 兼容的 rcParams 配置管理
+
+提供类似 matplotlib.rcParams 的全局配置字典，保存绘图相关的默认参数。
+
+**字体钩子**：当用户设置 `rcParams["font.sans-serif"]` 时，会自动调用
+Rust 的字体解析器 `apply_rcparams_font()`，把对应的字体文件注册到 plotters 的
+字体数据库中，从而真正影响文本渲染（而不是像普通 dict 一样只更新值）。
+"""
+import copy as _copy
+from typing import Any
+
+# 默认配置：与 matplotlib 保持一致的常用项
+_DEFAULT_RC = {
+    # 跨平台无衬线字体回退链：macOS/Windows 优先 Helvetica/Arial，其后回退到
+    # DejaVu Sans / Liberation Sans（Linux 常见字体，也是 matplotlib 的默认字体）。
+    # 这些名字按家族名从系统字体索引解析，不依赖具体安装路径，因此在没有
+    # Helvetica/Arial 的 Linux 上也能解析到真实字体，避免渲染时回退到无法解析的 "sans-serif"。
+    'font.sans-serif': ['Helvetica', 'Arial', 'DejaVu Sans', 'Liberation Sans', 'sans-serif'],
+    'axes.unicode_minus': True,
+    'font.size': 10,
+    'figure.figsize': [6.4, 4.8],
+    'figure.dpi': 100.0,
+}
+
+
+class RcParams(dict):
+    """与 matplotlib.rcParams 兼容的配置字典
+
+    区别于普通 dict：
+    1. 当访问不存在的键时返回 None 而不是抛出 KeyError。
+    2. **设置 `font.sans-serif` 时自动调用字体解析器**，把对应字体文件
+       注册到 plotters 的字体数据库中，使 plotters 真正使用用户指定的字体
+       渲染文字（而不是只更新一个不会生效的字符串列表）。
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.update(_DEFAULT_RC)
+
+    def __getitem__(self, key):
+        try:
+            return super().__getitem__(key)
+        except KeyError:
+            return None
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        super().__setitem__(key, value)
+        self._trigger_font_hook(key)
+
+    def update(self, *args, **kwargs):
+        super().update(*args, **kwargs)
+        # update 也需要触发字体钩子，否则初始化时默认字体不会被注册
+        if args:
+            other = args[0]
+            if isinstance(other, dict):
+                keys = other.keys()
+            else:
+                keys = [k for k, _ in other]
+        else:
+            keys = kwargs.keys()
+        if 'font.sans-serif' in keys:
+            self._trigger_font_hook('font.sans-serif')
+
+    def _trigger_font_hook(self, key: str) -> None:
+        # 字体钩子：用户在 Python 端改字体时同步通知字体注册
+        if key == 'font.sans-serif':
+            try:
+                # 延迟导入避免循环依赖
+                from .. import rsplotlib as _rs
+                from ._font_resolver import resolve_font_path
+                sans_serif = self.get('font.sans-serif')
+                if not sans_serif:
+                    return
+                if isinstance(sans_serif, str):
+                    candidates = [sans_serif]
+                else:
+                    candidates = list(sans_serif)
+                candidates = [c for c in candidates if c and c.lower() != 'sans-serif']
+                # 清空旧的字体栈
+                _rs.clear_font_stack()
+                # 注册所有字体
+                for family in candidates:
+                    path = resolve_font_path(family)
+                    if path is None:
+                        import os
+                        if os.path.isfile(family):
+                            path = family
+                    if path is not None:
+                        try:
+                            _rs.register_sans_serif_font(path, family)
+                        except Exception:
+                            pass
+            except Exception:
+                # 注册失败不影响 rcParams 写入
+                pass
+
+
+# 全局单例
+rcParams = RcParams()
+# 原始默认配置副本（用于 rcParams.reset() 等恢复操作）
+rcParamsOrig = _copy.deepcopy(rcParams)

rsplotlib/utils/style.py

@@ -0,0 +1,67 @@
+"""rsplotlib.style - Matplotlib style 兼容接口
+
+底层实现: Rust Style
+"""
+
+from .. import rsplotlib as _rs
+
+
+# ==================== 可用样式 ====================
+
+AVAILABLE_STYLES = [
+    'default',
+    'classic',
+    'ggplot',
+    'seaborn-v0_8',
+    'fast',
+    'fivethirtyeight',
+    'grayscale',
+    'dark_background',
+    'bmh',
+    'tableau-colorblind10',
+]
+
+
+class Style:
+    """样式管理器
+
+    底层实现: Rust Style
+    """
+
+    def __init__(self):
+        self._impl = _rs.Style()
+
+    def use(self, style_name):
+        """应用样式
+
+        Args:
+            style_name: 样式名称
+        """
+        self._impl.use_(style_name)
+
+    def available(self):
+        """返回可用样式列表"""
+        return self._impl.available()
+
+    @property
+    def current(self):
+        return self._impl.current
+
+
+# 全局样式实例
+style = Style()
+
+
+def use(style_name):
+    """应用样式（模块级函数）"""
+    style.use(style_name)
+
+
+def available():
+    """返回可用样式列表"""
+    return style.available()
+
+
+def current():
+    """返回当前样式名称"""
+    return style.current