kavacha 0.0.2__py3-none-any.whl

kavacha/__init__.py

@@ -0,0 +1,16 @@
+__version__ = "0.0.2"
+
+# The names a caller reaches for. `spec`, `build`, `bundle` and `probe` need nothing but fastcore,
+# so describing an app and asking what a build would do works on a machine that cannot build one.
+from .probe import backend, framework_python, is_framework, running_from, shell_ready, wait_for_http
+from .spec import App, doc_types, mypyc_modules, tree
+from .bundle import finish, frozen_distribution, graft, link_duplicates, strip_zip
+from .build import build, check, lock_requirements, read_stamp, write_stamp
+# The vocabulary a host builds its menu table in. Dataclasses over stdlib, so importing them
+# costs no pywebview and no AppKit.
+from .menus import Binding, Js, MenuItem, Std
+
+__all__ = ['backend', 'framework_python', 'is_framework', 'running_from', 'shell_ready',
+           'wait_for_http', 'App', 'doc_types', 'mypyc_modules', 'tree', 'finish',
+           'frozen_distribution', 'graft', 'link_duplicates', 'strip_zip', 'build', 'check',
+           'lock_requirements', 'read_stamp', 'write_stamp', 'Binding', 'Js', 'MenuItem', 'Std']

kavacha/_modidx.py

