graphica-plot 2.0.0__py3-none-any.whl

graphica/core/plugin_install.py

@@ -0,0 +1,82 @@
+"""プラグインの zip を展開してインストールする(取得はしない。信頼できる配布元のものだけを入れること)。"""
+import os
+import shutil
+import tempfile
+import uuid
+import zipfile
+
+from graphica.core.app_paths import get_user_plugins_dir
+
+
+class PluginInstallError(Exception):
+    """メッセージはそのまま利用者に見せる。"""
+
+
+def _reject_unsafe_members(zf: zipfile.ZipFile) -> None:
+    # zip-slip: 正規化して .. で始まるか絶対パスなら、target_dir の外に書くので拒否する
+    for member in zf.namelist():
+        normalized = os.path.normpath(member)
+        if normalized.startswith("..") or os.path.isabs(normalized):
+            raise PluginInstallError(
+                f"安全でないパスを含むzipファイルです(不正なエントリ: '{member}')。"
+            )
+
+
+def _find_plugin_root(staging_dir: str, zip_path: str) -> tuple[str, str]:
+    """(プラグイン本体のフォルダの絶対パス, 採用するフォルダ名)"""
+    if os.path.exists(os.path.join(staging_dir, "__init__.py")):
+        # __init__.py が zip の直下にある
+        name = os.path.splitext(os.path.basename(zip_path))[0]
+        return staging_dir, name
+
+    entries = [e for e in os.listdir(staging_dir) if os.path.isdir(os.path.join(staging_dir, e))]
+    if len(entries) == 1:
+        candidate = os.path.join(staging_dir, entries[0])
+        if os.path.exists(os.path.join(candidate, "__init__.py")):
+            # 1つのフォルダの中に __init__.py がある
+            return candidate, entries[0]
+
+    raise PluginInstallError(
+        "zip内に __init__.py を持つプラグインが見つかりませんでした。"
+        "プラグインフォルダそのもの、またはそのフォルダを1つだけ含むzipを指定してください。"
+    )
+
+
+def install_plugin_zip(zip_path: str, target_dir: str | None = None) -> str:
+    """target_dir(省略時は get_user_plugins_dir())に入れ、フォルダ名を返す。失敗は PluginInstallError。"""
+    if target_dir is None:
+        target_dir = get_user_plugins_dir()
+
+    if not zipfile.is_zipfile(zip_path):
+        raise PluginInstallError(f"'{zip_path}' は有効なzipファイルではありません。")
+
+    # 展開先は target_dir と同じボリュームに作る(最後の os.replace() を原子的な改名にするため)。
+    # 展開先の直下には __init__.py が無いので、プラグインとして誤って見つかることはない
+    staging_dir = tempfile.mkdtemp(prefix=".tmp_install_", dir=target_dir)
+    try:
+        try:
+            with zipfile.ZipFile(zip_path) as zf:
+                _reject_unsafe_members(zf)
+                zf.extractall(staging_dir)
+        except zipfile.BadZipFile as e:
+            raise PluginInstallError(f"zipファイルの展開に失敗しました: {e}") from e
+
+        plugin_root, plugin_name = _find_plugin_root(staging_dir, zip_path)
+        final_path = os.path.join(target_dir, plugin_name)
+
+        stale_path = None
+        if os.path.exists(final_path):
+            # 上書きのときは、既存のものを先に退避して最後に消す
+            stale_path = f"{final_path}.old-{uuid.uuid4().hex}"
+            os.replace(final_path, stale_path)
+
+        # zip の直下に __init__.py があった場合、改名までの一瞬だけ展開先が半端なプラグインに見える。
+        # 1つのプロセスで入れる前提なので、そのままにしている
+        os.replace(plugin_root, final_path)
+
+        if stale_path is not None:
+            shutil.rmtree(stale_path, ignore_errors=True)
+
+        return plugin_name
+    finally:
+        shutil.rmtree(staging_dir, ignore_errors=True)

graphica/core/plugin_manifest.py

