zmk 0.1.0__py3-none-any.whl

zmk/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

zmk/backports.py

@@ -0,0 +1,10 @@
+"""
+Backports from Python > 3.10.
+"""
+
+try:
+    # pylint: disable=unused-import
+    from enum import StrEnum
+except ImportError:
+    # pylint: disable=unused-import
+    from backports.strenum import StrEnum

zmk/build.py

@@ -0,0 +1,174 @@
+"""
+Build matrix processing.
+"""
+
+import collections.abc
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+import dacite
+
+from .repo import Repo
+from .yaml import YAML
+
+
+@dataclass
+class BuildItem:
+    """An item in the build matrix"""
+
+    board: str
+    shield: Optional[str] = None
+    snippet: Optional[str] = None
+    cmake_args: Optional[str] = None
+    artifact_name: Optional[str] = None
+
+    def __rich__(self):
+        parts = []
+        parts.append(self.board)
+
+        if self.shield:
+            parts.append(self.shield)
+
+        if self.snippet:
+            parts.append(f"[dim]snippet: {self.snippet}[/dim]")
+
+        if self.artifact_name:
+            parts.append(f"[dim]artifact-name: {self.artifact_name}[/dim]")
+
+        if self.cmake_args:
+            parts.append(f"[dim]cmake-args: {self.cmake_args}[/dim]")
+
+        return "[dim], [/dim]".join(parts)
+
+
+@dataclass
+class _BuildMatrixWrapper:
+    include: list[BuildItem] = field(default_factory=list)
+
+
+class BuildMatrix:
+    """Interface to read and edit ZMK's build.yaml file"""
+
+    _path: Path
+    _yaml: YAML
+    _data: Any
+
+    @classmethod
+    def from_repo(cls, repo: Repo):
+        """Get the build matrix for a repo"""
+        return cls(repo.build_matrix_path)
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._yaml = YAML(typ="rt")
+        self._yaml.indent(mapping=2, sequence=4, offset=2)
+        try:
+            self._data = self._yaml.load(self._path)
+        except FileNotFoundError:
+            self._data = None
+
+    def write(self):
+        """Updated the YAML file, creating it if necessary"""
+        self._yaml.dump(self._data, self._path)
+
+    @property
+    def path(self):
+        """Path to the matrix's YAML file"""
+        return self._path
+
+    @property
+    def include(self) -> list[BuildItem]:
+        """List of build items in the matrix"""
+        normalized = _keys_to_python(self._data)
+        if not normalized:
+            return []
+
+        wrapper = dacite.from_dict(_BuildMatrixWrapper, normalized)
+        return wrapper.include
+
+    def has_item(self, item: BuildItem):
+        """Get whether the matrix has a build item"""
+        return item in self.include
+
+    def append(self, items: BuildItem | Iterable[BuildItem]) -> list[BuildItem]:
+        """
+        Add build items to the matrix.
+
+        :return: the items that were added.
+        """
+        items = [items] if isinstance(items, BuildItem) else items
+
+        include = self.include
+        items = [i for i in items if i not in include]
+
+        if not items:
+            return []
+
+        if not self._data:
+            self._data = self._yaml.map()
+
+        if "include" not in self._data:
+            self._data["include"] = self._yaml.seq()
+
+        self._data["include"].extend([_to_yaml(i) for i in items])
+        return items
+
+    def remove(self, items: BuildItem | Iterable[BuildItem]) -> list[BuildItem]:
+        """
+        Remove build items from the matrix.
+
+        :return: the items that were removed.
+        """
+        if not self._data or "include" not in self._data:
+            return False
+
+        removed = []
+        items = [items] if isinstance(items, BuildItem) else items
+
+        # TODO: there's probably a more efficient way to do this, but this is easy
+        for item in items:
+            try:
+                index = self.include.index(item)
+                del self._data["include"][index]
+                removed.append(item)
+            except ValueError:
+                pass
+
+        return removed
+
+
+def _keys_to_python(data: Any):
+    """
+    Fix any keys with hyphens to underscores so that dacite.from_dict() will
+    work correctly.
+    """
+
+    def fix_key(key: str):
+        return key.replace("-", "_")
+
+    match data:
+        case str():
+            return data
+
+        case collections.abc.Sequence():
+            return [_keys_to_python(i) for i in data]
+
+        case collections.abc.Mapping():
+            return {fix_key(k): _keys_to_python(v) for k, v in data.items()}
+
+        case _:
+            return data
+
+
+def _to_yaml(item: BuildItem):
+    """
+    Convert a BuildItem to a dict with keys changed back from underscores to hyphens.
+    """
+
+    def fix_key(key: str):
+        return key.replace("_", "-")
+
+    data = asdict(item)
+
+    return {fix_key(k): v for k, v in data.items() if v is not None}