@@ -0,0 +1,89 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/kavacha',
+                'doc_host': 'https://vedicreader.github.io',
+                'git_url': 'https://github.com/vedicreader/kavacha',
+                'lib_path': 'kavacha'},
+  'syms': { 'kavacha.build': { 'kavacha.build.build': ('build.html#build', 'kavacha/build.py'),
+                               'kavacha.build.build_venv': ('build.html#build_venv', 'kavacha/build.py'),
+                               'kavacha.build.check': ('build.html#check', 'kavacha/build.py'),
+                               'kavacha.build.git_stamp': ('build.html#git_stamp', 'kavacha/build.py'),
+                               'kavacha.build.lock_requirements': ('build.html#lock_requirements', 'kavacha/build.py'),
+                               'kavacha.build.read_stamp': ('build.html#read_stamp', 'kavacha/build.py'),
+                               'kavacha.build.run': ('build.html#run', 'kavacha/build.py'),
+                               'kavacha.build.stamp_path': ('build.html#stamp_path', 'kavacha/build.py'),
+                               'kavacha.build.write_stamp': ('build.html#write_stamp', 'kavacha/build.py')},
+            'kavacha.bundle': { 'kavacha.bundle._lib_dir': ('bundle.html#_lib_dir', 'kavacha/bundle.py'),
+                                'kavacha.bundle.finish': ('bundle.html#finish', 'kavacha/bundle.py'),
+                                'kavacha.bundle.frozen_distribution': ('bundle.html#frozen_distribution', 'kavacha/bundle.py'),
+                                'kavacha.bundle.graft': ('bundle.html#graft', 'kavacha/bundle.py'),
+                                'kavacha.bundle.install_modern_icon': ('bundle.html#install_modern_icon', 'kavacha/bundle.py'),
+                                'kavacha.bundle.link_duplicates': ('bundle.html#link_duplicates', 'kavacha/bundle.py'),
+                                'kavacha.bundle.strip_zip': ('bundle.html#strip_zip', 'kavacha/bundle.py')},
+            'kavacha.icons': { 'kavacha.icons._open': ('icons.html#_open', 'kavacha/icons.py'),
+                               'kavacha.icons._resized': ('icons.html#_resized', 'kavacha/icons.py'),
+                               'kavacha.icons.favicon': ('icons.html#favicon', 'kavacha/icons.py'),
+                               'kavacha.icons.icns': ('icons.html#icns', 'kavacha/icons.py'),
+                               'kavacha.icons.ico': ('icons.html#ico', 'kavacha/icons.py'),
+                               'kavacha.icons.icons_for': ('icons.html#icons_for', 'kavacha/icons.py'),
+                               'kavacha.icons.iconset': ('icons.html#iconset', 'kavacha/icons.py')},
+            'kavacha.menus': { 'kavacha.menus.Binding': ('menus.html#binding', 'kavacha/menus.py'),
+                               'kavacha.menus.Binding.bound': ('menus.html#binding.bound', 'kavacha/menus.py'),
+                               'kavacha.menus.Js': ('menus.html#js', 'kavacha/menus.py'),
+                               'kavacha.menus.MenuItem': ('menus.html#menuitem', 'kavacha/menus.py'),
+                               'kavacha.menus.MenuItem.__post_init__': ('menus.html#menuitem.__post_init__', 'kavacha/menus.py'),
+                               'kavacha.menus.Std': ('menus.html#std', 'kavacha/menus.py')},
+            'kavacha.probe': { 'kavacha.probe.backend': ('probe.html#backend', 'kavacha/probe.py'),
+                               'kavacha.probe.framework_python': ('probe.html#framework_python', 'kavacha/probe.py'),
+                               'kavacha.probe.is_framework': ('probe.html#is_framework', 'kavacha/probe.py'),
+                               'kavacha.probe.py_version': ('probe.html#py_version', 'kavacha/probe.py'),
+                               'kavacha.probe.running_from': ('probe.html#running_from', 'kavacha/probe.py'),
+                               'kavacha.probe.shell_ready': ('probe.html#shell_ready', 'kavacha/probe.py'),
+                               'kavacha.probe.wait_for_http': ('probe.html#wait_for_http', 'kavacha/probe.py')},
+            'kavacha.spec': { 'kavacha.spec.App': ('spec.html#app', 'kavacha/spec.py'),
+                              'kavacha.spec.App.__post_init__': ('spec.html#app.__post_init__', 'kavacha/spec.py'),
+                              'kavacha.spec.App.bundle_name': ('spec.html#app.bundle_name', 'kavacha/spec.py'),
+                              'kavacha.spec.App.excluded': ('spec.html#app.excluded', 'kavacha/spec.py'),
+                              'kavacha.spec.App.info_plist': ('spec.html#app.info_plist', 'kavacha/spec.py'),
+                              'kavacha.spec.App.out': ('spec.html#app.out', 'kavacha/spec.py'),
+                              'kavacha.spec.App.py2app_options': ('spec.html#app.py2app_options', 'kavacha/spec.py'),
+                              'kavacha.spec.App.py2exe_options': ('spec.html#app.py2exe_options', 'kavacha/spec.py'),
+                              'kavacha.spec.doc_types': ('spec.html#doc_types', 'kavacha/spec.py'),
+                              'kavacha.spec.mypyc_modules': ('spec.html#mypyc_modules', 'kavacha/spec.py'),
+                              'kavacha.spec.tree': ('spec.html#tree', 'kavacha/spec.py')},
+            'kavacha.window': { 'kavacha.window.ShellApi': ('window.html#shellapi', 'kavacha/window.py'),
+                                'kavacha.window.ShellApi.open_folder': ('window.html#shellapi.open_folder', 'kavacha/window.py'),
+                                'kavacha.window.ShellApi.pick_folder': ('window.html#shellapi.pick_folder', 'kavacha/window.py'),
+                                'kavacha.window.ShellApi.recent': ('window.html#shellapi.recent', 'kavacha/window.py'),
+                                'kavacha.window._decorate': ('window.html#_decorate', 'kavacha/window.py'),
+                                'kavacha.window._disabled': ('window.html#_disabled', 'kavacha/window.py'),
+                                'kavacha.window._dock_delegates': ('window.html#_dock_delegates', 'kavacha/window.py'),
+                                'kavacha.window._point': ('window.html#_point', 'kavacha/window.py'),
+                                'kavacha.window._recent_target': ('window.html#_recent_target', 'kavacha/window.py'),
+                                'kavacha.window._title': ('window.html#_title', 'kavacha/window.py'),
+                                'kavacha.window._unreachable': ('window.html#_unreachable', 'kavacha/window.py'),
+                                'kavacha.window.backend': ('window.html#backend', 'kavacha/window.py'),
+                                'kavacha.window.dock_menu': ('window.html#dock_menu', 'kavacha/window.py'),
+                                'kavacha.window.errstr': ('window.html#errstr', 'kavacha/window.py'),
+                                'kavacha.window.eval_js': ('window.html#eval_js', 'kavacha/window.py'),
+                                'kavacha.window.install_menu_patch': ('window.html#install_menu_patch', 'kavacha/window.py'),
+                                'kavacha.window.keep_running_in_dock': ('window.html#keep_running_in_dock', 'kavacha/window.py'),
+                                'kavacha.window.mac_key': ('window.html#mac_key', 'kavacha/window.py'),
+                                'kavacha.window.make_window': ('window.html#make_window', 'kavacha/window.py'),
+                                'kavacha.window.menu_bar': ('window.html#menu_bar', 'kavacha/window.py'),
+                                'kavacha.window.menu_chord': ('window.html#menu_chord', 'kavacha/window.py'),
+                                'kavacha.window.menus': ('window.html#menus', 'kavacha/window.py'),
+                                'kavacha.window.off_main_thread': ('window.html#off_main_thread', 'kavacha/window.py'),
+                                'kavacha.window.open_window': ('window.html#open_window', 'kavacha/window.py'),
+                                'kavacha.window.quiet_text_substitution': ('window.html#quiet_text_substitution', 'kavacha/window.py'),
+                                'kavacha.window.run_shell': ('window.html#run_shell', 'kavacha/window.py'),
+                                'kavacha.window.shell_api': ('window.html#shell_api', 'kavacha/window.py'),
+                                'kavacha.window.shell_ready': ('window.html#shell_ready', 'kavacha/window.py'),
+                                'kavacha.window.splash': ('window.html#splash', 'kavacha/window.py'),
+                                'kavacha.window.start_cdp': ('window.html#start_cdp', 'kavacha/window.py'),
+                                'kavacha.window.use_app': ('window.html#use_app', 'kavacha/window.py'),
+                                'kavacha.window.wait_for_http': ('window.html#wait_for_http', 'kavacha/window.py'),
+                                'kavacha.window.warm_cdp': ('window.html#warm_cdp', 'kavacha/window.py'),
+                                'kavacha.window.watch_open_events': ('window.html#watch_open_events', 'kavacha/window.py'),
+                                'kavacha.window.window_size': ('window.html#window_size', 'kavacha/window.py')}}}