@@ -0,0 +1,67 @@
+"""
+プラグインのマニフェスト(plugin.json)の読み込みと検証。
+
+プラグイン API の版は "主番号.小番号"。壊す変更で主番号を、互換のある追加で小番号を上げる。
+plugin.json の api_version は、主番号が本体と同じで小番号が本体以下なら読み込む
+(使う機能がそろっている)。合わないプラグインは import する前に弾く。
+entry_point キーは予約済みで未使用(常にパッケージの __init__.py の register(api) を呼ぶ)。
+"""
+import json
+import os
+from typing import Any
+
+PLUGIN_API_VERSION = "2.0"
+PLUGIN_MANIFEST_FILENAME = "plugin.json"
+
+_REQUIRED_MANIFEST_KEYS = ("name", "version", "api_version")
+
+
+class PluginManifestError(Exception):
+    """plugin.json が無い・壊れている・api_version が合わない(呼び出し側はそのプラグインを飛ばす)。"""
+
+
+def load_plugin_manifest(plugin_dir: str) -> dict[str, Any]:
+    """plugin_dir/plugin.json を辞書で返す。不正なら PluginManifestError。"""
+    manifest_path = os.path.join(plugin_dir, PLUGIN_MANIFEST_FILENAME)
+    if not os.path.exists(manifest_path):
+        raise PluginManifestError(
+            f"{PLUGIN_MANIFEST_FILENAME} が見つかりません(プラグインディレクトリ直下に必須です)。"
+        )
+
+    try:
+        with open(manifest_path, encoding='utf-8') as f:
+            manifest = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        raise PluginManifestError(f"{PLUGIN_MANIFEST_FILENAME} の読み込みに失敗しました: {e}") from e
+
+    if not isinstance(manifest, dict):
+        raise PluginManifestError(f"{PLUGIN_MANIFEST_FILENAME} はJSONオブジェクトである必要があります。")
+
+    missing_keys = [k for k in _REQUIRED_MANIFEST_KEYS if k not in manifest]
+    if missing_keys:
+        raise PluginManifestError(
+            f"{PLUGIN_MANIFEST_FILENAME} に必須キーがありません: {', '.join(missing_keys)}"
+        )
+
+    if not is_compatible_api_version(manifest["api_version"]):
+        raise PluginManifestError(
+            f"api_version '{manifest['api_version']}' はサポート対象外です"
+            f"(このGraphicaのプラグインAPIは '{PLUGIN_API_VERSION}'。主番号が同じで、"
+            f"小番号がこれ以下のプラグインを読み込めます)。"
+        )
+
+    return manifest
+
+
+def parse_api_version(text: object) -> tuple[int, int] | None:
+    """ "2.1" -> (2, 1)。形が違えば None。"""
+    parts = str(text).split(".")
+    if len(parts) != 2 or not all(p.isdigit() for p in parts):
+        return None
+    return int(parts[0]), int(parts[1])
+
+
+def is_compatible_api_version(plugin_api_version: object, app_api_version: str = PLUGIN_API_VERSION) -> bool:
+    plugin = parse_api_version(plugin_api_version)
+    app = parse_api_version(app_api_version)
+    return plugin is not None and app is not None and plugin[0] == app[0] and plugin[1] <= app[1]

graphica/core/plugin_testing.py

