Skip to content

app_writer

app_writer

Reliable text insertion into a requested desktop application.

Functions:

write_text 

write_text(
    text: str, *, app_name: str = "", timeout_s: float = 2.0
) -> WriteResult

Focus app_name when supplied, insert text, and verify focus.

The preferred AX path avoids touching the clipboard. The fallback uses Diapason's clipboard-preserving paste implementation. It never presses Return, clicks Send, or submits a form.

Source code in src/diapason/desktop/app_writer.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def write_text(text: str, *, app_name: str = "", timeout_s: float = 2.0) -> WriteResult:
    """Focus *app_name* when supplied, insert text, and verify focus.

    The preferred AX path avoids touching the clipboard.  The fallback uses
    Diapason's clipboard-preserving paste implementation.  It never presses
    Return, clicks Send, or submits a form.
    """
    if not text:
        return WriteResult(False, detail="Aucun texte à écrire.")

    resolved = app_name.strip()
    focused = not bool(resolved)
    if resolved:
        from diapason.tools.desktop_tools import open_application

        opened = open_application(resolved)
        if not opened.success:
            return WriteResult(False, app=resolved, detail=opened.content)
        resolved = str(opened.metadata.get("app") or resolved)
        from diapason.desktop.frontmost import wait_until_frontmost

        focused = (
            wait_until_frontmost(resolved, timeout_s=timeout_s)
            if sys.platform == "darwin"
            else True
        )

    # Accessibility insertion is both faster and less invasive than paste.
    try:
        from diapason.desktop.accessibility import insert_text

        if insert_text(text):
            return WriteResult(
                True,
                method="accessibility",
                app=resolved,
                verified=focused,
                detail="Texte écrit par l’API d’accessibilité.",
            )
    except Exception:  # noqa: BLE001 - safe fallback is expected on many hosts
        pass

    from diapason.tools.desktop_tools import PasteToFrontmostTool

    pasted = PasteToFrontmostTool().execute(text=text)
    return WriteResult(
        pasted.success,
        method="clipboard" if pasted.success else "",
        app=resolved,
        verified=bool(pasted.success and focused),
        detail=pasted.content,
    )