kavacha/build.py

@@ -0,0 +1,143 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/03_build.ipynb.
+
+# %% ../nbs/03_build.ipynb #ec24be20
+from __future__ import annotations
+import json, os, shutil, subprocess, sys, time
+from fastcore.all import Path
+
+from .probe import framework_python, is_framework, py_version, running_from
+from .bundle import finish
+
+# %% auto #0
+__all__ = ['STAMP', 'REEXEC', 'run', 'lock_requirements', 'build_venv', 'git_stamp', 'stamp_path', 'write_stamp', 'read_stamp',
+           'check', 'build']
+
+# %% ../nbs/03_build.ipynb #7b260a31
+STAMP = 'build.json'
+REEXEC = 'KAVACHA_BUILD_VENV'
+
+def run(*args, **kw):
+    print('·', ' '.join(str(a) for a in args))
+    return subprocess.run([str(a) for a in args], check=True, **kw)
+
+# %% ../nbs/03_build.ipynb #98cf7446
+def lock_requirements(root, extras=(), out=None):
+    "Export `uv.lock` as pinned requirements, or return `None`."
+    root = Path(root)
+    if not (root/'uv.lock').exists(): return None
+    args = ['uv', 'export', '--frozen', '--no-dev', '--no-hashes', '--no-emit-project',
+            '--format', 'requirements-txt']
+    for e in extras: args += ['--extra', e]
+    try: got = subprocess.run(args, cwd=str(root), capture_output=True, text=True, timeout=300)
+    except (OSError, subprocess.SubprocessError): return None
+    if got.returncode or not got.stdout.strip():
+        print(f'· uv export failed; resolving from pyproject instead: {got.stderr.strip()[:200]}')
+        return None
+    out = Path(out or root/'packaging'/'.app-venv'/'app-requirements.txt')
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(got.stdout)
+    return out
+
+# %% ../nbs/03_build.ipynb #0431c2e0
+def build_venv(python, venv, root, extras=(), force=False):
+    "A plain build venv using `python`."
+    venv = Path(venv)
+    if force: shutil.rmtree(venv, ignore_errors=True)
+    exe = venv/'bin'/'python'
+    if exe.exists() and py_version(exe) != py_version(python):
+        print(f'· rebuilding {venv.name}: it is on {py_version(exe)}, this build wants {py_version(python)}')
+        shutil.rmtree(venv, ignore_errors=True)
+    if not exe.exists():
+        venv.parent.mkdir(parents=True, exist_ok=True)
+        run(python, '-m', 'venv', venv)
+    run(exe, '-m', 'pip', 'install', '--upgrade', '--quiet', 'pip', 'setuptools', 'wheel')
+    spec = f'{root}[{",".join(extras)}]' if extras else str(root)
+    if (req := lock_requirements(root, extras, venv/'app-requirements.txt')) is not None:
+        run(exe, '-m', 'pip', 'install', '--quiet', '--upgrade', '-r', req)
+        run(exe, '-m', 'pip', 'install', '--quiet', '--no-deps', '-e', spec)
+    else: run(exe, '-m', 'pip', 'install', '--quiet', '-e', spec)
+    return exe
+
+# %% ../nbs/03_build.ipynb #43eee4ee
+def git_stamp(root, version=''):
+    "The commit the tree is on and whether it is dirty, or `None` outside a checkout."
+    def git(*a):
+        r = subprocess.run(['git', *a], cwd=str(root), capture_output=True, text=True, timeout=30)
+        return r.stdout.strip() if not r.returncode else None
+    try: sha = git('rev-parse', 'HEAD')
+    except (OSError, subprocess.SubprocessError): return None
+    if not sha: return None
+    return {'commit': sha, 'dirty': bool(git('status', '--porcelain', '--untracked-files=no')),
+            'version': version, 'built': time.strftime('%Y-%m-%dT%H:%M:%S')}
+
+def stamp_path(bundle):
+    "Where the build stamp lives inside `bundle`, on either platform."
+    b = Path(bundle)
+    return (b/'Contents'/'Resources'/STAMP) if b.suffix == '.app' else (b/STAMP)
+
+def write_stamp(bundle, root, version=''):
+    "Write and return the bundle's source stamp."
+    if (st := git_stamp(root, version)) is None:
+        st = {'commit': '', 'dirty': False, 'version': version,
+              'built': time.strftime('%Y-%m-%dT%H:%M:%S')}
+    p = stamp_path(bundle)
+    if p.parent.is_dir(): p.write_text(json.dumps(st, indent=1) + '\n')
+    return st
+
+def read_stamp(bundle):
+    "The stamp `bundle` was built with, or None when it has none."
+    try: return json.loads(stamp_path(bundle).read_text())
+    except (OSError, ValueError): return None
+
+# %% ../nbs/03_build.ipynb #accc2d7f
+def check(spec, root, venv=None):
+    "What a build would do here, without doing it. Answers on any platform, Linux included."
+    root, venv = Path(root), Path(venv or Path(root)/'packaging'/'.app-venv')
+    rows = {'platform': sys.platform, 'interpreter': sys.executable,
+            'app': spec.name, 'out': str(spec.out(root))}
+    if sys.platform not in ('darwin', 'win32'):
+        rows['freezer'] = f'none — {sys.platform} builds nothing; macOS and Windows build on their own OS'
+    else: rows['freezer'] = 'py2app' if sys.platform == 'darwin' else 'py2exe'
+    if sys.platform == 'darwin':
+        rows['framework_build'] = is_framework()
+        if not rows['framework_build']:
+            rows['would_rebuild'] = str(venv)
+            rows['on'] = str(framework_python() or '')
+    try:
+        import webview  # noqa: F401
+        rows['pywebview'] = 'installed'
+    except ImportError: rows['pywebview'] = 'MISSING'
+    rows['running'] = running_from(spec.out(root))
+    return rows
+
+# %% ../nbs/03_build.ipynb #6215af9c
+def build(spec, root, setup_py, venv=None, alias=False, force=False, rebuild_venv=False,
+          identity=None):
+    "Build `spec` into `root/dist`, using framework Python on macOS."
+    root, venv = Path(root), Path(venv or Path(root)/'packaging'/'.app-venv')
+    out = spec.out(root)
+    if not force and (live := running_from(out)):
+        raise SystemExit(
+            f'{out} is running as pid {", ".join(map(str, live))}. Quit it first, or pass force.\n'
+            'A build replaces the standard library the running app imports from, and it fails from '
+            'then on with a zip error that says nothing about the build.')
+    if sys.platform == 'darwin' and not is_framework():
+        if os.environ.get(REEXEC):
+            raise SystemExit(f'{sys.executable} is still not a framework build; run `check` to see why')
+        if (found := framework_python()) is None:
+            raise SystemExit('py2app needs a framework Python, and this one is a standalone build '
+                             'whose stdlib extension modules are not files.\n'
+                             'Install one and try again:  brew install python@3.12')
+        print(f'framework Python: {found}')
+        exe = build_venv(found, venv, root, spec.extras, force=rebuild_venv)
+        run(exe, sys.argv[0], *(['--alias'] if alias else []), env={**os.environ, REEXEC: '1'})
+        return out
+    args = [sys.executable, str(setup_py)] + (['py2app'] if sys.platform == 'darwin' else [])
+    if alias and sys.platform == 'darwin': args.append('--alias')
+    run(*args, cwd=str(root))
+    if out.exists() and sys.platform == 'darwin':
+        for name, where in finish(out, spec, identity).items(): print(f'  {name}: {where}')
+    st = write_stamp(out, root, spec.version)
+    print(f"\nbuilt {out}\n  from {st['commit'][:12]}"
+          f"{' with uncommitted changes' if st['dirty'] else ''}")
+    return out

