jupyterminal 0.0.1.dev0__py3-none-any.whl

jupyterminal/__init__.py

@@ -0,0 +1,13 @@
+"""jupyterminal: a terminal emulator whose session is a list of blocks.
+
+A block is one command plus everything it printed, kept as a unit that can
+be selected, copied and navigated to.
+
+* :mod:`jupyterminal.term` - terminal emulation (parser, screen model);
+* :mod:`jupyterminal.shell` - the pseudo-terminal and the zsh integration
+  that reports where commands start and end;
+* :mod:`jupyterminal.session` - blocks, and the router that fills them;
+* :mod:`jupyterminal.ui` - the Qt user interface.
+"""
+
+__version__ = '0.0.1-dev0'

jupyterminal/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m jupyterminal``."""
+
+import sys
+
+from .app import main
+
+sys.exit(main())

jupyterminal/app.py

@@ -0,0 +1,111 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import signal
+import sys
+
+from . import __version__
+from . import config as _config
+from . import desktop as _desktop
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="jupyterminal",
+        description="A terminal emulator whose session is a list of "
+                    "command blocks.")
+    parser.add_argument("--version", action="version",
+                        version=f"jupyterminal {__version__}")
+    parser.add_argument("--config", metavar="FILE",
+                        help="configuration file (default: "
+                             f"{_config.default_path()})")
+    parser.add_argument("--shell", metavar="PROGRAM",
+                        help="shell to run (default: zsh)")
+    parser.add_argument("--login", action="store_true",
+                        help="start the shell as a login shell")
+    parser.add_argument("-d", "--working-directory", metavar="DIR",
+                        help="directory to start in")
+    parser.add_argument("--print-default-config", action="store_true",
+                        help="print a configuration file with every "
+                             "default and exit")
+    parser.add_argument("--install-desktop-entry", action="store_true",
+                        help="put the program into the menus of the "
+                             "desktop, which also gives its windows their "
+                             "icon there, and exit")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.print_default_config:
+        sys.stdout.write(_config.DEFAULT_CONFIG)
+        return 0
+    if args.install_desktop_entry:
+        written = _desktop.install(_desktop.launcher())
+        print(f"jupyterminal: wrote {written}; delete that file to take "
+              "the program out of the menus again")
+        return 0
+
+    path = args.config or _config.default_path()
+    config = _config.load(path)
+    for warning in config.warnings:
+        print(f"jupyterminal: {warning}", file=sys.stderr)
+
+    # Imported late so that --help and --version need no display.
+    from PySide6.QtCore import QMetaObject, QStandardPaths, Qt
+    from PySide6.QtGui import QIcon
+    from PySide6.QtWidgets import QApplication
+
+    from .session import Session
+    from .shell import find_shell, is_zsh
+    from .ui import MainWindow
+
+    app = QApplication.instance() or QApplication(sys.argv[:1])
+    # Being told to stop is a normal way to end: hang up the shell and
+    # remove the session's private directory.  Python only notices a
+    # signal when it gets to run; the view's timer, which looks after the
+    # shell several times a second, sees to that.  The request is queued,
+    # because one that comes before the event loop has started would
+    # otherwise be forgotten.
+    for number in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        signal.signal(number, lambda *_: QMetaObject.invokeMethod(
+            app, "quit", Qt.ConnectionType.QueuedConnection))
+    app.setApplicationName("jupyterminal")
+    app.setWindowIcon(QIcon(_desktop.icon_path()))
+    # The window belongs to the desktop entry of that name when one is
+    # installed.  Naming an entry that does not exist only earns a
+    # complaint from the desktop ("App info not found") at every start.
+    if QStandardPaths.locate(
+            QStandardPaths.StandardLocation.ApplicationsLocation,
+            "jupyterminal.desktop"):
+        app.setDesktopFileName("jupyterminal")
+
+    shell = find_shell(args.shell or config.shell)
+    if shutil.which(shell) is None:
+        print(f"jupyterminal: cannot run {shell}: no such program",
+              file=sys.stderr)
+        return 127
+    if not is_zsh(shell):
+        print(f"jupyterminal: {shell} is not zsh; without its integration "
+              "the whole session is one block.", file=sys.stderr)
+    cwd = args.working_directory
+    if cwd and not os.path.isdir(cwd):
+        # Said, and no more: a shell that cannot enter its directory
+        # starts where this program was started.
+        print(f"jupyterminal: {cwd}: not a directory", file=sys.stderr)
+
+    session = Session(100, 30, max_lines=config.scrollback_lines,
+                      divert=config.divert_background_output)
+    window = MainWindow(session, config)
+    for warning in window.view.theme.warnings:
+        print(f"jupyterminal: {path}: {warning}", file=sys.stderr)
+    session.start(shell, cwd=cwd, login=args.login or config.login_shell)
+    window.view.attach_io()
+    window.show()
+    status = app.exec()
+    session.close()
+    return status

jupyterminal/config.py

@@ -0,0 +1,253 @@
+"""User configuration.
+
+Read from ``$XDG_CONFIG_HOME/jupyterminal/config.toml`` (normally
+``~/.config/jupyterminal/config.toml``).  Every key is optional; see
+:data:`DEFAULT_CONFIG` for the full file with its defaults.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+
+#: action -> default shortcuts.  The first group works everywhere, the
+#: ``blocks.*`` group only while a block is selected.
+DEFAULT_KEYS: dict[str, list[str]] = {
+    "copy": ["Ctrl+Shift+C"],
+    "copy_command_and_output": ["Ctrl+Alt+Shift+C"],
+    "paste": ["Ctrl+Shift+V"],
+    "paste_selection": ["Shift+Ins"],
+    "select_newest_block": ["Ctrl+Up"],
+    "clear_blocks": ["Ctrl+Shift+K"],
+    "find_in_block": ["Ctrl+Shift+F"],
+    "filter_output": ["Ctrl+Shift+L"],
+    "scroll_page_up": ["Shift+PgUp"],
+    "scroll_page_down": ["Shift+PgDown"],
+    "scroll_to_top": ["Shift+Home"],
+    "scroll_to_bottom": ["Shift+End"],
+    "zoom_in": ["Ctrl+=", "Ctrl++"],
+    "zoom_out": ["Ctrl+-"],
+    "zoom_reset": ["Ctrl+0"],
+    "blocks.previous": ["Up"],
+    "blocks.next": ["Down"],
+    "blocks.extend_previous": ["Shift+Up"],
+    "blocks.extend_next": ["Shift+Down"],
+    "blocks.scroll_to_top": ["Ctrl+Shift+Up"],
+    "blocks.scroll_to_bottom": ["Ctrl+Shift+Down"],
+    "blocks.first": ["Home"],
+    "blocks.last": ["End"],
+    "blocks.page_up": ["PgUp"],
+    "blocks.page_down": ["PgDown"],
+    "blocks.focus_input": ["Esc"],
+    "blocks.menu": ["Menu"],
+    "blocks.toggle_collapse": [],
+}
+
+#: The ways a command can be typed; the first is the default.
+INPUTS = ("editor", "shell")
+
+DEFAULT_CONFIG = '''\
+# jupyterminal configuration.  Every key is optional.
+
+[font]
+family = ""          # empty: the system's fixed-width font
+size = 11.0
+
+[shell]
+program = ""         # empty: $SHELL if it is zsh, otherwise zsh from PATH
+login = false        # start it as a login shell
+
+[terminal]
+# History cap, in output lines.  The oldest blocks are dropped whole.
+scrollback_lines = 2000000
+# Output that arrives while the prompt is idle goes into a background
+# block instead of landing on the prompt.
+divert_background_output = true
+confirm_multiline_paste = true
+# How a command is typed.  "editor": in a text box that edits like every
+# other one on the desktop: the mouse places the cursor, Shift and the
+# arrows select, Ctrl+C, Ctrl+X and Ctrl+V are the clipboard, Ctrl+Z takes
+# back.  "shell": in the shell's own line editor, as in other terminals.
+input = "editor"
+# Characters besides letters and digits that a double-click treats as
+# part of a word.
+word_characters = "-_./~:@%+#=?&"
+bell = "none"        # "none" or "visual"
+# Let programs set the clipboard (OSC 52).
+allow_clipboard_write = true
+
+[keys]
+# action = "Shortcut" or ["Shortcut", "Another"].  An empty list unbinds.
+copy = "Ctrl+Shift+C"
+copy_command_and_output = "Ctrl+Alt+Shift+C"
+paste = "Ctrl+Shift+V"
+paste_selection = "Shift+Ins"
+select_newest_block = "Ctrl+Up"
+clear_blocks = "Ctrl+Shift+K"
+find_in_block = "Ctrl+Shift+F"
+filter_output = "Ctrl+Shift+L"
+scroll_page_up = "Shift+PgUp"
+scroll_page_down = "Shift+PgDown"
+scroll_to_top = "Shift+Home"
+scroll_to_bottom = "Shift+End"
+zoom_in = ["Ctrl+=", "Ctrl++"]
+zoom_out = "Ctrl+-"
+zoom_reset = "Ctrl+0"
+
+[keys.blocks]
+# These apply while a block is selected.
+previous = "Up"
+next = "Down"
+extend_previous = "Shift+Up"
+extend_next = "Shift+Down"
+scroll_to_top = "Ctrl+Shift+Up"
+scroll_to_bottom = "Ctrl+Shift+Down"
+first = "Home"
+last = "End"
+page_up = "PgUp"
+page_down = "PgDown"
+focus_input = "Esc"
+menu = "Menu"
+toggle_collapse = []    # unbound: any printable key returns to the input
+
+[colors]
+# Any color of the theme, as "#rrggbb" or by name.  The defaults:
+# background = "#1a1c22"
+# foreground = "#d5d8df"
+# dim = "#7d8594"
+# header_background = "#22252d"
+# header_foreground = "#eef0f4"
+# divider = "#525a6e"
+# selected_background = "#1c2738"
+# selected_header = "#25344f"
+# selected_bar = "#4d8eff"
+# failed_background = "#271b1e"
+# failed_header = "#382024"
+# failed_bar = "#e5534b"
+# failed_foreground = "#ff7b72"
+# accent = "#58a6ff"
+# input_background = "#14161b"
+# input_border = "#333845"
+# cursor = "#d5d8df"
+# cursor_text = "#1a1c22"
+# selection = "#34507f"
+# find = "#6a5a19"
+# find_current = "#d4a72c"
+# find_current_text = "#1a1c22"
+# chip_background = "#2d323d"
+# chip_foreground = "#aab1bf"
+# scrollbar = "#3a404d"
+# The sixteen colors programs choose by number: black, red, green,
+# yellow, blue, magenta, cyan and white, then the bright one of each.
+# ansi = ["#2b303b", "#e06c75", "#98c379", "#e5c07b",
+#         "#61afef", "#c678dd", "#56b6c2", "#c8ccd4",
+#         "#5c6370", "#ff7b86", "#b1e18b", "#f2d08a",
+#         "#7cc0ff", "#d7a1f0", "#74d2de", "#ffffff"]
+'''
+
+
+@dataclass
+class Config:
+    font_family: str = ""
+    font_size: float = 11.0
+    shell: str = ""
+    login_shell: bool = False
+    scrollback_lines: int = 2_000_000
+    divert_background_output: bool = True
+    confirm_multiline_paste: bool = True
+    input: str = "editor"
+    word_characters: str = "-_./~:@%+#=?&"
+    bell: str = "none"
+    allow_clipboard_write: bool = True
+    keys: dict[str, list[str]] = field(
+        default_factory=lambda: {k: list(v) for k, v in DEFAULT_KEYS.items()})
+    colors: dict = field(default_factory=dict)
+    #: Problems found while reading the file, for the user to see.
+    warnings: list[str] = field(default_factory=list)
+
+
+def default_path() -> str:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return os.path.join(base, "jupyterminal", "config.toml")
+
+
+def _shortcuts(value) -> list[str] | None:
+    if isinstance(value, str):
+        return [value] if value else []
+    if isinstance(value, list) and all(isinstance(v, str) for v in value):
+        return [v for v in value if v]
+    return None
+
+
+def load(path: str | None = None) -> Config:
+    """Read the configuration; a missing file gives the defaults."""
+    config = Config()
+    path = path or default_path()
+    try:
+        with open(path, "rb") as handle:
+            data = tomllib.load(handle)
+    except FileNotFoundError:
+        return config
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        config.warnings.append(f"{path}: {error}")
+        return config
+
+    def take(section: str, key: str, attr: str, kind) -> None:
+        table = data.get(section)
+        if not isinstance(table, dict) or key not in table:
+            return
+        value = table[key]
+        if kind is float and isinstance(value, int) \
+                and not isinstance(value, bool):
+            value = float(value)
+        if isinstance(value, kind) and not (kind is int
+                                            and isinstance(value, bool)):
+            setattr(config, attr, value)
+        else:
+            config.warnings.append(
+                f"{path}: [{section}] {key} should be {kind.__name__}")
+
+    take("font", "family", "font_family", str)
+    take("font", "size", "font_size", float)
+    take("shell", "program", "shell", str)
+    take("shell", "login", "login_shell", bool)
+    take("terminal", "scrollback_lines", "scrollback_lines", int)
+    take("terminal", "divert_background_output",
+         "divert_background_output", bool)
+    take("terminal", "confirm_multiline_paste",
+         "confirm_multiline_paste", bool)
+    take("terminal", "input", "input", str)
+    if config.input not in INPUTS:
+        config.warnings.append(
+            f"{path}: [terminal] input should be one of "
+            + ", ".join(repr(name) for name in INPUTS)
+            + f", not {config.input!r}")
+        config.input = INPUTS[0]
+    take("terminal", "word_characters", "word_characters", str)
+    take("terminal", "bell", "bell", str)
+    take("terminal", "allow_clipboard_write", "allow_clipboard_write", bool)
+
+    keys = data.get("keys")
+    if isinstance(keys, dict):
+        for name, value in keys.items():
+            if name == "blocks" and isinstance(value, dict):
+                for sub, sub_value in value.items():
+                    _bind(config, path, f"blocks.{sub}", sub_value)
+            else:
+                _bind(config, path, name, value)
+    colors = data.get("colors")
+    if isinstance(colors, dict):
+        config.colors = colors
+    return config
+
+
+def _bind(config: Config, path: str, action: str, value) -> None:
+    shortcuts = _shortcuts(value)
+    if action not in DEFAULT_KEYS:
+        config.warnings.append(f"{path}: unknown action {action!r}")
+    elif shortcuts is None:
+        config.warnings.append(
+            f"{path}: {action} should be a shortcut or a list of them")
+    else:
+        config.keys[action] = shortcuts

