lotus-shell 26.10.4__tar.gz

lotus_shell-26.10.4/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: lotus-shell
+Version: 26.10.4
+Summary: Add your description here
+Author: Stormzady
+Author-email: Stormzady <Stormzady@noreply.codeberg.org>
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+

lotus_shell-26.10.4/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "lotus-shell"
+version = "26.10.4"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = ["prompt-toolkit>=3.0.53"]
+
+[[project.authors]]
+name = "Stormzady"
+email = "Stormzady@noreply.codeberg.org"
+
+[project.scripts]
+lotus = "lotus:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

lotus_shell-26.10.4/pyproject.toml.orig

@@ -0,0 +1,19 @@
+[project]
+name = "lotus-shell"
+version = "26.10.4"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Stormzady", email = "Stormzady@noreply.codeberg.org" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "prompt-toolkit>=3.0.53",
+]
+
+[project.scripts]
+lotus = "lotus:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

lotus_shell-26.10.4/src/lotus_shell/__init__.py

@@ -0,0 +1,4 @@
+from .shell import Shell
+def main():
+    shell = Shell()
+    shell.go()

lotus_shell-26.10.4/src/lotus_shell/builtins.py

@@ -0,0 +1,158 @@
+import inspect as ins
+import os
+import subprocess
+import sys
+import shutil
+import ast
+
+from .config import Context
+from pathlib import Path
+
+
+def cd(args: list[str], ctx: Context) -> int:
+    place = args[0] if args else "~"
+    try:
+        os.chdir(os.path.expanduser(place))
+    except OSError as e:
+        print(f"cd: {place}: {e.strerror}")
+        return 127
+    path(args, ctx)
+    return 0
+
+def test() -> None:
+    while True:
+        continue
+
+def path(args, ctx: Context):
+    cwd = Path.cwd()
+    home = Path.home()
+    print(f"you're somewhere around: {cwd}")
+    if cwd == home:
+        print("and that is.. home, as far as i can tell.")
+    elif cwd.is_relative_to(home):
+        print(f"home is {len(cwd.relative_to(home).parts)} dirs away")
+    else:
+        print("and that is.. nowhere near home, as far as i can tell.")
+    return 0
+
+def help(args, ctx: Context):
+    print("help? you want help?\nhere's some help: type things in the box and i will make it do things for you")
+    return 0
+
+def editconfig(args, ctx: Context):
+    editor = os.environ.get("EDITOR", "nano")
+    config = os.path.expanduser("~/.config/lotus/config.py")
+    subprocess.run([editor, config], check=False)
+    return 0
+
+def command(args: list[str], ctx: Context):
+    try:
+        subprocess.run(args, check=False)
+        return 0
+    except IndexError:
+        return 1
+def exit(args, ctx: Context):
+    sys.exit(0)
+
+def listdir(args: list[str], ctx: Context):
+    path = Path(args[0]).expanduser() if args else Path.cwd()
+
+    raw = os.listdir(path)
+
+    print(f"Directory listing of: {path.resolve()}")
+    print("-------------")
+
+    for item in raw:
+        print(item)
+
+    print("-------------")
+
+    return 0
+
+def inspect(args: list[str], ctx: Context):
+    if len(args) < 1:
+        print("Please provide a command!")
+        return 2
+    print(f"Specified command name: {args[0]}")
+    for arg in args[1:]:
+        print(f"Argument: {arg}")
+    exec = shutil.which(args[0])
+    print(f"Does command exist: {exec or 'not found'}")
+    if args[0] in ctx.config.aliases:
+        print("Is alias: True")
+        print(f"Alias points to: {ctx.config.aliases.get(args[0])}")
+    else:
+        print("Is alias = False")
+    return 0
+
+def config(args: list[str], ctx: Context) -> int:
+    configuration = ctx.config
+
+    # config
+    if not args:
+        for name in dir(configuration):
+            if name.startswith("_"):
+                continue
+
+            value = getattr(configuration, name)
+
+            if not callable(value):
+                print(f"{name} = {value}")
+        return 0
+
+    name = args[0]
+    key = f"_{name}"
+
+    # config <name>
+    if not hasattr(configuration, key):
+        print(f"config: '{name}' doesn't exist")
+        return 127
+
+    if len(args) == 1:
+        print(f"{name} = {getattr(configuration, name)}")
+        return 0
+
+    # config <name> <value>
+    raw_value = " ".join(args[1:])
+
+    try:
+        value = ast.literal_eval(raw_value)
+    except (ValueError, SyntaxError):
+        if raw_value.startswith("[") and raw_value.endswith("]"):
+            value = [
+                item.strip().strip("\"'")
+                for item in raw_value[1:-1].split(",")
+            ]
+        else:
+            value = raw_value
+
+    setattr(configuration, key, value)
+
+    print(f"{name} = {getattr(configuration, name)}")
+    return 0
+
+def type(args: list[str], ctx: Context):
+    if not args:
+        print("type: expected a command")
+        return 2
+
+    name = args[0]
+
+    if name in ctx.config.aliases:
+        print(f"{name} is an alias for {ctx.config.aliases[name]}")
+    elif name in ctx.info.BUILTINS:
+        print(f"{name} is a lotus builtin")
+    elif shutil.which(name):
+        print(f"{name} is {shutil.which(name)}")
+    else:
+        print(f"{name}: not found")
+        return 127
+    return 0
+
+def _get():
+    return {
+        name: func
+        for name, func in globals().items()
+        if ins.isfunction(func)
+        and not name.startswith("_")
+    }