kavacha/bundle.py

@@ -0,0 +1,102 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/02_bundle.ipynb.
+
+# %% ../nbs/02_bundle.ipynb #4767bcd3
+from __future__ import annotations
+import hashlib, os, shutil, sys, zipfile
+from fastcore.all import Path, first
+
+# %% auto #0
+__all__ = ['graft', 'link_duplicates', 'strip_zip', 'install_modern_icon', 'finish', 'frozen_distribution']
+
+# %% ../nbs/02_bundle.ipynb #2b553810
+def graft(app, name, python=None):
+    "Put the installed `name` package into a built bundle."
+    import importlib.util
+    spec = importlib.util.find_spec(name)
+    if spec is None or not spec.submodule_search_locations:
+        raise SystemExit(f'cannot graft {name}: it is not installed here')
+    src = Path(first(spec.submodule_search_locations))
+    lib = _lib_dir(app)
+    want = 'python%d.%d' % (python or sys.version_info[:2])
+    if lib.name != want: raise SystemExit(f'cannot graft {name}: bundle is {lib.name}, this is {want}')
+    dest = lib/name
+    for stray in lib.glob(f'{name}.*'): stray.unlink()
+    shutil.rmtree(dest, ignore_errors=True)
+    shutil.copytree(src, dest, ignore=shutil.ignore_patterns('__pycache__', '*.pyc'))
+    return dest.relative_to(app)
+
+def _lib_dir(app):
+    "The bundle's `lib/pythonX.Y`, on either platform's layout."
+    app = Path(app)
+    for base in (app/'Contents'/'Resources'/'lib', app/'lib', app):
+        if (hit := first(sorted(base.glob('python3.*')))) is not None: return Path(hit)
+    raise SystemExit(f'{app} has no lib/python3.* to write into')
+
+# %% ../nbs/02_bundle.ipynb #f054e586
+def link_duplicates(app, names, floor=1_000_000):
+    "Hardlink duplicate package files and return megabytes saved."
+    lib = _lib_dir(app)
+    seen, saved = {}, 0
+    for name in names:
+        for f in sorted((lib/name).rglob('*')):
+            if not f.is_file() or f.is_symlink() or f.stat().st_size < floor: continue
+            key = (f.stat().st_size, hashlib.sha256(f.read_bytes()).hexdigest())
+            if (other := seen.get(key)) is None: seen[key] = f; continue
+            if os.stat(f).st_ino == os.stat(other).st_ino: continue
+            saved += f.stat().st_size
+            f.unlink(); os.link(other, f)
+    return round(saved / 1e6)
+
+# %% ../nbs/02_bundle.ipynb #9e0b3d82
+def strip_zip(app, prefixes=()):
+    "Remove matching entries from the bundle archive and return megabytes saved."
+    z = first(sorted(_lib_dir(app).parent.glob('python3*.zip')))
+    if not z or not prefixes: return 0
+    prefixes = tuple(prefixes)
+    keep, dropped = [], 0
+    with zipfile.ZipFile(z) as src:
+        for info in src.infolist():
+            if info.filename.startswith(prefixes): dropped += info.compress_size; continue
+            keep.append((info, src.read(info.filename)))
+    if not dropped: return 0
+    tmp = Path(str(z) + '.new')
+    with zipfile.ZipFile(tmp, 'w', zipfile.ZIP_DEFLATED) as out:
+        for info, data in keep: out.writestr(info, data)
+    tmp.replace(z)
+    return round(dropped / 1e6)
+
+# %% ../nbs/02_bundle.ipynb #22fd45d1
+def install_modern_icon(app, icon, identity=None, deployment_target='14.0'):
+    "Install an Icon Composer icon before signing, retaining the ICNS fallback."
+    icon = Path(icon) if icon else None
+    if icon is None or not icon.is_dir(): return None
+    try: from iconmage import install_icon
+    except ImportError:
+        print('  iconmage not installed; keeping the ICNS icon alone '
+              '(uv tool install git+https://github.com/AnswerDotAI/iconmage.git)')
+        return None
+    try: return install_icon(icon, app, deployment_target=deployment_target, identity=identity)
+    except Exception as e:
+        print(f'  Icon Composer icon not installed ({type(e).__name__}: {e}); keeping the ICNS one')
+        return None
+
+# %% ../nbs/02_bundle.ipynb #4f455d17
+def finish(app, spec, identity=None):
+    "Everything a bundle needs after the freezer wrote it, in the order it needs it."
+    out = {}
+    for name in spec.grafted: out[name] = str(graft(app, name))
+    dropped = [*spec.unreachable, *[f'{n}/' for n in spec.grafted]]
+    out['stripped_mb'] = strip_zip(app, dropped)
+    out['linked_mb'] = link_duplicates(app, spec.grafted)
+    out['modern_icon'] = bool(install_modern_icon(app, spec.modern_icon, identity))
+    return out
+
+# %% ../nbs/02_bundle.ipynb #8be45025
+def frozen_distribution():
+    "Return a setuptools distribution that ignores project dependencies."
+    from setuptools.dist import Distribution
+    class Frozen(Distribution):
+        def parse_config_files(self, *args, **kwargs):
+            super().parse_config_files(*args, **kwargs)
+            self.install_requires = []
+    return Frozen