jupyterminal/desktop.py

@@ -0,0 +1,84 @@
+"""A place on the desktop: the icon, and the entry that puts the program
+into the desktop's menus.
+
+A desktop knows an application by an entry, a file named after it.  A
+window that says which entry it belongs to gets that entry's icon in the
+task bar and in the window switcher; on Wayland that is the only way to
+an icon of its own.  :func:`install` writes the entry for the user who
+runs it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib import resources
+
+#: What the desktop knows the program by: its entry is ``NAME.desktop``.
+NAME = "jupyterminal"
+
+#: Characters that an argument of a command may only hold in quotes.
+_RESERVED = frozenset(" \t\n\"'\\><~|&;$*?#()`")
+#: Those that take a backslash in front even between quotes.
+_ESCAPED = frozenset("\"`$\\")
+
+
+def icon_path() -> str:
+    """The file that holds the icon."""
+    return str(resources.files("jupyterminal.ui") / (NAME + ".svg"))
+
+
+def launcher() -> list[str]:
+    """The command that starts the program the way it was started this
+    time: as a module, or by a script such as the installed command or
+    the ``main.py`` of a checkout."""
+    spec = getattr(sys.modules.get("__main__"), "__spec__", None)
+    if spec is not None and spec.name == NAME + ".__main__":
+        return [sys.executable, "-m", NAME]
+    return [sys.executable, os.path.abspath(sys.argv[0])]
+
+
+def _word(word: str) -> str:
+    """One argument the way the ``Exec`` line of an entry writes it."""
+    word = word.replace("%", "%%")          # a single one starts a field code
+    if word and not _RESERVED.intersection(word):
+        return word
+    quoted = "".join("\\" + ch if ch in _ESCAPED else ch for ch in word)
+    # The line is a string to the desktop before it is a command: every
+    # backslash is written twice.
+    return '"' + quoted.replace("\\", "\\\\") + '"'
+
+
+def entry(command: list[str]) -> str:
+    """The text of the entry that starts the program with ``command``."""
+    return "\n".join((
+        "[Desktop Entry]",
+        "Type=Application",
+        "Name=" + NAME,
+        "GenericName=Terminal",
+        "Comment=A terminal in which typing and copying work as everywhere"
+        " else",
+        "Exec=" + " ".join(_word(word) for word in command),
+        "Icon=" + icon_path().replace("\\", "\\\\"),
+        "Terminal=false",
+        "Categories=System;TerminalEmulator;",
+        # Windows on X11 are matched to the entry by this.
+        "StartupWMClass=" + NAME,
+        ""))
+
+
+def entry_path() -> str:
+    """Where the entry of the user who runs this goes."""
+    base = os.environ.get("XDG_DATA_HOME") \
+        or os.path.expanduser("~/.local/share")
+    return os.path.join(base, "applications", NAME + ".desktop")
+
+
+def install(command: list[str]) -> str:
+    """Write the entry that starts the program with ``command`` and
+    return its path.  An entry that is there already is replaced."""
+    path = entry_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(entry(command))
+    return path

jupyterminal/session/__init__.py

@@ -0,0 +1,13 @@
+"""The session model: blocks, the router that fills them, and the text
+that copying takes out of them."""
+
+from .block import BACKGROUND, COMMAND, Block, git_branch
+from .session import CLOSED, PROMPT, RUNNING, STARTUP, Session
+from .text import (BOTH, FilterSpec, block_text, copy_text, filter_indices,
+                   find_matches, output_text)
+
+__all__ = [
+    "BACKGROUND", "BOTH", "Block", "CLOSED", "COMMAND", "FilterSpec",
+    "PROMPT", "RUNNING", "STARTUP", "Session", "block_text", "copy_text",
+    "filter_indices", "find_matches", "git_branch", "output_text",
+]

jupyterminal/session/block.py

@@ -0,0 +1,150 @@
+"""The block: one command and everything it printed."""
+
+from __future__ import annotations
+
+import os
+import time
+
+from ..term import LineStore, Screen
+
+COMMAND = "command"
+BACKGROUND = "background"
+
+RUNNING = "running"
+FINISHED = "finished"
+
+
+class Block:
+    """One entry of the session.
+
+    While the command runs, ``screen`` is the live terminal screen it draws
+    on and ``store`` receives the lines that scroll off it.  When the
+    command finishes the screen is frozen into the store and dropped; from
+    then on the block is just its logical lines.
+    """
+
+    __slots__ = ("id", "kind", "command", "cwd", "branch", "label",
+                 "started", "_t0", "duration", "exit_code", "state",
+                 "not_run", "fullscreen", "cleared", "store", "screen",
+                 "collapsed", "filter", "visible", "find", "view")
+
+    def __init__(self, kind: str, cols: int, rows: int, command: str = "",
+                 cwd: str = "", branch: str = "") -> None:
+        self.id = 0
+        self.kind = kind
+        #: The exact text the user submitted ("" for background output).
+        self.command = command
+        self.cwd = cwd
+        self.branch = branch
+        self.label = "background output" if kind == BACKGROUND else ""
+        self.started = time.time()
+        self._t0 = time.monotonic()
+        self.duration: float | None = None
+        self.exit_code: int | None = None
+        self.state = RUNNING
+        #: The shell turned the text down before running anything.
+        self.not_run = False
+        #: A full-screen program ran in this block.
+        self.fullscreen = False
+        self.cleared = False
+        self.store = LineStore()
+        self.screen: Screen | None = Screen(cols, rows, self.store)
+        # View state, owned by the user interface.
+        self.collapsed = False
+        self.filter = None
+        self.visible: list[int] | None = None
+        self.find = None
+        self.view = None
+
+    @property
+    def running(self) -> bool:
+        return self.state == RUNNING
+
+    @property
+    def failed(self) -> bool:
+        return self.state == FINISHED and self.exit_code not in (None, 0)
+
+    @property
+    def is_command(self) -> bool:
+        return self.kind == COMMAND
+
+    def elapsed(self) -> float:
+        if self.duration is not None:
+            return self.duration
+        return time.monotonic() - self._t0
+
+    def finish(self, exit_code: int | None) -> None:
+        """The command is over: freeze its output."""
+        if self.state == FINISHED:
+            return
+        self.duration = time.monotonic() - self._t0
+        self.exit_code = exit_code
+        self.state = FINISHED
+        # A running block always has its screen: this is the one place
+        # that takes it away.
+        self.screen.finish()
+        self.screen = None
+
+    def has_output(self) -> bool:
+        store = self.store
+        if store.texts or store.open_parts is not None:
+            return True
+        screen = self.screen
+        if screen is not None:
+            for row in screen.grid:
+                if not row.is_blank():
+                    return True
+        return False
+
+    def lines(self) -> list[str]:
+        """Every logical line of output so far."""
+        screen = self.screen
+        if screen is None:
+            return self.store.texts
+        return [text for text, _ in screen.all_lines()]
+
+    def line_count(self) -> int:
+        """``len(self.lines())``, at no more than the cost of what is on
+        the screen."""
+        screen = self.screen
+        if screen is None:
+            return len(self.store.texts)
+        return screen.line_count()
+
+
+def git_branch(path: str) -> str:
+    """The checked-out branch of the repository containing ``path``.
+
+    Read straight from the repository files; returns "" outside one.
+    """
+    if not path:
+        return ""
+    try:
+        current = os.path.abspath(path)
+        while True:
+            dot_git = os.path.join(current, ".git")
+            if os.path.isdir(dot_git):
+                git_dir = dot_git
+                break
+            if os.path.isfile(dot_git):
+                with open(dot_git, encoding="utf-8",
+                          errors="replace") as handle:
+                    pointer = handle.read().strip()
+                if not pointer.startswith("gitdir:"):
+                    return ""
+                git_dir = os.path.join(current, pointer[7:].strip())
+                break
+            parent = os.path.dirname(current)
+            if parent == current:
+                return ""
+            current = parent
+        with open(os.path.join(git_dir, "HEAD"), encoding="utf-8",
+                  errors="replace") as handle:
+            head = handle.read().strip()
+    except OSError:
+        return ""
+    if head.startswith("ref:"):
+        ref = head[4:].strip()
+        prefix = "refs/heads/"
+        return ref[len(prefix):] if ref.startswith(prefix) else ref
+    return head[:7]