osc7501 1.0.0__py3-none-any.whl

osc7501/__init__.py

@@ -0,0 +1,35 @@
+"""Report terminal program status with OSC 7501."""
+
+from osc7501.encode import Kind, State, encode
+from osc7501.terminal import (
+    Detection,
+    Job,
+    Support,
+    blocked,
+    clear,
+    detect,
+    done,
+    error,
+    idle,
+    parse_reply,
+    query,
+    working,
+)
+
+__all__ = [
+    "Detection",
+    "Job",
+    "Kind",
+    "State",
+    "Support",
+    "blocked",
+    "clear",
+    "detect",
+    "done",
+    "encode",
+    "error",
+    "idle",
+    "parse_reply",
+    "query",
+    "working",
+]

osc7501/encode.py

@@ -0,0 +1,118 @@
+"""Build one OSC 7501 report. This module does not write to a terminal."""
+
+import base64
+import re
+import unicodedata
+from enum import StrEnum
+
+_APP = re.compile(r"[A-Za-z0-9_.+-]{1,32}")
+_ID_BYTES = 128
+_ID_SEGMENTS = 8
+_MSG_BYTES = 2048
+_TITLE_BYTES = 192
+_SEQUENCE_BYTES = 4096
+
+
+class State(StrEnum):
+    IDLE = "idle"
+    WORKING = "working"
+    DONE = "done"
+    BLOCKED = "blocked"
+    ERROR = "error"
+    CLEAR = "clear"
+
+
+class Kind(StrEnum):
+    PERMISSION = "permission"
+    QUESTION = "question"
+    AUTH = "auth"
+
+
+def encode(
+    state: str,
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    kind: str | None = None,
+    progress: int | None = None,
+) -> str:
+    """Return one report. The terminator is ST.
+
+    ``re.fullmatch`` is required for ``app`` and each ``id`` segment.
+    ``re.match`` with ``$`` also matches before a trailing newline.
+
+    Control characters in ``msg`` and ``title`` are replaced with a space.
+    A terminal discards the whole report when those fields decode to a control.
+    """
+    try:
+        parsed = State(state)
+    except ValueError:
+        raise ValueError(f"unknown state: {state!r}") from None
+
+    if parsed is State.CLEAR and any(
+        value is not None for value in (msg, title, app, kind, progress)
+    ):
+        raise ValueError("clear accepts only id")
+
+    parsed_kind: Kind | None = None
+    if kind is not None:
+        if parsed is not State.BLOCKED:
+            raise ValueError("kind is only valid with blocked")
+        try:
+            parsed_kind = Kind(kind)
+        except ValueError:
+            raise ValueError(f"unknown kind: {kind!r}") from None
+
+    if progress is not None:
+        if parsed not in (State.WORKING, State.BLOCKED):
+            raise ValueError("progress is only valid with working or blocked")
+        # bool is a subclass of int. True would otherwise encode as progress=1.
+        if isinstance(progress, bool) or not isinstance(progress, int) or not 0 <= progress <= 100:
+            raise ValueError(f"invalid progress: {progress!r}")
+
+    if app is not None and _APP.fullmatch(app) is None:
+        raise ValueError(f"invalid app: {app!r}")
+    if id is not None:
+        _check_id(id)
+
+    pairs = [f"state={parsed.value}"]
+    if id is not None:
+        pairs.append(f"id={id}")
+    if parsed_kind is not None:
+        pairs.append(f"kind={parsed_kind.value}")
+    if progress is not None:
+        pairs.append(f"progress={progress}")
+    if app is not None:
+        pairs.append(f"app={app}")
+    if title is not None and (encoded := _text(title, _TITLE_BYTES)) is not None:
+        pairs.append(f"title={encoded}")
+    if msg is not None and (encoded := _text(msg, _MSG_BYTES)) is not None:
+        pairs.append(f"msg={encoded}")
+
+    sequence = f"\x1b]7501;{':'.join(pairs)}\x1b\\"
+    if len(sequence.encode("ascii")) > _SEQUENCE_BYTES:
+        raise ValueError("sequence longer than 4096 bytes")
+    return sequence
+
+
+def _check_id(record_id: str) -> None:
+    if len(record_id.encode("utf-8")) > _ID_BYTES:
+        raise ValueError("id longer than 128 bytes")
+    segments = record_id.split("/")
+    if len(segments) > _ID_SEGMENTS:
+        raise ValueError("id has more than 8 segments")
+    for segment in segments:
+        if _APP.fullmatch(segment) is None:
+            raise ValueError(f"invalid id segment: {segment!r}")
+
+
+def _text(text: str, limit: int) -> str | None:
+    cleaned = "".join(" " if unicodedata.category(char) == "Cc" else char for char in text)
+    raw = cleaned.encode("utf-8", errors="replace")
+    if len(raw) > limit:
+        raw = raw[:limit].decode("utf-8", errors="ignore").encode("utf-8")
+    if not raw:
+        return None
+    return base64.b64encode(raw).decode("ascii")