kavacha/icons.py

@@ -0,0 +1,81 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/05_icons.ipynb.
+
+# %% ../nbs/05_icons.ipynb #1752ff04
+from __future__ import annotations
+import subprocess
+from fastcore.all import Path
+
+# %% auto #0
+__all__ = ['ICNS_SIZES', 'ICO_SIZES', 'iconset', 'icns', 'ico', 'favicon', 'icons_for']
+
+# %% ../nbs/05_icons.ipynb #f00569e4
+ICNS_SIZES = ((16, 'icon_16x16'), (32, 'icon_16x16@2x'), (32, 'icon_32x32'),
+              (64, 'icon_32x32@2x'), (128, 'icon_128x128'), (256, 'icon_128x128@2x'),
+              (256, 'icon_256x256'), (512, 'icon_256x256@2x'), (512, 'icon_512x512'),
+              (1024, 'icon_512x512@2x'))
+
+ICO_SIZES = (16, 24, 32, 48, 64, 128, 256)
+
+# %% ../nbs/05_icons.ipynb #894757de
+def _open(src):
+    "The source image as RGBA, square, or the reason it cannot be used."
+    from PIL import Image
+    im = Image.open(src).convert('RGBA')
+    if im.width != im.height:
+        raise ValueError(f'{src} is {im.width}x{im.height}; an app icon has to be square')
+    if im.width < 512:
+        raise ValueError(f'{src} is {im.width}px; macOS draws icons at 1024 and will upscale this')
+    return im
+
+def _resized(im, size):
+    from PIL import Image
+    return im.resize((size, size), Image.LANCZOS)
+
+# %% ../nbs/05_icons.ipynb #c4c119cd
+def iconset(src, out):
+    "The `.iconset` folder `iconutil` turns into an `.icns`. Returns the folder."
+    im, out = _open(src), Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    for size, name in ICNS_SIZES: _resized(im, size).save(out/f'{name}.png')
+    return out
+
+def icns(src, out, keep_iconset=False):
+    "Build an `.icns` with macOS `iconutil`."
+    out = Path(out)
+    folder = out.with_suffix('.iconset')
+    iconset(src, folder)
+    try: subprocess.run(['iconutil', '-c', 'icns', str(folder), '-o', str(out)], check=True,
+                        capture_output=True)
+    except FileNotFoundError as e:
+        raise RuntimeError('an .icns is built by `iconutil`, which only macOS has') from e
+    finally:
+        if not keep_iconset:
+            for f in folder.glob('*.png'): f.unlink()
+            folder.rmdir()
+    return out
+
+# %% ../nbs/05_icons.ipynb #7babd804
+def ico(src, out, sizes=ICO_SIZES):
+    "A Windows `.ico` from one square image. Pillow writes every size into the one file."
+    im, out = _open(src), Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    im.save(out, format='ICO', sizes=[(s, s) for s in sizes])
+    return out
+
+# %% ../nbs/05_icons.ipynb #2e2ddd68
+def favicon(src, out, size=64):
+    "Write a PNG favicon for the web UI."
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    _resized(_open(src), size).save(out)
+    return out
+
+def icons_for(src, assets, name):
+    "Every icon asset a bundle wants, written under `assets`. Skips the ones this platform cannot make."
+    import sys
+    assets, out = Path(assets), {}
+    assets.mkdir(parents=True, exist_ok=True)
+    out['favicon'] = str(favicon(src, assets/'favicon.png'))
+    out['ico'] = str(ico(src, assets/f'{name}.ico'))
+    if sys.platform == 'darwin': out['icns'] = str(icns(src, assets/f'{name}.icns'))
+    return out