lotus_shell-26.10.4/src/lotus_shell/config.py

@@ -0,0 +1,103 @@
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Callable
+
+VERSION = "26.10.4"
+
+class Context:
+    def __init__(self, config, info):
+        self.config = config
+        self.info = info
+
+class Config:
+    def __init__(self):
+        self.config_path: Path = Path("~/.config/lotus").expanduser().resolve()
+        self.default_config = """
+# WARNING
+# The config does NOT check if a value is missing.
+# This means that if you are to remove a value, it will error out before the shell can load.
+# This is being patched.
+# Please keep all existing entries.
+
+
+# Create the config object
+lotus = Config()
+
+# Lotus version. Do not modify.
+lotus.version = "26.10.4"
+
+# Wanna know what's happening?
+lotus.verbose = False
+
+# Would you like the dynamic prompt?
+# True: Dynamic, False: Classic
+# Dynamic: -- Home -- 12:00 >
+# Classic user@hostname:directory >
+lotus.dynamic = True
+
+# What should we show for root and user as the indicator?
+# (root first, then user)
+lotus.indicator = ["#", "$"]
+
+# Can I show you an advert on startup?
+lotus.advert = True
+
+# What do you want Lotus to pretend you typed? (aliases, prefix builtins with b-)
+lotus.aliases = {
+    "la": "ls -la",
+    "ls": "b-listdir",
+    "dir": "b-listdir",
+}
+
+# This function runs on startup!
+def on_start():
+    pass
+"""
+        if not self.config_path.exists():
+            self.config_path.mkdir(parents=True)
+            self.defaults()
+
+    def defaults(self):
+        with open(self.config_path / "config.py", "w") as f:
+            f.write(self.default_config)
+
+    def load(self):
+        config_file = self.config_path / "config.py"
+
+        spec = importlib.util.spec_from_file_location(
+            "lotus.config",
+            config_file,
+        )
+
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not load config: {config_file}")
+
+        config_module = importlib.util.module_from_spec(spec)
+
+        config_module.Config = Config  # pyright: ignore[reportAttributeAccessIssue]
+
+        spec.loader.exec_module(config_module)
+
+        config = config_module.lotus.__dict__
+
+        on_start: Callable | None = getattr(config_module, "on_start", None)
+        if config.get("version") != VERSION:
+            print("your config is outdated. ")
+            res = input(f"do you want to update it to {VERSION}? [y/N] ")
+            if res.lower() == "n" or not res:
+                print(f"cannot load outdated config, loading default for version {VERSION}")
+                namespace = {
+                    "Config": Config,
+                }
+
+                exec(self.default_config, namespace)
+
+                config = namespace["lotus"].__dict__
+            else:
+                print(f"updating config to version {VERSION}")
+                self.defaults()
+                print("config updated.\nrestart the shell.")
+                sys.exit()
+
+        return config, on_start # pyright: ignore[reportAny]

lotus_shell-26.10.4/src/lotus_shell/init.py