@@ -0,0 +1,213 @@
+"""
+プラグイン作者向けのテスト用の偽物。本体(Qt・QApplication)を起動せずにテストできる。
+
+    api = FakeGraphicaPluginAPI()
+    my_plugin.register(api)
+    ctx = FakePluginContext(datasets=[ds])
+    api.menu_actions[0].callback(ctx)
+    assert ctx.messages == [("info", "My Plugin", "3 点")]
+
+FakeGraphicaPluginAPI は本物の GraphicaPluginAPI と同じ公開メソッドを持ち、本物が拒む
+重複登録は同じく ValueError にする(偽物だけ通るとテストが通っても本体で失敗する)。
+tests/test_plugin_api_contract.py が両者のシグネチャの一致を確かめている。
+"""
+import tempfile
+
+from graphica.core.color_palettes import normalize_palettes
+from graphica.core.named_colors import add_named_color
+from graphica.core.plugin_context import PluginContext
+from graphica.core.plugin_types import PluginMenuAction
+from typing import TYPE_CHECKING, Any, Callable
+if TYPE_CHECKING:
+    from graphica.core.dataset import Dataset
+
+
+class FakeGraphicaPluginAPI:
+    """
+    登録内容を記録するだけの GraphicaPluginAPI。
+
+    Attributes:
+        menu_actions (list[PluginMenuAction]): 本物と同じ形。callback に FakePluginContext を渡して試せる。
+        panels (dict): 名前 -> {"widget_factory", "area"}。
+        そのほか fit_functions / importers / exporters / processors / analyzers / plot_types /
+        render_backends は、名前(または拡張子)をキーにした登録内容の辞書。
+    """
+
+    def __init__(self, plugin_name: str = "test_plugin") -> None:
+        self.plugin_name = plugin_name
+        self.fit_functions: dict[str, dict[str, Any]] = {}
+        self.menu_actions: list[PluginMenuAction] = []
+        self.importers: dict[str, dict[str, Any]] = {}
+        self.exporters: dict[str, dict[str, Any]] = {}
+        self.processors: dict[str, dict[str, Any]] = {}
+        self.analyzers: dict[str, dict[str, Any]] = {}
+        self.panels: dict[str, dict[str, Any]] = {}
+        self.plot_types: dict[str, dict[str, Any]] = {}
+        self.render_backends: dict[str, Any] = {}
+
+    def register_fit_function(self, name: str, func: Callable[..., Any], param_names: list[str],
+                              p0: list[float] | Callable[..., Any] | None = None) -> None:
+        if name in self.fit_functions:
+            raise ValueError(f"フィット関数 '{name}' は既に登録されています。")
+        self.fit_functions[name] = {"func": func, "param_names": param_names, "p0": p0}
+
+    def register_menu_action(self, text: str, callback: Callable[..., Any], shortcut: str | None = None) -> None:
+        self.menu_actions.append(PluginMenuAction(
+            text=text, callback=callback, shortcut=shortcut, plugin_name=self.plugin_name,
+        ))
+
+    def register_importer(self, extensions: list[str], loader: Callable[[str], Any], *, name: str | None = None,
+                          priority: int = 0) -> None:
+        # 本物は拡張子ごとに複数を優先度順で持つが、使える拡張子を確かめる用途にはこれで足りる。
+        for ext in extensions:
+            ext = ext.lower()
+            if not ext.startswith('.'):
+                ext = '.' + ext
+            self.importers[ext] = {"loader": loader, "name": name, "priority": priority}
+
+    def register_exporter(self, format_name: str, extension: str, writer: Callable[[Any, str], Any], *,
+                          name: str | None = None) -> None:
+        self.exporters[format_name.lower()] = {"extension": extension, "writer": writer, "name": name}
+
+    def register_processor(self, name: str, fn: Callable[[Any, dict[str, Any]], Any], *, category: str = "general",
+                           param_schema: list[dict[str, Any]] | None = None) -> None:
+        if name in self.processors:
+            raise ValueError(f"データ処理 '{name}' は既に登録されています。")
+        self.processors[name] = {"fn": fn, "category": category, "param_schema": list(param_schema or [])}
+
+    def register_analyzer(self, name: str, fn: Callable[[Any, dict[str, Any]], Any], *, output_kind: str = "table",
+                          param_schema: list[dict[str, Any]] | None = None) -> None:
+        if name in self.analyzers:
+            raise ValueError(f"解析 '{name}' は既に登録されています。")
+        self.analyzers[name] = {"fn": fn, "output_kind": output_kind, "param_schema": list(param_schema or [])}
+
+    def register_panel(self, name: str, widget_factory: Callable[..., Any], *, area: str = "right") -> None:
+        if name in self.panels:
+            raise ValueError(f"パネル '{name}' は既に登録されています。")
+        self.panels[name] = {"widget_factory": widget_factory, "area": area}
+
+    def register_plot_type(self, type_name: str, drawer: Callable[..., Any], *, requires_2d: bool = False) -> None:
+        if type_name in self.plot_types:
+            raise ValueError(f"プロット種別 '{type_name}' は既に登録されています。")
+        self.plot_types[type_name] = {"drawer": drawer, "requires_2d": requires_2d}
+
+    def register_render_backend(self, name: str, backend: Any) -> None:
+        if name in self.render_backends:
+            raise ValueError(f"描画バックエンド '{name}' は既に登録されています。")
+        self.render_backends[name] = {"backend": backend}
+
+
+class FakePluginContext(PluginContext):
+    """
+    メモリ上だけで動く PluginContext。本物と同じ検証をし、行った操作を記録する。
+
+    Args:
+        datasets (list[Dataset] | None): タブにあるデータセット。
+        current (Dataset | None): 選ばれているデータセット。
+        selected (list[Dataset] | None): 選択中のデータセット。省略時は current だけ。
+        plugin_name (str): show_message の既定のタイトル。
+        data_dir (str | None): 省略時は一時フォルダを作る。
+        named_colors (list[dict] | None) / color_palettes (dict | None) / color_cycle (list[str] | None):
+            色の初期値。
+
+    Attributes:
+        messages (list[tuple]): 表示したメッセージ ("info" または "error", タイトル, 本文)。
+        undo_descriptions (list[str]): Undo 履歴に積まれた操作の説明。
+        redraw_count (int): redraw() が呼ばれた回数。
+    """
+
+    def __init__(self, datasets: "list[Dataset] | None" = None, current: "Dataset | None" = None,
+                 selected: "list[Dataset] | None" = None, plugin_name: str = "test_plugin",
+                 data_dir: str | None = None, named_colors: list[dict[str, str]] | None = None,
+                 color_palettes: dict[str, list[str]] | None = None, color_cycle: list[str] | None = None) -> None:
+        self._datasets = list(datasets or [])
+        self._current = current
+        self._selected = list(selected) if selected is not None else ([current] if current else [])
+        self._plugin_name = plugin_name
+        self._data_dir = data_dir
+        self._named_colors = [dict(e) for e in (named_colors or [])]
+        self._palettes = normalize_palettes(color_palettes or {})
+        self._color_cycle = list(color_cycle or ["#1f77b4", "#ff7f0e", "#2ca02c"])
+        self._datasets_changed_callbacks: list[Callable[[], Any]] = []
+        self._selection_changed_callbacks: list[Callable[[Dataset | None], Any]] = []
+        self.messages: list[tuple[str, str, str]] = []  # ("info" / "error", タイトル, 本文)
+        self.undo_descriptions: list[str | None] = []
+        self.redraw_count = 0
+
+    def datasets(self) -> "list[Dataset]":
+        return list(self._datasets)
+
+    def current_dataset(self) -> "Dataset | None":
+        return self._current
+
+    def selected_datasets(self) -> "list[Dataset]":
+        return list(self._selected)
+
+    def add_dataset(self, dataset: "Dataset", description: str | None = None) -> None:
+        self._datasets.append(dataset)
+        self.undo_descriptions.append(description or f"[{self._plugin_name}] データセットの追加")
+        self.fire_datasets_changed()
+
+    def set_dataset_properties(self, dataset: "Dataset", values: dict[str, Any], description: str | None = None) -> None:
+        unknown = sorted(k for k in values if not hasattr(dataset, k))
+        if unknown:
+            raise AttributeError(f"Dataset に無い属性です: {', '.join(unknown)}")
+        for key, value in values.items():
+            setattr(dataset, key, value)
+        self.undo_descriptions.append(description or f"[{self._plugin_name}] プロパティの変更")
+        self.fire_datasets_changed()
+
+    def redraw(self) -> None:
+        self.redraw_count += 1
+
+    def on_datasets_changed(self, callback: Callable[[], Any]) -> None:
+        self._datasets_changed_callbacks.append(callback)
+
+    def on_selection_changed(self, callback: Callable[["Dataset | None"], Any]) -> None:
+        self._selection_changed_callbacks.append(callback)
+
+    def fire_datasets_changed(self) -> None:
+        """テスト用: データセットが変わったときの通知を送る。"""
+        for callback in list(self._datasets_changed_callbacks):
+            callback()
+
+    def select(self, dataset: "Dataset | None") -> None:
+        """テスト用: データセット一覧で dataset を選んだことにし、通知を送る。"""
+        self._current = dataset
+        self._selected = [dataset] if dataset is not None else []
+        for callback in list(self._selection_changed_callbacks):
+            callback(dataset)
+
+    @property
+    def parent_widget(self) -> Any:
+        return None
+
+    def show_message(self, text: str, title: str | None = None) -> None:
+        self.messages.append(("info", title or self._plugin_name, text))
+
+    def show_error(self, text: str, title: str | None = None) -> None:
+        self.messages.append(("error", title or self._plugin_name, text))
+
+    @property
+    def data_dir(self) -> str:
+        if self._data_dir is None:
+            self._data_dir = tempfile.mkdtemp(prefix=f"graphica_{self._plugin_name}_")
+        return self._data_dir
+
+    def named_colors(self) -> list[dict[str, str]]:
+        return [dict(e) for e in self._named_colors]
+
+    def set_named_colors(self, entries: list[dict[str, str]]) -> None:
+        validated: list[dict[str, str]] = []
+        for entry in entries:
+            validated = add_named_color(validated, entry.get("name"), entry.get("color"))
+        self._named_colors = validated
+
+    def color_palettes(self) -> dict[str, list[str]]:
+        return {name: list(colors) for name, colors in self._palettes.items()}
+
+    def set_color_palettes(self, palettes: dict[str, list[str]]) -> None:
+        self._palettes = normalize_palettes(palettes)
+
+    def active_color_cycle(self) -> list[str]:
+        return list(self._color_cycle)