kavacha/menus.py

@@ -0,0 +1,44 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/06_menus.ipynb.
+
+# %% ../nbs/06_menus.ipynb #11fab8fe
+from __future__ import annotations
+from dataclasses import dataclass
+
+# %% auto #0
+__all__ = ['MenuItem', 'Std', 'Js', 'Binding']
+
+# %% ../nbs/06_menus.ipynb #1a54959d
+@dataclass(frozen=True)
+class MenuItem:
+    "One action in a menu. A blank action is a separator."
+    action: str = ''
+    kind: str = ''
+    def __post_init__(self):
+        if self.kind not in ('', 'warn'):
+            raise ValueError(f'{self.action or "separator"}: bad menu kind {self.kind!r}')
+
+# %% ../nbs/06_menus.ipynb #d30dc4ea
+@dataclass(frozen=True)
+class Std:
+    "A row AppKit implements itself. The selector goes to the responder chain, target nil."
+    title: str
+    selector: str
+    key: str = ''
+    mods: str = 'mod'
+
+# %% ../nbs/06_menus.ipynb #86983e95
+@dataclass(frozen=True)
+class Js:
+    "A row no action backs, named by the expression it runs."
+    title: str
+    expr: str
+
+# %% ../nbs/06_menus.ipynb #191bfb64
+@dataclass(frozen=True)
+class Binding:
+    "What a menu row reads from the host's keymap: the chords, the label, and where it applies."
+    keys: tuple = ()
+    label: str = ''
+    scope: str = 'global'
+    @property
+    def bound(self): return bool(self.keys)

