figtune 1.0.0__py3-none-any.whl

figtune/__init__.py

@@ -0,0 +1,5 @@
+"""figtune — matplotlib figure를 GUI로 미세조정하고 코드로 남기는 도구."""
+
+# 버전의 유일한 출처. pyproject가 이 값을 읽는다(dynamic version).
+# 두 곳에 적으면 한쪽만 고쳐져 배포판과 패키지가 서로 다른 버전을 말한다.
+__version__ = "1.0.0"

figtune/cli.py

@@ -0,0 +1,285 @@
+"""figtune 명령줄 진입점.
+
+서브커맨드는 PowerPoint 애드인이 호출할 안정된 계약이기도 하다.
+출력 형식과 종료 코드를 함부로 바꾸지 말 것.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import i18n
+from .i18n import t as _t
+
+SUBCOMMANDS = {"edit", "render", "refresh", "merge", "normalize"}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="figtune",
+        description=_t("matplotlib figure를 GUI로 미세조정하고 코드로 남깁니다."))
+    ap.add_argument("--lang", choices=(*i18n.LANGUAGES, "auto"),
+                    help=_t("메시지 언어 (기본: 시스템 설정을 따름)"))
+    sub = ap.add_subparsers(dest="cmd")
+
+    def common(p):
+        p.add_argument("--python", metavar="PATH",
+                       help=_t("스크립트를 실행할 인터프리터 "
+                               "(다른 venv/얼려진 앱인 경우)"))
+        p.add_argument("--dpi", type=int, default=300)
+        return p
+
+    e = common(sub.add_parser(
+        "edit", help=_t("GUI로 편집 (PowerPoint 애드인이 호출)")))
+    e.add_argument("script")
+    e.add_argument("--spec-in", metavar="PATH",
+                   help=_t("시작 spec (없으면 디스크에서)"))
+    e.add_argument("--spec-out", metavar="PATH",
+                   help=_t("저장 시 spec을 여기에도 기록"))
+    e.add_argument("--png-out", metavar="PATH",
+                   help=_t("저장 시 이미지를 여기에도 기록"))
+
+    r = common(sub.add_parser("render", help=_t("GUI 없이 이미지만 생성")))
+    r.add_argument("script")
+    r.add_argument("--spec-in", metavar="PATH")
+    r.add_argument("-o", "--out", required=True)
+
+    f = common(sub.add_parser(
+        "refresh", help=_t("pptx 안의 figtune 그림을 모두 재생성")))
+    f.add_argument("deck")
+    f.add_argument("-o", "--out", help=_t("다른 파일로 저장 (기본: 덮어쓰기)"))
+    f.add_argument("--check", action="store_true",
+                   help=_t("쓰지 않고 무엇이 바뀌는지만 보고"))
+
+    m = common(sub.add_parser(
+        "merge", help=_t("여러 패널 스크립트를 하나의 figure로 합침")))
+    m.add_argument("scripts", nargs="+", help=_t("패널 스크립트들 (배치 순서대로)"))
+    m.add_argument("-o", "--out", required=True,
+                   help=_t("생성할 병합 스크립트 (.py)"))
+    m.add_argument("--rows", type=int)
+    m.add_argument("--cols", type=int)
+    m.add_argument("--panel-size", default="4x3", metavar="WxH",
+                   help=_t("패널 하나의 크기(인치). 기본 4x3"))
+    m.add_argument("--labels", default="({a})",
+                   help=_t("패널 라벨 서식. 기본 '({a})'. 끄려면 빈 문자열"))
+    m.add_argument("--svg", metavar="PATH",
+                   help=_t("모드 B가 불가능할 때 SVG 합성으로 대신 출력"))
+    m.add_argument("--edit", action="store_true", help=_t("생성 후 GUI를 연다"))
+    m.add_argument("--normalize", action="store_true",
+                   help=_t("정규형이 아닌 스크립트를 먼저 *_norm.py로 변환"))
+
+    z = sub.add_parser("normalize", help=_t("스크립트를 정규형으로 변환"))
+    z.add_argument("scripts", nargs="+")
+    z.add_argument("--check", action="store_true",
+                   help=_t("변환하지 않고 판정만"))
+    z.add_argument("--in-place", action="store_true",
+                   help=_t("원본을 덮어쓴다 (기본은 *_norm.py 생성)"))
+    return ap
+
+
+def _grid(n: int, rows: int | None, cols: int | None) -> tuple[int, int]:
+    """행/열이 지정되지 않으면 논문에서 흔한 모양으로 고른다."""
+    if rows and cols:
+        return rows, cols
+    if rows:
+        return rows, -(-n // rows)
+    if cols:
+        return -(-n // cols), cols
+    return ({1: (1, 1), 2: (1, 2), 3: (1, 3), 4: (2, 2),
+             5: (2, 3), 6: (2, 3), 8: (2, 4), 9: (3, 3)}.get(n)
+            or (-(-n // 3), 3))
+
+
+def _load_spec(path):
+    from .core.spec import Spec
+    return Spec.load(path) if path else None
+
+
+def _early_lang(argv: list[str]) -> str | None:
+    """도움말 문구도 번역되어야 하므로 파서를 만들기 전에 언어를 정한다."""
+    for i, a in enumerate(argv):
+        if a == "--lang" and i + 1 < len(argv):
+            return argv[i + 1]
+        if a.startswith("--lang="):
+            return a.split("=", 1)[1]
+    return None
+
+
+def _insert_default_subcommand(argv: list[str]) -> None:
+    """하위 호환: `figtune script.py` 는 `figtune edit script.py`.
+
+    앞에 붙은 전역 옵션(--lang en 등)을 건너뛰고 첫 위치 인자를 본다.
+    """
+    i = 0
+    while i < len(argv) and argv[i].startswith("-"):
+        i += 2 if argv[i] == "--lang" else 1
+    if i < len(argv) and argv[i] not in SUBCOMMANDS:
+        argv.insert(i, "refresh" if argv[i].lower().endswith(".pptx") else "edit")
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    i18n.init(_early_lang(argv))
+    _insert_default_subcommand(argv)
+
+    args = _build_parser().parse_args(argv)
+    if args.cmd is None:
+        _build_parser().print_help()
+        return 2
+
+    if args.cmd == "refresh":
+        deck = Path(args.deck)
+        if not deck.exists():
+            print(_t("파일 없음: {path}", path=deck), file=sys.stderr)
+            return 2
+        from .office import pptx_link as PL
+        result = PL.refresh_deck(deck, args.out, python=args.python,
+                                 check_only=args.check)
+        verb = _t("변경예정") if args.check else _t("갱신")
+        for label in result.updated:
+            d = result.data_changes.get(label) or {}
+            marks = []
+            if d.get("changed"):
+                marks.append(_t("데이터 수정 {n}", n=len(d["changed"])))
+            if d.get("added"):
+                marks.append(_t("추가 {n}", n=len(d["added"])))
+            if d.get("removed"):
+                marks.append(_t("사라짐 {n}", n=len(d["removed"])))
+            note = f"  [{', '.join(marks)}]" if marks else ""
+            print(f"{verb}  {label}{note}")
+        for label, why in result.skipped:
+            print(_t("건너뜀 {label}: {why}", label=label, why=why),
+                  file=sys.stderr)
+        print(result.summary())
+        return 1 if result.skipped and not result.updated else 0
+
+    if args.cmd == "normalize":
+        return _normalize(args)
+
+    if args.cmd == "merge":
+        return _merge(args)
+
+    script = Path(args.script)
+    if not script.exists():
+        print(_t("파일 없음: {path}", path=script), file=sys.stderr)
+        return 2
+
+    if args.cmd == "render":
+        import matplotlib
+        matplotlib.use("Agg")
+        from .core.session import Session
+        s = Session(python=args.python)
+        rep = s.open(script, spec=_load_spec(args.spec_in))
+        if rep.stale:
+            print(_t("경고: 지문 불일치 {n}건", n=len(rep.stale)),
+                  file=sys.stderr)
+        s.export(args.out, dpi=args.dpi)
+        print(args.out)
+        return 0
+
+    from .ui.qt.main import launch
+    return launch(script, python=args.python, spec_in=args.spec_in,
+                  spec_out=args.spec_out, png_out=args.png_out, dpi=args.dpi,
+                  lang=args.lang)
+
+
+def _normalize(args) -> int:
+    from .core import normalize as N
+
+    rc = 0
+    for name in args.scripts:
+        p = Path(name)
+        if not p.exists():
+            print(_t("파일 없음: {path}", path=p), file=sys.stderr)
+            rc = 2
+            continue
+        if args.check:
+            rep = N.analyze(p.read_text(encoding="utf-8"))
+            mark = "OK  " if rep.ok else _t("불가")
+            print(f"{mark} {p}: {rep.reasons[0]}")
+            for extra in rep.reasons[1:]:
+                print(f"       {extra}")
+            rc = rc or (0 if rep.ok else 1)
+            continue
+        dst, rep = N.normalize_file(p, in_place=args.in_place)
+        if dst is None:
+            print(f"{_t('불가')} {p}", file=sys.stderr)
+            for r in rep.reasons:
+                print(f"       {r}", file=sys.stderr)
+            rc = 1
+        else:
+            note = _t(" (이미 정규형)") if rep.n_plot_stmts == 0 else ""
+            print(f"OK   {p} → {dst}{note}")
+    return rc
+
+
+def _merge(args) -> int:
+    from .core.montage_build import (MontageSpec, PanelRef,
+                                     can_use_subplot_mode,
+                                     generate_subplot_script)
+
+    scripts = [Path(s) for s in args.scripts]
+    missing = [str(s) for s in scripts if not s.exists()]
+    if missing:
+        print(_t("파일 없음: {path}", path=", ".join(missing)), file=sys.stderr)
+        return 2
+
+    if getattr(args, "normalize", False):
+        from .core import normalize as N
+        converted = []
+        for sc in scripts:
+            dst, rep = N.normalize_file(sc)
+            if dst is None:
+                print(_t("정규화 실패: {path}", path=sc), file=sys.stderr)
+                for r in rep.reasons:
+                    print(f"  {r}", file=sys.stderr)
+                return 1
+            if dst != sc:
+                print(_t("정규화  {src} → {dst}", src=sc, dst=dst))
+            converted.append(dst)
+        scripts = converted
+
+    rows, cols = _grid(len(scripts), args.rows, args.cols)
+    try:
+        w, h = (float(v) for v in args.panel_size.lower().split("x"))
+    except ValueError:
+        print(_t("--panel-size 형식은 WxH 입니다 (예: 4x3)"), file=sys.stderr)
+        return 2
+
+    mspec = MontageSpec(rows=rows, cols=cols,
+                        label_template=args.labels or "",
+                        auto_label=bool(args.labels),
+                        panels=[PanelRef(script=str(s.resolve()))
+                                for s in scripts])
+
+    out = Path(args.out)
+    try:
+        generate_subplot_script(mspec, out, base_dir=Path.cwd(),
+                                panel_size=(w, h))
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        if not args.svg:
+            print(_t("\n원본을 고칠 수 없다면 --svg PATH 로 SVG 합성을 쓰세요. "
+                     "다만 그 결과는 하나의 Figure가 아니며 통째로 편집할 수 "
+                     "없습니다."), file=sys.stderr)
+            return 1
+        from .core import montage as M
+        from .core.montage_build import build as build_montage
+        result = build_montage(mspec, base_dir=Path.cwd(), python=args.python)
+        M.write(result, args.svg)
+        print(_t("{path}  (SVG 합성 — 하나의 Figure가 아닙니다)", path=args.svg))
+        return 0
+
+    print(_t("{path}  ({rows}×{cols}, 패널 {n}개)",
+             path=out, rows=rows, cols=cols, n=len(scripts)))
+    print(_t("평범한 matplotlib 스크립트입니다. figtune으로 열어 편집하세요:"))
+    print(f"  figtune {out}")
+    if args.edit:
+        from .ui.qt.main import launch
+        return launch(out, python=args.python, lang=args.lang)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

figtune/config.py

@@ -0,0 +1,50 @@
+"""사용자 설정 파일.
+
+세션을 넘어 기억해야 하는 것만 담는다 (언어 선택, 한 번만 띄우는 안내 등).
+그림이나 spec에 영향을 주는 값은 절대 넣지 않는다 — 그런 값이 여기 들어가면
+같은 spec이 사람마다 다른 그림을 내게 되고, 재현 가능성이 무너진다.
+
+설정을 못 읽거나 못 써도 동작은 계속되어야 한다. 설정은 편의일 뿐이다.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+def path() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming"
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "figtune" / "config.json"
+
+
+def load() -> dict:
+    try:
+        data = json.loads(path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def get(key: str, default=None):
+    return load().get(key, default)
+
+
+def set(key: str, value) -> None:      # noqa: A001 - 설정 키 접근자라 이 이름이 맞다
+    """value가 None이면 키를 지운다 (= 기본값으로 되돌림)."""
+    cfg = load()
+    if value is None:
+        cfg.pop(key, None)
+    else:
+        cfg[key] = value
+    p = path()
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n",
+                     encoding="utf-8")
+    except OSError:
+        pass