graphica/core/plugin_types.py

@@ -0,0 +1,118 @@
+"""プラグイン API で共有する型。登録されたフックの記録と、失敗の表し方。"""
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable
+
+
+class PluginHookKind(Enum):
+    IMPORTER = "importer"
+    EXPORTER = "exporter"
+    PROCESSOR = "processor"
+    ANALYZER = "analyzer"
+    PANEL = "panel"
+    PLOT_TYPE = "plot_type"
+    FIT_FUNCTION = "fit_function"
+    MENU_ACTION = "menu_action"
+    RENDER_BACKEND = "render_backend"
+
+
+@dataclass
+class PluginRegistrationError:
+    """register_xxx の1回の呼び出しが失敗したこと。"""
+    plugin_name: str
+    hook_kind: PluginHookKind
+    message: str
+    exception: Exception | None = None
+
+
+@dataclass
+class PluginMenuAction:
+    text: str
+    callback: Callable[..., Any]  # (PluginContext) -> None
+    shortcut: str | None
+    plugin_name: str
+
+
+@dataclass
+class PluginImporter:
+    extension: str            # ピリオド付きの小文字(例: ".jdx")
+    loader: Callable[[str], Any]  # (パス) -> pandas.DataFrame
+    name: str                 # エラー表示用(通常はプラグイン名)
+    priority: int = 0
+
+
+@dataclass
+class PluginExporter:
+    format_name: str
+    extension: str            # ピリオド付きの小文字
+    writer: Callable[[Any, str], Any]  # (matplotlib の Figure, 出力パス) -> None
+    name: str
+
+
+@dataclass
+class PluginProcessor:
+    name: str
+    fn: Callable[[Any, dict[str, Any]], Any]  # (Dataset, 入力値) -> Dataset。元の Dataset は変えない
+    category: str
+    param_schema: list[dict[str, Any]]  # 入力フォームの定義(register_processor の説明を参照)
+    plugin_name: str
+
+
+@dataclass
+class AnalysisResult:
+    """
+    register_analyzer の fn が返す解析結果。どれも省略できる。
+
+    Attributes:
+        table (pandas.DataFrame | None): 結果の表。CSV に保存できる形で表示する。
+        annotations (list[dict] | None): 現在の軸に追加する注釈(Undo できる)。
+        new_datasets (list[Dataset] | None): 追加するデータセット(Undo できる)。
+    """
+    table: Any = None
+    annotations: list[dict[str, Any]] | None = None
+    new_datasets: list[Any] | None = None
+
+
+@dataclass
+class PluginAnalyzer:
+    name: str
+    fn: Callable[[Any, dict[str, Any]], Any]  # (Dataset, 入力値) -> AnalysisResult
+    output_kind: str          # 表示上の分類だけ
+    param_schema: list[dict[str, Any]]
+    plugin_name: str
+
+
+@dataclass
+class PluginPanel:
+    name: str
+    widget_factory: Callable[..., Any]  # (PluginContext) -> QWidget。タブごとに1回呼ぶ
+    area: str                 # "right"/"left"/"top"/"bottom"。Qt への対応付けは GUI 側(core は Qt に依存しない)
+    plugin_name: str
+
+
+@dataclass
+class PluginPlotType:
+    type_name: str
+    drawer: Callable[..., Any]  # (Dataset, Axes, x, y) -> Artist | None
+    requires_2d: bool         # 予約(動作に影響しない)
+    plugin_name: str
+
+
+class RenderBackend:
+    """描画バックエンドの型の予約。描画には未接続で、持つべきメソッドも未定。"""
+
+
+@dataclass
+class PluginRenderBackend:
+    name: str
+    backend: "RenderBackend"
+    plugin_name: str
+
+
+class PluginExecutionError(Exception):
+    """プラグインのフックの実行時の失敗。文字列にするとプラグイン名が付くので、そのまま表示に使える。"""
+
+    def __init__(self, plugin_name: str, message: str) -> None:
+        self.plugin_name = plugin_name
+        self.message = message
+        super().__init__(f"[{plugin_name}] {message}")