zmk/commands/__init__.py

@@ -0,0 +1,28 @@
+"""
+ZMK CLI subcommands.
+"""
+
+import typer
+
+from . import cd, code, config, download, init, keyboard, module, west
+
+
+def register(app: typer.Typer):
+    """Register all commands with the app"""
+    app.command()(cd.cd)
+    app.command()(code.code)
+    app.command()(config.config)
+    app.command()(download.download)
+    app.command(name="dl")(download.download)
+    app.command()(init.init)
+    app.command()(west.update)
+    app.command(
+        add_help_option=False,
+        context_settings={
+            "allow_extra_args": True,
+            "ignore_unknown_options": True,
+        },
+    )(west.west)
+
+    app.add_typer(keyboard.app)
+    app.add_typer(module.app)

zmk/commands/cd.py

@@ -0,0 +1,56 @@
+"""
+"zmk cd" command.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import shellingham
+import typer
+
+from ..config import Config
+from ..exceptions import FatalError, FatalHomeMissing, FatalHomeNotSet
+
+
+def cd(ctx: typer.Context):
+    """Go to the ZMK config repo."""
+    if not sys.stdout.isatty():
+        raise FatalError(
+            "This command can only be used from an interactive shell. "
+            'Use "cd $(zmk config user.home)" instead.'
+        )
+
+    cfg = ctx.find_object(Config)
+    home = cfg.home_path
+
+    if home is None:
+        raise FatalHomeNotSet()
+
+    if not home.is_dir():
+        raise FatalHomeMissing(home)
+
+    if home == Path(os.getcwd()):
+        # Already in the home directory. Nothing to do.
+        return
+
+    os.chdir(home)
+
+    try:
+        _, shell = shellingham.detect_shell()
+    except shellingham.ShellDetectionFailure:
+        shell = _default_shell()
+
+    if os.name == "nt":
+        subprocess.run([shell], env=os.environ.copy(), check=False)
+    else:
+        os.execl(shell, shell)
+
+
+def _default_shell():
+    if os.name == "posix":
+        return os.environ["SHELL"]
+    if os.name == "nt":
+        return os.environ["COMSPEC"]
+    raise NotImplementedError(f"Don't know how to get a shell for OS {os.name!r}")

zmk/commands/code.py

@@ -0,0 +1,197 @@
+"""
+"zmk code" command.
+"""
+
+import platform
+import shlex
+import shutil
+import subprocess
+from configparser import NoOptionError
+from dataclasses import dataclass, field
+from enum import Flag, auto
+from typing import Annotated, Callable, Optional
+
+import rich
+import typer
+from rich.markdown import Markdown
+
+from ..config import Config, Settings
+from ..exceptions import FatalError
+from ..menu import show_menu
+from ..repo import Repo
+
+
+def code(
+    ctx: typer.Context,
+    keyboard: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Name of the keyboard to edit. If omitted, opens the repo directory.",
+        ),
+    ] = None,
+    open_conf: Annotated[
+        bool,
+        typer.Option("--conf", "-c", help="Open the .conf file instead of the keymap."),
+    ] = False,
+    open_build_matrix: Annotated[
+        bool,
+        typer.Option(
+            "--build", "-b", help="Open the build matrix instead of a keymap."
+        ),
+    ] = False,
+):
+    """Open the repo or a .keymap or .conf file in a text editor."""
+
+    cfg = ctx.find_object(Config)
+    repo = cfg.get_repo()
+
+    if open_build_matrix:
+        path = repo.build_matrix_path
+    else:
+        path = _get_file(repo, keyboard, open_conf)
+
+    editor = _get_editor(cfg, path.is_dir())
+
+    cmd = shlex.split(editor) + [path]
+    subprocess.call(cmd, shell=True)
+
+
+def _get_file(repo: Repo, keyboard: str, open_conf: bool):
+    if not keyboard:
+        return repo.path
+
+    ext = ".conf" if open_conf else ".keymap"
+    return repo.config_path / f"{keyboard}{ext}"
+
+
+def _get_editor(cfg: Config, is_directory: bool):
+    if is_directory:
+        try:
+            return cfg.get(Settings.CORE_EXPLORER)
+        except NoOptionError:
+            pass
+    try:
+        return cfg.get(Settings.CORE_EDITOR)
+    except NoOptionError:
+        pass
+
+    # No editor found. Prompt the user to select one and try again.
+    _select_editor(cfg)
+    return _get_editor(cfg, is_directory)
+
+
+class Support(Flag):
+    """Types of files an editor supports"""
+
+    FILE = auto()
+    DIR = auto()
+
+    ALL = FILE | DIR
+
+
+@dataclass
+class Editor:
+    """File editing tool"""
+
+    name: str
+    cmd: str
+    "Executable name or command line to execute this tool"
+    support: Support = Support.FILE
+    "Types of files this tool supports editing"
+    test: Callable[[], bool] = None
+    """
+    Function that returns true if the tool is installed.
+    Defaults to `which {self.cmd}`.
+    """
+    paths: list[str] = field(default_factory=list)
+    "Extra paths to search for the executable if `test` is not set"
+
+    def __rich__(self):
+        return self.name
+
+    def get_command(self):
+        """Get the command to execute the tool, or None if it is not installed"""
+        if self.test and self.test():
+            return self.cmd
+
+        if shutil.which(self.cmd):
+            return self.cmd
+
+        for path in self.paths:
+            if cmd := shutil.which(self.cmd, path=path):
+                return shlex.quote(cmd)
+
+        return None
+
+
+def _mac():
+    return platform.system() == "Darwin"
+
+
+_NPP_PATHS = ["C:\\Program Files\\Notepad++", "C:\\Program Files (x86)\\Notepad++"]
+_SUBL_PATHS = [
+    "C:\\Program Files\\sublime text 3",
+    "C:\\Program Files (x86)\\sublime text 3",
+]
+
+
+_EDITORS: list[Editor] = [
+    # Graphical text editors
+    Editor("Visual Studio Code", cmd="code", support=Support.ALL),
+    Editor("Sublime Text", cmd="subl", support=Support.ALL, paths=_SUBL_PATHS),
+    Editor("Emacs", cmd="emacs", support=Support.ALL),
+    Editor("Gedit", cmd="gedit"),
+    Editor("Notepad", cmd="notepad"),
+    Editor("Notepad++", cmd="notepad++", paths=_NPP_PATHS),
+    Editor("TextEdit", cmd="open -a TextEdit", test=_mac),
+    Editor("TextMate", cmd="mate", support=Support.ALL),
+    # Terminal text editors
+    Editor("Nano", cmd="nano"),
+    Editor("Neovim", cmd="nvim", support=Support.ALL),
+    Editor("Vim", cmd="vim", support=Support.ALL),
+    # File explorers
+    Editor("File Explorer", cmd="explorer", support=Support.DIR),
+    Editor("Nautilus", cmd="nautilus", support=Support.DIR),
+    Editor("Finder", cmd="open", support=Support.DIR, test=_mac),
+]
+
+
+def _select_editor(cfg: Config):
+    available = [e for e in _EDITORS if e.get_command()]
+    file_editors = [e for e in available if e.support & Support.FILE]
+    dir_editors = [e for e in available if e.support & Support.DIR]
+
+    if not file_editors:
+        raise FatalError(
+            "Could not find a known text editor.\n"
+            "Run \"zmk config core.editor='<command>'\" "
+            'replacing "<command>" with the path to a text editor.'
+        )
+
+    editor = show_menu("Select a text editor:", file_editors, filter_func=_filter)
+    cfg.set(Settings.CORE_EDITOR, editor.get_command())
+
+    explorer = None
+    if editor.support & Support.DIR:
+        cfg.remove(Settings.CORE_EXPLORER)
+    elif dir_editors:
+        explorer = show_menu(
+            "This text editor only supports opening files.\n"
+            "Select another tool for opening directories:",
+            dir_editors,
+            filter_func=_filter,
+        )
+        cfg.set(Settings.CORE_EXPLORER, explorer.get_command())
+
+    cfg.write()
+
+    rich.print("Editor saved:")
+    rich.print(Markdown(f'`zmk config core.editor="{editor.get_command()}"`'))
+    if explorer:
+        rich.print(Markdown(f'`zmk config core.explorer="{explorer.get_command()}"`'))
+
+    rich.print()
+
+
+def _filter(editor: Editor, text: str):
+    return text.casefold() in editor.name.casefold()

zmk/commands/config.py

@@ -0,0 +1,83 @@
+"""
+"zmk config" command.
+"""
+
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from .. import styles
+from ..config import Config
+
+console = Console(
+    highlighter=styles.KeyValueHighlighter(), theme=styles.KEY_VALUE_THEME
+)
+
+
+def _path_callback(ctx: typer.Context, value: bool):
+    if value:
+        cfg = ctx.find_object(Config)
+        print(cfg.path)
+        raise typer.Exit()
+
+
+def config(
+    ctx: typer.Context,
+    name: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Setting name. Prints all setting values if omitted.",
+        ),
+    ] = None,
+    value: Annotated[
+        Optional[str],
+        typer.Argument(help="New setting value. Prints the current value if omitted."),
+    ] = None,
+    unset: Annotated[
+        bool,
+        typer.Option("--unset", "-u", help="Remove the setting with the given name."),
+    ] = False,
+    _: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--path",
+            "-p",
+            help="Print the path to the ZMK CLI configuration file and exit.",
+            is_eager=True,
+            callback=_path_callback,
+        ),
+    ] = False,
+):
+    """Get and set ZMK CLI settings."""
+
+    cfg = ctx.find_object(Config)
+
+    if name is None:
+        _list_settings(cfg)
+    elif unset:
+        _unset_setting(cfg, name)
+    elif value:
+        _set_setting(cfg, name, value)
+    else:
+        _get_setting(cfg, name)
+
+
+def _list_settings(cfg: Config):
+    for name, value in sorted(cfg.items()):
+        console.print(f"{name}={value}")
+
+
+def _unset_setting(cfg: Config, name: str):
+    cfg.remove(name)
+    cfg.write()
+
+
+def _set_setting(cfg: Config, name: str, value: str):
+    cfg.set(name, value)
+    cfg.write()
+
+
+def _get_setting(cfg: Config, name: str):
+    if value := cfg.get(name, fallback=None):
+        console.print(value)

zmk/commands/download.py

@@ -0,0 +1,26 @@
+"""
+"zmk download" command.
+"""
+
+import typer
+
+from ..config import Config
+from ..repo import Repo
+
+
+def download(ctx: typer.Context):
+    """Open the web page to download firmware from GitHub."""
+
+    cfg = ctx.find_object(Config)
+    repo = cfg.get_repo()
+
+    actions_url = _get_actions_url(repo)
+
+    typer.launch(actions_url)
+
+
+def _get_actions_url(repo: Repo):
+    remote = repo.git("remote", capture_output=True).strip()
+    remote_url = repo.git("remote", "get-url", remote, capture_output=True).strip()
+
+    return f"{remote_url}/actions/workflows/build.yml"