osc7501/terminal.py

@@ -0,0 +1,467 @@
+"""Write an OSC 7501 report to a terminal, and read a support reply."""
+
+import os
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import IO, Any
+
+from osc7501.encode import Kind, State, encode
+
+_ESC = 0x1B
+_BEL = 0x07
+_CAN = 0x18
+_SUB = 0x1A
+_GROUND = "ground"
+_ESCAPE = "esc"
+_OSC = "osc"
+_OSC_ESC = "osc-esc"
+_CSI = "csi"
+_REPLY_PREFIX = b"7501;?"
+_BODY_LIMIT = 4096
+
+_lock = threading.Lock()
+
+
+def idle(
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    return _send(State.IDLE, msg=msg, title=title, app=app, id=id, stream=stream, enabled=enabled)
+
+
+def done(
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    return _send(State.DONE, msg=msg, title=title, app=app, id=id, stream=stream, enabled=enabled)
+
+
+def error(
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    return _send(State.ERROR, msg=msg, title=title, app=app, id=id, stream=stream, enabled=enabled)
+
+
+def blocked(
+    *,
+    kind: str | None = None,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    progress: int | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    return _send(
+        State.BLOCKED,
+        kind=kind,
+        msg=msg,
+        title=title,
+        app=app,
+        id=id,
+        progress=progress,
+        stream=stream,
+        enabled=enabled,
+    )
+
+
+def working(
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    progress: int | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> "Job":
+    """Write ``working`` immediately and return a handle for later reports."""
+    job = Job(
+        app=app,
+        id=id,
+        title=title,
+        stream=sys.stderr if stream is None else stream,
+        enabled=enabled,
+    )
+    job.update(msg=msg, progress=progress)
+    return job
+
+
+def clear(
+    *,
+    id: str | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    return _send(State.CLEAR, id=id, stream=stream, enabled=enabled)
+
+
+class Job:
+    """One task. Repeats ``app``, ``id``, and ``title`` because a report replaces the record."""
+
+    def __init__(
+        self,
+        *,
+        app: str | None,
+        id: str | None,
+        title: str | None,
+        stream: Any,
+        enabled: bool | None,
+    ) -> None:
+        self._app = app
+        self._id = id
+        self._title = title
+        self._stream = stream
+        self._enabled = enabled
+        self._last_state: State | None = None
+        self._last_bytes: str | None = None
+
+    def __enter__(self) -> "Job":
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: object) -> bool:
+        if self._last_state not in (State.WORKING, State.BLOCKED):
+            return False
+        if exc_type is None:
+            self.done()
+        elif issubclass(exc_type, SystemExit):
+            code = exc.code if isinstance(exc, SystemExit) else None
+            if code in (0, None):
+                self.done()
+            else:
+                self.error()
+        elif issubclass(exc_type, KeyboardInterrupt):
+            self.idle()
+        elif issubclass(exc_type, Exception):
+            self.error()
+        else:
+            # asyncio.CancelledError and other non-Exception BaseExceptions.
+            self.idle()
+        return False
+
+    def update(self, *, progress: int | None = None, msg: str | None = None) -> bool:
+        return self._emit(State.WORKING, progress=progress, msg=msg)
+
+    def blocked(
+        self,
+        *,
+        kind: str | None = None,
+        msg: str | None = None,
+        progress: int | None = None,
+    ) -> bool:
+        return self._emit(State.BLOCKED, kind=kind, msg=msg, progress=progress)
+
+    def done(self, *, msg: str | None = None) -> bool:
+        return self._emit(State.DONE, msg=msg)
+
+    def error(self, *, msg: str | None = None) -> bool:
+        return self._emit(State.ERROR, msg=msg)
+
+    def idle(self, *, msg: str | None = None) -> bool:
+        return self._emit(State.IDLE, msg=msg)
+
+    def _emit(
+        self,
+        state: str,
+        *,
+        msg: str | None = None,
+        kind: str | None = None,
+        progress: int | None = None,
+    ) -> bool:
+        sequence = encode(
+            state,
+            msg=msg,
+            title=self._title,
+            app=self._app,
+            id=self._id,
+            kind=kind,
+            progress=progress,
+        )
+        self._last_state = State(state)
+        if sequence == self._last_bytes:
+            return False
+        wrote = _write(sequence, self._stream, self._enabled)
+        if wrote:
+            self._last_bytes = sequence
+        return wrote
+
+
+def _send(
+    state: str,
+    *,
+    msg: str | None = None,
+    title: str | None = None,
+    app: str | None = None,
+    id: str | None = None,
+    kind: str | None = None,
+    progress: int | None = None,
+    stream: IO[str] | None = None,
+    enabled: bool | None = None,
+) -> bool:
+    sequence = encode(
+        state,
+        msg=msg,
+        title=title,
+        app=app,
+        id=id,
+        kind=kind,
+        progress=progress,
+    )
+    return _write(sequence, sys.stderr if stream is None else stream, enabled)
+
+
+class Detection(Enum):
+    SUPPORTED = "supported"
+    UNSUPPORTED = "unsupported"
+    UNKNOWN = "unknown"
+
+
+_DEFAULT_STATES = frozenset(state.value for state in State if state is not State.CLEAR)
+_DEFAULT_KINDS = frozenset(kind.value for kind in Kind)
+
+
+@dataclass(frozen=True)
+class Support:
+    result: Detection
+    states: frozenset[str]
+    kinds: frozenset[str]
+
+    @property
+    def supported(self) -> bool:
+        return self.result is Detection.SUPPORTED
+
+
+def detect(*, timeout: float = 0.2) -> Support:
+    """Ask ``/dev/tty`` whether it supports OSC 7501.
+
+    Call this before reading input. Keystrokes typed during the wait can be
+    consumed, and a reply that arrives after the timeout can leak into later
+    input. Emit paths never call this.
+    """
+    try:
+        import select
+        import termios
+    except ImportError:
+        return _unknown()
+    try:
+        fd = os.open("/dev/tty", os.O_RDWR | os.O_NOCTTY)
+    except OSError:
+        return _unknown()
+    try:
+        try:
+            old = termios.tcgetattr(fd)
+        except termios.error:
+            return _unknown()
+        new = [old[0], old[1], old[2], old[3], old[4], old[5], list(old[6])]
+        new[3] &= ~(termios.ICANON | termios.ECHO | termios.ISIG | termios.IEXTEN)
+        new[0] &= ~(termios.IXON | termios.ICRNL)
+        new[6][termios.VMIN] = 0
+        new[6][termios.VTIME] = 1
+        termios.tcsetattr(fd, termios.TCSANOW, new)
+        try:
+            os.write(fd, query().encode("ascii"))
+            os.write(fd, b"\x1b[c")
+            reader = _ReplyReader()
+            deadline = time.monotonic() + timeout
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                ready, _, _ = select.select([fd], [], [], remaining)
+                if not ready:
+                    break
+                chunk = os.read(fd, 256)
+                if not chunk:
+                    break
+                reader.feed(chunk)
+                if reader._done:
+                    break
+            return _support_from(reader)
+        finally:
+            termios.tcsetattr(fd, termios.TCSANOW, old)
+    finally:
+        os.close(fd)
+
+
+def _unknown() -> Support:
+    return Support(Detection.UNKNOWN, frozenset(), frozenset())
+
+
+def _support_from(reader: "_ReplyReader") -> Support:
+    if reader._result is Detection.SUPPORTED and reader.reply is not None:
+        parsed = parse_reply(reader.reply)
+        if parsed is not None:
+            return parsed
+    if reader._result is Detection.SUPPORTED:
+        return Support(Detection.SUPPORTED, _DEFAULT_STATES, _DEFAULT_KINDS)
+    return Support(reader._result, frozenset(), frozenset())
+
+
+def query() -> str:
+    """The feature-detection query, ``OSC 7501 ; ? ST``."""
+    return "\x1b]7501;?\x1b\\"
+
+
+def parse_reply(sequence: str) -> Support | None:
+    """Parse one support reply. Anything else, including DA1, returns ``None``."""
+    if sequence.endswith("\x1b\\"):
+        body = sequence[: -2]
+    elif sequence.endswith("\x07"):
+        body = sequence[: -1]
+    else:
+        return None
+    if not body.startswith("\x1b]7501;?"):
+        return None
+    rest = body[len("\x1b]7501;?") :]
+    if rest.startswith(":"):
+        rest = rest[1:]
+    elif rest != "":
+        return None
+
+    states: frozenset[str] | None = None
+    kinds: frozenset[str] | None = None
+    for pair in rest.split(":") if rest else ():
+        if "=" not in pair:
+            continue
+        key, value = pair.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if key == "states":
+            states = _csv(value)
+        elif key == "kinds":
+            kinds = _csv(value)
+    return Support(
+        result=Detection.SUPPORTED,
+        states=_DEFAULT_STATES if states is None else states,
+        kinds=_DEFAULT_KINDS if kinds is None else kinds,
+    )
+
+
+def _csv(value: str) -> frozenset[str]:
+    return frozenset(part.strip() for part in value.split(",") if part.strip())
+
+
+class _ReplyReader:
+    """Streaming scan for a 7501 support reply and the following DA1 reply.
+
+    DA1 is a CSI whose first parameter byte is ``?`` and whose final byte is ``c``.
+    OSC ends on BEL or ST. CAN and SUB cancel. ESC restarts a sequence.
+    """
+
+    def __init__(self) -> None:
+        self._state = _GROUND
+        self._buf = bytearray()
+        self._overflow = False
+        self._csi_first = 0
+        self._result = Detection.UNKNOWN
+        self._done = False
+        self.reply: str | None = None
+
+    def feed(self, data: bytes) -> tuple[Detection, bool]:
+        for byte in data:
+            if self._done:
+                break
+            self._feed_byte(byte)
+        return self._result, self._done
+
+    def _feed_byte(self, byte: int) -> None:
+        if self._state == _GROUND:
+            if byte == _ESC:
+                self._state = _ESCAPE
+            return
+        if self._state == _ESCAPE:
+            self._after_esc(byte)
+            return
+        if self._state == _OSC:
+            if byte == _BEL:
+                self._end_osc(b"\x07")
+            elif byte == _ESC:
+                self._state = _OSC_ESC
+            elif byte in (_CAN, _SUB):
+                self._state = _GROUND
+                self._buf.clear()
+                self._overflow = False
+            elif len(self._buf) < _BODY_LIMIT:
+                self._buf.append(byte)
+            else:
+                self._overflow = True
+            return
+        if self._state == _OSC_ESC:
+            if byte == ord("\\"):
+                self._end_osc(b"\x1b\\")
+            else:
+                self._after_esc(byte)
+            return
+        if byte == _ESC:
+            self._state = _ESCAPE
+        elif byte in (_CAN, _SUB):
+            self._state = _GROUND
+        elif 0x40 <= byte <= 0x7E:
+            if byte == ord("c") and self._csi_first == ord("?"):
+                if self._result is Detection.UNKNOWN:
+                    self._result = Detection.UNSUPPORTED
+                self._done = True
+            self._state = _GROUND
+        elif 0x20 <= byte <= 0x3F:
+            if self._csi_first == 0:
+                self._csi_first = byte
+        else:
+            self._state = _GROUND
+
+    def _after_esc(self, byte: int) -> None:
+        if byte == ord("]"):
+            self._buf.clear()
+            self._overflow = False
+            self._state = _OSC
+        elif byte == ord("["):
+            self._csi_first = 0
+            self._state = _CSI
+        elif byte == _ESC:
+            self._state = _ESCAPE
+        else:
+            self._state = _GROUND
+
+    def _end_osc(self, terminator: bytes) -> None:
+        self._state = _GROUND
+        body = bytes(self._buf)
+        self._buf.clear()
+        overflow = self._overflow
+        self._overflow = False
+        if overflow or self._result is not Detection.UNKNOWN or not body.startswith(_REPLY_PREFIX):
+            return
+        self._result = Detection.SUPPORTED
+        self.reply = "\x1b]" + body.decode("ascii") + terminator.decode("ascii")
+
+
+def _write(sequence: str, stream: Any, enabled: bool | None) -> bool:
+    if enabled is None:
+        isatty = getattr(stream, "isatty", None)
+        enabled = bool(isatty()) if isatty is not None else False
+    if not enabled:
+        return False
+    with _lock:
+        stream.write(sequence)
+        flush = getattr(stream, "flush", None)
+        if flush is not None:
+            flush()
+    return True

osc7501-1.0.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: osc7501
+Version: 1.0.0
+Summary: Report terminal program status with OSC 7501.
+Project-URL: Homepage, https://github.com/ysskrishna/osc7501
+Project-URL: Repository, https://github.com/ysskrishna/osc7501.git
+Project-URL: Issues, https://github.com/ysskrishna/osc7501/issues
+Project-URL: Changelog, https://github.com/ysskrishna/osc7501/blob/main/CHANGELOG.md
+Author-email: "Y. Siva Sai Krishna" <sivasaikrishnassk@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,osc,osc7501,status,terminal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OSC 7501
+
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ysskrishna/osc7501/blob/main/LICENSE)
+![Tests](https://github.com/ysskrishna/osc7501/actions/workflows/test.yml/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/osc7501)](https://pypi.org/project/osc7501/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/osc7501?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/osc7501)
+
+Report terminal program status with OSC 7501. Inspired by the [osc-status](https://github.com/jonahsnider/osc-status) npm package.
+
+## Features
+
+- **States**: `idle`, `working`, `done`, `blocked`, `error`, and `clear`
+- **One job**: a context manager that repeats `app`, `id`, and `title` and closes the job for you
+- **Safe text**: control characters become spaces before base64, so one newline cannot drop the report
+- **Optional probe**: ask the terminal whether it implements revision 0.4
+- **Zero dependencies**: the library only uses the Python standard library
+- **TTY gate**: reports are skipped when stderr is a pipe, unless you pass `enabled=True`
+
+## Why OSC 7501?
+
+OSC 9;4 progress can say that a program is busy, at a percentage, or failed. It has no message and no way to say the program is waiting on the user. A window title is one free-form string.
+
+OSC 7501 adds a state, a reason (`permission`, `question`, or `auth`), and a stable `app` name. The terminal decides how to show that. A terminal that does not know the sequence ignores it, so sending a report is safe.
+
+Spec: [Program Status Protocol, revision 0.4](https://control-codes.page/proposals/osc-7501/) (2026-10-10).
+
+## Installation
+
+```bash
+pip install osc7501
+```
+
+## Usage Examples
+
+### Helpers
+
+```python
+from osc7501 import blocked, done, working
+
+working(progress=40, msg="Building docs")
+blocked(kind="permission", msg="Approve deploy?")
+done(msg="Docs built")
+```
+
+Each report replaces the terminal's record. Repeat every field you still want. `clear()` with no `id` removes every record in the terminal.
+
+Reports go to stderr, and only when it is a terminal.
+
+### One job
+
+```python
+from osc7501 import working
+
+with working(app="make", msg="Building docs") as job:
+    job.blocked(kind="question", msg="Overwrite config.toml?")
+    job.done(msg="Docs built")
+```
+
+Enter writes `working`. A clean exit writes `done` with no message. An exception writes `error`. `KeyboardInterrupt` writes `idle`. If you already called `job.done()` or `job.error()`, the exit writes nothing.
+
+`msg` for `kind="auth"` is the prompt, never the secret.
+
+### Detection
+
+```python
+from osc7501 import detect
+
+print(detect().result)
+```
+
+Call `detect()` before reading input. It can consume keystrokes typed during the wait. On Windows, or when `/dev/tty` cannot be opened, the result is `Detection.UNKNOWN`. Helpers never probe on their own.
+
+## Where reports show up
+
+This list is from the [awesome-osc7501 matrix](https://github.com/hyeebeen/awesome-osc7501) dated 2026-10-11. It was not re-checked for this release.
+
+Shows reports: Rex, TUIOS, termio, SwiftTerm, Termy, con-terminal, phux, thurm, wietty, Prowl.
+
+Ignores reports: the Ghostty app (libghostty parses them; the app does not opt in), tmux (drops them unless DCS passthrough and `allow-passthrough` are on; this release does not wrap them), Kitty, WezTerm, Alacritty, iTerm2, Windows Terminal, VS Code, Zed, Warp, zellij.
+
+## API Reference
+
+| Name | Description |
+|------|-------------|
+| `encode(state, *, msg, title, app, id, kind, progress) -> str` | Build one sequence. Does not write. |
+| `working(*, msg, title, app, id, progress, stream, enabled) -> Job` | Write `working` and return a `Job`. |
+| `Job.update(*, progress, msg) -> bool` | Write another `working` report. Skips a byte-identical repeat. |
+| `Job.blocked(*, kind, msg, progress) -> bool` | Write `blocked`, repeating `app`, `id`, and `title`. |
+| `Job.done(*, msg) -> bool` / `Job.error` / `Job.idle` | Write that state. |
+| `idle`, `done`, `error`, `blocked`, `clear` | Write one report. Return `True` only when bytes were written. |
+| `query() -> str` | The `OSC 7501 ; ? ST` query. |
+| `parse_reply(sequence) -> Support \| None` | Parse one reply. Missing lists mean the five states and three kinds. |
+| `detect(*, timeout=0.2) -> Support` | Probe `/dev/tty`. `Support.supported` is true only for `Detection.SUPPORTED`. |
+| `State`, `Kind` | `StrEnum` values. Plain strings are accepted too. |
+
+## Learn More
+
+- [Program Status Protocol (OSC 7501)](https://control-codes.page/proposals/osc-7501/)
+- [Mitchell Hashimoto: A Terminal Protocol for Program Status](https://mitchellh.com/writing/program-status-osc7501)
+- [awesome-osc7501](https://github.com/hyeebeen/awesome-osc7501)
+
+## Acknowledgments
+
+- [Mitchell Hashimoto](https://github.com/mitchellh), for the specification
+- [Jonah Snider](https://github.com/jonahsnider), for [osc-status](https://github.com/jonahsnider/osc-status)
+- [Adam Duke](https://github.com/adamvduke), for [pst](https://github.com/adamvduke/pst)
+
+## Built and maintained by
+
+osc7501 is built and maintained by:
+
+| | Name | GitHub | Role |
+|---|------|--------|------|
+| <img src="https://github.com/ysskrishna.png?size=120" width="60" height="60" alt="Y. Siva Sai Krishna"> | **Y. Siva Sai Krishna** | [@ysskrishna](https://github.com/ysskrishna) | Creator |
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/ysskrishna/osc7501/blob/main/CHANGELOG.md) for a detailed list of changes and version history.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/ysskrishna/osc7501/blob/main/CONTRIBUTING.md) for details.
+
+## Support
+
+If you find this library helpful:
+
+- ⭐ Star the repository
+- 🐛 Report issues
+- 🔀 Submit pull requests
+- 💝 [Sponsor on GitHub](https://github.com/sponsors/ysskrishna)
+
+## License
+
+MIT © [Y. Siva Sai Krishna](https://github.com/ysskrishna) - see [LICENSE](https://github.com/ysskrishna/osc7501/blob/main/LICENSE) file for details.
+
+---
+
+<p align="left">
+  <a href="https://github.com/ysskrishna">Author's GitHub</a> •
+  <a href="https://linkedin.com/in/ysskrishna">Author's LinkedIn</a> •
+  <a href="https://github.com/ysskrishna/osc7501/issues">Report Issues</a> •
+  <a href="https://pypi.org/project/osc7501/">Package on PyPI</a>
+</p>

osc7501-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+osc7501/__init__.py,sha256=b6E9XqBc0Vi-43TBxlPdOVdHi32C_NdYL2yVWsZiGjU,501
+osc7501/encode.py,sha256=5r93P-V5rWoxiW7YRXpqC94j4TeHrutFffWDickT9u4,3794
+osc7501/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+osc7501/terminal.py,sha256=WmdTxXrlARd3vzXBJRT9bjK7GbTizKdL6SFb5LAEUjc,13329
+osc7501-1.0.0.dist-info/METADATA,sha256=IG2O_o8jwrK5yn2IZHADsy2I8vrdHkpMUwTjf_4RhLg,7655
+osc7501-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+osc7501-1.0.0.dist-info/licenses/LICENSE,sha256=Szx3imxJ9EtUI6_eYtQa6jNMVK_1jhrbjMSaHOzIsVE,1076
+osc7501-1.0.0.dist-info/RECORD,,

osc7501-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

osc7501-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Y. Siva Sai Krishna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.