graphica/core/provenance.py

@@ -0,0 +1,19 @@
+"""派生データセットの由来(Dataset.provenance)。core/methods_text.py がここから「方法」文を作る。"""
+from datetime import datetime, timezone
+from typing import Any
+
+
+def build_provenance(operation: str, params: dict[str, Any], source_datasets: list[Any]) -> dict[str, Any]:
+    """
+    Args:
+        operation (str): 操作の名前(methods_text の説明の引き当てに使う)。
+        params (dict): 操作の設定。pickle と JSON の両方で往復できるよう素の Python 型だけにする。
+        source_datasets (list[Dataset]): 元になったデータセット(複数なら合成)。
+    """
+    return {
+        'operation': operation,
+        'params': params,
+        'source_dataset_ids': [ds.dataset_id for ds in source_datasets],
+        'source_dataset_names': [ds.name for ds in source_datasets],
+        'timestamp': datetime.now(timezone.utc).isoformat(),
+    }

graphica/core/report_export.py

@@ -0,0 +1,51 @@
+"""グラフの画像と処理の「方法」の文をまとめたレポート(HTML)。GUI には依存しない。"""
+import base64
+import datetime
+import html
+
+from graphica.core.methods_text import generate_methods_text
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from graphica.models.project import ProjectModel
+
+
+def collect_methods_sections(project: "ProjectModel") -> list[tuple[str, str]]:
+    """履歴を持つデータセットごとの (名前, 方法の文)。元データは含めない。"""
+    return [
+        (ds.name, generate_methods_text(ds, project))
+        for ds in project.datasets
+        if ds.provenance
+    ]
+
+
+def generate_html_report(image_png_bytes: bytes, methods_sections: list[tuple[str, str]], title: str = "") -> str:
+    """画像を base64 で埋め込んだ1ファイルで完結する HTML。title が空なら既定のタイトル。"""
+    title_text = title.strip() or "実験レポート"
+    title_html = html.escape(title_text)
+    generated_at = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
+    image_b64 = base64.b64encode(image_png_bytes).decode('ascii')
+
+    if methods_sections:
+        items = "".join(
+            f"<li><b>{html.escape(name)}</b>: {html.escape(text)}</li>"
+            for name, text in methods_sections
+        )
+        methods_html = f"<ul>{items}</ul>"
+    else:
+        methods_html = "<p>(処理履歴を持つデータセットはありません)</p>"
+
+    return (
+        "<!doctype html>\n"
+        "<html><head><meta charset=\"utf-8\">"
+        f"<title>{title_html}</title>\n"
+        "<style>\n"
+        "body { font-family: sans-serif; max-width: 900px; margin: 2em auto; padding: 0 1em; }\n"
+        "img { max-width: 100%; border: 1px solid #ccc; }\n"
+        "</style></head><body>\n"
+        f"<h1>{title_html}</h1>\n"
+        f"<p>生成日時: {generated_at}</p>\n"
+        f"<img src=\"data:image/png;base64,{image_b64}\" alt=\"plot\">\n"
+        "<h2>方法</h2>\n"
+        f"{methods_html}\n"
+        "</body></html>\n"
+    )