@@ -0,0 +1,157 @@
+from typing import Callable
+from pathlib import Path
+
+from .config import Config, Context
+from .builtins import _get
+
+import os
+import socket
+import importlib
+import shutil
+import subprocess
+
+class CTX(Context):
+    def __init__(self, config, info):
+        super().__init__(config, info)
+
+class Configuration:
+    def __init__(self, config, on_start, config_path):
+        # lotus.indicator
+        if not config.get("indicator"):
+            config["indicator"] = ["#", "$"]
+        self._indicators: list[str] = config.get("indicator")
+        self._advert: bool = config.get("advert")
+        self._aliases: dict[str, str] = config.get("aliases")
+        self._verbose: bool = config.get("verbose")
+        self._dynamic: bool = config.get("dynamic")
+        self._on_start: Callable = on_start
+        self.config_path = config_path
+    @property
+    def indicators(self):
+        return self._indicators
+    @property
+    def advert(self):
+        return self._advert
+    @property
+    def aliases(self):
+        return self._aliases
+    @property
+    def verbose(self):
+        return self._verbose
+    @property
+    def dynamic_shell(self):
+        return self._dynamic
+
+
+
+
+class Information:
+    def __init__(self):
+        self.user: str | None = os.environ.get("USER") or os.environ.get("USERNAME")
+        self.host: str = socket.gethostname()
+        self.home = Path.home()
+        self.builtins: dict[str,Callable] = _get()
+    @property
+    def username(self):
+        return self.user
+    @property
+    def hostname(self):
+        return self.host
+    @property
+    def BUILTINS(self):
+        return self.builtins
+    @property
+    def cwd(self) -> str:
+        path = Path.cwd()
+
+        if path == self.home:
+            return "~"
+
+        try:
+            parts = list(path.relative_to(self.home).parts)
+        except ValueError:
+            parts = list(path.parts)
+
+        if not parts:
+            return "~"
+
+        width = shutil.get_terminal_size().columns
+        available = max(width // 3, 20)
+
+        if len("/".join(parts)) <= available:
+            return "/".join(parts)
+
+        # Shorten parent directories first.
+        for i in range(len(parts) - 1):
+            while len("/".join(parts)) > available and len(parts[i]) > 1:
+                parts[i] = parts[i][:-1]
+
+        # If we're still too long, progressively shorten deeper parents.
+        while len("/".join(parts)) > available:
+            changed = False
+
+            for i in range(len(parts) - 1):
+                if len(parts[i]) > 1:
+                    parts[i] = parts[i][:-1]
+                    changed = True
+
+                    if len("/".join(parts)) <= available:
+                        break
+
+            if not changed:
+                break
+
+        return "/".join(parts)
+    @property
+    def git(self) -> str | None:
+        result = subprocess.run(
+            ["git", "status", "--porcelain", "--branch"],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            return None
+
+        lines = result.stdout.splitlines()
+        branch = lines[0].removeprefix("## ").split("...")[0]
+
+        unstaged = 0
+        staged = 0
+
+        for line in lines[1:]:
+            if line[0] != " ":
+                staged += 1
+
+            if line[1] != " ":
+                unstaged += 1
+
+        def indicator(symbol: str, count: int) -> str:
+            if count == 0:
+                return ""
+
+            if count <= 4:
+                return symbol * count
+
+            return f"{symbol}×{count}"
+
+        status = (
+            indicator("!", unstaged)
+            + indicator("*", staged)
+        )
+
+        if "ahead" in lines[0]:
+            status += "^"
+
+        return f"{branch}{status}"
+
+
+def load_config():
+    unloaded = Config()
+    loaded, on_start = unloaded.load()
+
+    if on_start is not None and not callable(on_start):
+        raise TypeError("on_start isn't callable")
+
+    configuration = Configuration(loaded, on_start, unloaded.config_path)
+    return configuration

lotus_shell-26.10.4/src/lotus_shell/shell.py

@@ -0,0 +1,126 @@
+import os
+from pathlib import Path
+from prompt_toolkit import PromptSession
+from prompt_toolkit.history import FileHistory
+from datetime import datetime
+import subprocess
+import shlex
+import importlib
+import time
+
+from .init import Configuration, Information, CTX, load_config
+from .utils import open_invite
+from . import builtins
+
+
+class Shell:
+    def __init__(self):
+        status = self.status
+        print("shell [WAIT]")
+        self.config: Configuration = load_config()
+        status("config [OK]")
+        self.info: Information = Information()
+        status("info [OK]")
+        self.info.BUILTINS["reload"] = self.reload
+        status("reload inject [OK]")
+
+    def reload(self, args: list[str], ctx: CTX):
+        importlib.reload(builtins)
+        self.__init__()
+
+    def status(self, message: str):
+        if self.config.verbose:
+            print(message)
+            time.sleep(0.1)
+
+    def go(self):
+        status = self.status
+        # doing the ad
+        status("ad [WAIT]")
+        if self.config.advert:
+            print("wait, pause, you should probably join this cool amazing funny super duper best discord server!\nyou can turn this off by setting advert to false in your config!")
+            res = input("would you like to join the server? [y/N]: ")
+            if res.lower() == "n" or not res:
+                status("ad [FAIL]")
+            else:
+                open_invite("f9GsbvRadg")
+                status("ad [OK]")
+        else:
+            status("ad [FAIL]")
+        status("history [WAIT]" )
+        history = self.config.config_path / "history"
+        status("file init [OK]")
+        history.touch(exist_ok=True)
+        status("file creation [OK]")
+        session = PromptSession(
+            history=FileHistory(str(history)),
+        )
+        status("prompter'd'session creation [OK]")
+        status("history [OK]")
+        if self.config._on_start:
+            status("on_start [WAIT]")
+            self.config._on_start()
+            status("on_start [OK]")
+        print("do you wanna build a snowman..? (shell [OK])")
+        code = 0
+        while True:
+            try:
+                try:
+                    indicator = (
+                        self.config.indicators[0]
+                        if self.info.username == "root"
+                        else self.config.indicators[1]
+                    )
+
+                    if self.config.dynamic_shell:
+                        git = self.info.git
+                        time = datetime.now().strftime("%H:%M")
+                        if Path.cwd().resolve() == Path.home():
+                            prompt = f"-- Home -- {time} > "
+                        elif git:
+                            prompt = f"-- {Path.cwd().name} -- ({git}) -- {time} > "
+                        else:
+                            prompt = f"-- {Path.cwd().name} -- {time} > "
+                    else:
+                        prompt = f"{self.info.username}@{self.info.hostname}:{self.info.cwd} > "
+                    cmd = shlex.split(session.prompt(prompt))
+                except ValueError as e:
+                    print(f"what is this? ({e})")
+                    status("syntax error [ERROR]")
+                    continue
+
+                if not cmd:
+                    print("what do i do with NOTHING?")
+                    status("no text given [WARN]")
+                    continue
+
+                try:
+                    if cmd[0] in self.info.BUILTINS:
+                        code=self.info.BUILTINS[cmd[0]](cmd[1:], CTX(self.config, self.info))
+                        continue
+                    if cmd[0] in self.config.aliases:
+                        cmd = shlex.split(self.config.aliases[cmd[0]]) + cmd[1:]
+                        if cmd and cmd[0].startswith("b-"):
+                            name = cmd[0][2:]
+                            if name in self.info.BUILTINS:
+                                self.info.BUILTINS[name](cmd[1:], CTX(self.config, self.info))
+                            else:
+                                print(f"{name}: no such builtin")
+                            continue
+                except TypeError:
+                    print("fatal: a builtin didn't take it's arguments\nit's refusing to move to ram now..\ncan we get a crane for this guy?")
+                    status("builtin has no positional argument slot [FATAL]")
+                    continue
+                result=subprocess.run(cmd, check=False)
+                code = result.returncode
+            except FileNotFoundError:
+                print(f"{cmd[0]}: command not found\nshall i put the missing posters up?")
+                status("ErrorNo2/WinError2 [ERROR]")
+                continue
+            except EOFError:
+                status("shutdown [OK]")
+                print("\nokay, bye..")
+                break
+            except KeyboardInterrupt:
+                status("caught KeyboardInterrupt [WARN]")
+                print("\nlotus: the keyboard did WHAT now!?")

lotus_shell-26.10.4/src/lotus_shell/utils.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import socket
+import struct
+import subprocess
+import sys
+import webbrowser
+from dataclasses import dataclass, field
+from pathlib import Path
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from typing import Optional
+
+__all__ = ["open_invite", "parse_code", "InviteError", "InviteResult", "METHODS"]
+__version__ = "0.1.0"
+
+log = logging.getLogger("discord_invite")
+
+METHODS = ("ipc", "client", "opener", "web")
+
+CLIENT_BINS = ("vesktop", "equibop", "legcord", "webcord", "vencord",
+               "discord", "discord-ptb", "discord-canary", "Discord")
+FLATPAK_IDS = ("dev.vencord.Vesktop", "com.discordapp.Discord",
+               "app.legcord.Legcord", "io.github.equicord.equibop")
+
+
+class InviteError(RuntimeError):
+    """Raised when every requested method failed. `.attempted` lists them."""
+
+    def __init__(self, message: str, attempted: Sequence[str] = ()):
+        super().__init__(message)
+        self.attempted = tuple(attempted)
+
+
+@dataclass(frozen=True)
+class InviteResult:
+    method: str
+    code: str
+    url: str
+    attempted: tuple = field(default_factory=tuple)
+
+
+def parse_code(invite: str) -> str:
+    """Accept a full link (discord.gg/…, discord.com/invite/…) or a bare code."""
+    code = invite.strip().split("?")[0].split("#")[0].rstrip("/").rsplit("/", 1)[-1]
+    if not code or not all(c.isalnum() or c in "-_" for c in code):
+        raise ValueError(f"Can't parse invite: {invite!r}")
+    return code
+
+
+def _run(cmd: Sequence[str], timeout: float = 10) -> tuple[int, str]:
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return r.returncode, r.stdout.strip()
+    except (OSError, subprocess.SubprocessError) as e:
+        log.debug("run failed %s: %s", cmd, e)
+        return 1, ""
+
+
+def _spawn(cmd: Sequence[str]) -> bool:
+    """Launch detached: never blocks, survives the calling process."""
+    kwargs = {}
+    if sys.platform == "win32":
+        kwargs["creationflags"] = 0x00000008 | 0x00000200  # DETACHED | NEW_GROUP
+    else:
+        kwargs["start_new_session"] = True
+    try:
+        subprocess.Popen(list(cmd), stdin=subprocess.DEVNULL,
+                         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                         **kwargs)
+        log.debug("spawned %s", cmd)
+        return True
+    except OSError as e:
+        log.debug("spawn failed %s: %s", cmd, e)
+        return False
+
+def _ipc_sockets() -> Iterator[Path]:
+    if sys.platform == "win32":
+        return
+    base = (os.environ.get("XDG_RUNTIME_DIR") or os.environ.get("TMPDIR")
+            or f"/run/user/{os.getuid()}")
+    roots = [Path(base), Path(base, "app/com.discordapp.Discord"),
+             Path(base, "app/dev.vencord.Vesktop"), Path(base, "snap.discord")]
+    for root in roots:
+        for i in range(10):
+            p = root / f"discord-ipc-{i}"
+            if p.exists():
+                yield p
+
+
+def _frame(op: int, payload: dict) -> bytes:
+    data = json.dumps(payload).encode()
+    return struct.pack("<II", op, len(data)) + data
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = b""
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            break
+        buf += chunk
+    return buf
+
+
+def _read_frame(sock: socket.socket) -> tuple[Optional[int], dict]:
+    head = _recv_exact(sock, 8)
+    if len(head) < 8:
+        return None, {}
+    op, length = struct.unpack("<II", head)
+    body = _recv_exact(sock, length)
+    try:
+        return op, json.loads(body)
+    except ValueError:
+        return op, {}
+
+
+def _via_ipc(code: str, url: str) -> bool:
+    for path in _ipc_sockets():
+        log.debug("trying IPC socket %s", path)
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
+                s.settimeout(3)
+                s.connect(str(path))
+                s.sendall(_frame(0, {"v": 1, "client_id": "1234567890123456789"}))
+                op, msg = _read_frame(s)
+                if op != 1 or msg.get("evt") == "ERROR":
+                    log.debug("handshake rejected: %s %s", op, msg)
+                    continue
+                s.sendall(_frame(1, {"cmd": "INVITE_BROWSER",
+                                     "args": {"code": code},
+                                     "nonce": "invite-1"}))
+                op, msg = _read_frame(s)
+                if op == 1 and msg.get("evt") != "ERROR":
+                    return True
+                log.debug("invite rejected: %s %s", op, msg)
+        except (OSError, ValueError) as e:
+            log.debug("IPC error on %s: %s", path, e)
+    return False
+
+
+def _handler_binary() -> Optional[str]:
+    if not shutil.which("xdg-mime"):
+        return None
+    _, out = _run(["xdg-mime", "query", "default", "x-scheme-handler/discord"])
+    name = out[:-8] if out.endswith(".desktop") else out
+    return name or None
+
+
+def _via_client(code: str, url: str) -> bool:
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            for v in ("Discord", "DiscordPTB", "DiscordCanary"):
+                upd = Path(local, v, "Update.exe")
+                if upd.exists():
+                    exe = {"Discord": "Discord.exe", "DiscordPTB": "DiscordPTB.exe",
+                           "DiscordCanary": "DiscordCanary.exe"}[v]
+                    return _spawn([str(upd), "--processStart", exe, "--process-start-args", url])
+        return False
+    if sys.platform == "darwin":
+        for app in ("Vesktop", "Discord", "Discord PTB", "Discord Canary", "Legcord"):
+            if _run(["open", "-a", app, url])[0] == 0:
+                return True
+        return False
+
+    ordered: list[str] = []
+    h = _handler_binary()
+    if h:
+        ordered.append(h)
+    ordered += [b for b in CLIENT_BINS if b != h]
+    for b in ordered:
+        if shutil.which(b) and _spawn([b, url]):
+            return True
+    if shutil.which("flatpak"):
+        _, out = _run(["flatpak", "list", "--app", "--columns=application"])
+        installed = out.split()
+        for fid in FLATPAK_IDS:
+            if fid in installed and _spawn(["flatpak", "run", fid, url]):
+                return True
+    return False
+
+
+def _via_opener(code: str, url: str) -> bool:
+    if sys.platform == "win32":
+        try:
+            os.startfile(url)  # type: ignore[attr-defined]
+            return True
+        except OSError as e:
+            log.debug("startfile failed: %s", e)
+            return False
+    if sys.platform == "darwin":
+        return _run(["open", url])[0] == 0
+    # gio uses GLib's handler lookup and doesn't fall back to a browser the
+    # way xdg-open does.
+    for cmd in (["gio", "open", url], ["xdg-open", url]):
+        if shutil.which(cmd[0]) and _run(cmd)[0] == 0:
+            return True
+    return False
+
+
+def _via_web(code: str, url: str) -> bool:
+    web = f"https://discord.gg/{code}"
+    if sys.platform.startswith("linux") and shutil.which("xdg-open"):
+        return _run(["xdg-open", web])[0] == 0
+    return webbrowser.open(web)
+
+
+_IMPL: dict[str, Callable[[str, str], bool]] = {
+    "ipc": _via_ipc,
+    "client": _via_client,
+    "opener": _via_opener,
+    "web": _via_web,
+}
+
+
+def open_invite(invite: str, *,
+                methods: Optional[Iterable[str]] = None) -> InviteResult:
+    """Open `invite` in the desktop client.
+
+    Args:
+        invite: full invite URL or bare code.
+        methods: ordered subset of METHODS to try. Default is all of them,
+            most seamless first. Pass e.g. ("ipc", "client") to forbid the
+            browser fallback.
+
+    Raises:
+        ValueError: the invite couldn't be parsed.
+        InviteError: every requested method failed.
+    """
+    code = parse_code(invite)
+    url = f"discord://-/invite/{code}"
+    order = tuple(methods) if methods is not None else METHODS
+
+    unknown = [m for m in order if m not in _IMPL]
+    if unknown:
+        raise ValueError(f"Unknown method(s) {unknown}; choose from {METHODS}")
+
+    attempted: list[str] = []
+    for name in order:
+        attempted.append(name)
+        log.debug("trying method %s", name)
+        try:
+            ok = _IMPL[name](code, url)
+        except Exception:  # a broken method must never stop the fallthrough
+            log.debug("method %s raised", name, exc_info=True)
+            ok = False
+        if ok:
+            return InviteResult(name, code, url, tuple(attempted))
+    raise InviteError(f"No method worked (tried: {', '.join(attempted)})", attempted)