kavacha/probe.py

@@ -0,0 +1,93 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_probe.ipynb.
+
+# %% ../nbs/00_probe.ipynb #3b4b84e6
+from __future__ import annotations
+import json, os, subprocess, sys, sysconfig, time
+from fastcore.all import Path, first
+
+# %% auto #0
+__all__ = ['BACKENDS', 'FRAMEWORK_CANDIDATES', 'backend', 'shell_ready', 'py_version', 'is_framework', 'framework_python',
+           'wait_for_http', 'running_from']
+
+# %% ../nbs/00_probe.ipynb #64edb644
+BACKENDS = {'darwin': 'cocoa', 'win32': 'edgechromium', 'linux': 'gtk'}
+
+FRAMEWORK_CANDIDATES = (
+    '/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13',
+    '/Library/Frameworks/Python.framework/Versions/3.14/bin/python3.14',
+    '/Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12',
+    '/opt/homebrew/opt/python@3.13/bin/python3.13',
+    '/opt/homebrew/opt/python@3.14/bin/python3.14',
+    '/opt/homebrew/opt/python@3.12/bin/python3.12',
+    '/usr/local/opt/python@3.13/bin/python3.13',
+    '/usr/local/opt/python@3.14/bin/python3.14',
+    '/usr/local/opt/python@3.12/bin/python3.12',
+    '/usr/bin/python3',
+)
+
+# %% ../nbs/00_probe.ipynb #ce90fe5b
+def backend(platform=None):
+    "pywebview's GUI name for `platform`, or None where there is no supported webview."
+    return BACKENDS.get(platform or sys.platform)
+
+def shell_ready(platform=None):
+    "`(ok, why)`: whether a native window can be opened here, and what is missing if not."
+    gui = backend(platform)
+    if gui is None: return False, f'no native webview backend for {platform or sys.platform}'
+    try: import webview  # noqa: F401
+    except ImportError as e: return False, f'pywebview is not installed ({e})'
+    return True, gui
+
+# %% ../nbs/00_probe.ipynb #0de4f037
+def py_version(python):
+    "The `(major, minor)` of `python`, or None when it will not say."
+    try: out = subprocess.run([str(python), '-c', 'import sys;print(*sys.version_info[:2])'],
+                              capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError): return None
+    try: return tuple(int(n) for n in out.stdout.split()) or None
+    except ValueError: return None
+
+def is_framework(python=None):
+    "Whether `python` (default: this interpreter) is a macOS framework build py2app can use."
+    if python is None: return bool(sysconfig.get_config_var('PYTHONFRAMEWORK'))
+    probe = ('import json,sysconfig,sys;'
+             "print(json.dumps([sysconfig.get_config_var('PYTHONFRAMEWORK') or '', "
+             'list(sys.version_info[:2])]))')
+    try: out = subprocess.run([str(python), '-c', probe], capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError): return False
+    if out.returncode: return False
+    try: name, version = json.loads(out.stdout.strip() or 'null')
+    except (ValueError, TypeError): return False
+    return bool(name) and tuple(version) >= (3, 12)
+
+def framework_python(candidates=FRAMEWORK_CANDIDATES):
+    "The first framework interpreter on this machine that py2app can build against."
+    return first(p for c in candidates if (p := Path(c)).exists() and is_framework(p))
+
+# %% ../nbs/00_probe.ipynb #8e6da7fd
+def wait_for_http(url, timeout=60, interval=.1):
+    "Block until `url` answers, or `timeout` passes. True if the server came up."
+    import urllib.request
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            urllib.request.urlopen(url, timeout=2)
+            return True
+        except Exception: time.sleep(interval)
+    return False
+
+# %% ../nbs/00_probe.ipynb #d18e585d
+def running_from(bundle, ps_output=None):
+    "PIDs of processes whose executable is inside `bundle`."
+    target = str(Path(bundle).resolve())
+    if ps_output is None:
+        try: ps_output = subprocess.run(['ps', '-Ao', 'pid,command'], capture_output=True,
+                                        text=True, timeout=10).stdout
+        except (OSError, subprocess.SubprocessError): return []
+    pids = []
+    for line in ps_output.splitlines()[1:]:
+        pid, _, command = line.strip().partition(' ')
+        exe = command.split(' ', 1)[0]
+        if exe.startswith(target + os.sep) and pid.isdigit() and int(pid) != os.getpid():
+            pids.append(int(pid))
+    return pids