figtune/core/__init__.py

@@ -0,0 +1,2 @@
+from .session import Session, LoadReport  # noqa: F401
+from .spec import Spec, UserText  # noqa: F401

figtune/core/apply.py

@@ -0,0 +1,146 @@
+"""spec → 살아있는 Figure.
+
+적용 순서가 중요하다. 범례는 handle/label이 확정된 뒤에 마지막으로 만들어야
+하고, 레이아웃 엔진은 수동 위치 조정과 충돌하므로 별도 취급한다.
+"""
+
+from __future__ import annotations
+
+from . import props as P
+from . import selector as sel
+from .spec import Spec, UserText
+
+# 적용 순서와 정규 정렬 순서는 같은 표를 쓴다. 둘이 어긋나면 "저장한 대로
+# 다시 적용된다"는 보장이 깨진다.
+from .canon import KIND_ORDER as _ORDER
+
+
+class ApplyReport:
+    def __init__(self):
+        self.failed: list[tuple[str, str, str]] = []   # (path, prop, 사유)
+
+    def fail(self, path, prop, why):
+        self.failed.append((path, prop, str(why)))
+
+    def __bool__(self):
+        return not self.failed
+
+
+def transform_for(ax, coords: str):
+    if coords == "data":
+        return ax.transData
+    if coords == "figure":
+        return ax.figure.transFigure
+    return ax.transAxes
+
+
+def ensure_text(fig, t: UserText):
+    """user text artist를 만들거나 찾아서 최신 상태로 만든다."""
+    try:
+        ax = fig.axes[t.axes]
+    except IndexError:
+        return None
+    art = None
+    for cand in ax.texts:
+        if getattr(cand, "_figtune_id", None) == t.id:
+            art = cand
+            break
+    if art is None:
+        art = ax.text(t.position[0], t.position[1], t.text,
+                      transform=transform_for(ax, t.coords))
+        art._figtune_id = t.id
+    else:
+        art.set_text(t.text)
+        art.set_position((t.position[0], t.position[1]))
+        art.set_transform(transform_for(ax, t.coords))
+    for k, v in t.style().items():
+        try:
+            getattr(art, f"set_{k}")(v)
+        except Exception:
+            pass
+    return art
+
+
+def apply_spec(fig, spec: Spec, report: ApplyReport | None = None) -> ApplyReport:
+    report = report or ApplyReport()
+
+    # user text를 먼저 만들어야 그에 대한 override를 걸 수 있다
+    for t in spec.texts:
+        try:
+            ensure_text(fig, t)
+        except Exception as exc:
+            report.fail(sel.usertext(t.axes, t.id), "-", exc)
+
+    def rank(path: str) -> int:
+        try:
+            return _ORDER.get(sel.parse(path).kind, 8)
+        except sel.SelectorError:
+            return 8
+
+    for path in sorted(spec.overrides, key=rank):
+        over = spec.overrides[path]
+        try:
+            kind = sel.parse(path).kind
+        except sel.SelectorError as exc:
+            report.fail(path, "-", exc)
+            continue
+
+        if kind == "figlegend":
+            try:
+                P.apply_fig_legend(fig, over)
+            except Exception as exc:
+                report.fail(path, "figlegend", exc)
+            continue
+
+        if kind == "legend":
+            try:
+                P.apply_legend(fig.axes[sel.parse(path).axes], over)
+            except Exception as exc:
+                report.fail(path, "legend", exc)
+            continue
+
+        view_keys = {"elev", "azim", "roll", "dist_zoom"}
+        if kind == "axes" and view_keys & set(over):
+            try:
+                P.apply_view(fig.axes[sel.parse(path).axes], over)
+            except Exception as exc:
+                report.fail(path, "view", exc)
+
+        for name, value in over.items():
+            if kind == "axes" and name in view_keys:
+                continue
+            try:
+                P.apply(fig, path, name, value)
+            except Exception as exc:
+                report.fail(path, name, exc)
+
+    return report
+
+
+def apply_one(fig, spec: Spec, path: str, name: str, value) -> None:
+    """GUI 편집 한 건을 spec과 figure에 동시에 반영한다."""
+    spec.set(path, name, value)
+    if sel.parse(path).kind == "legend":
+        P.apply_legend(fig.axes[sel.parse(path).axes], spec.of(path))
+    else:
+        P.apply(fig, path, name, value)
+
+
+def sync_text(fig, spec: Spec, tid: str) -> None:
+    t = spec.text_by_id(tid)
+    if t is not None:
+        ensure_text(fig, t)
+
+
+def remove_text(fig, spec: Spec, tid: str) -> None:
+    t = spec.text_by_id(tid)
+    if t is None:
+        return
+    try:
+        ax = fig.axes[t.axes]
+        for cand in list(ax.texts):
+            if getattr(cand, "_figtune_id", None) == tid:
+                cand.remove()
+    except IndexError:
+        pass
+    spec.remove_text(tid)