mathcraft-window-tools

Имя пакета на PyPI: mathcraft-window-tools; имя импорта: mathcraft.

Пакет содержит математический API и экспериментальный Windows-терминал. mathcraft.math() не является вычислением: он открывает окно PowerShell и по умолчанию включает перехват ввода внутри терминала, виртуальную мышь и временную замену стандартных системных курсоров на прозрачные. Над терминалом, PyCharm и VS Code отображается отдельный указатель. Ctrl+Alt+F12 отключает эти режимы. Импорт пакета и вызовы mathcraft.mathematics сами по себе ничего из этого не запускают.

Математические функции, статистика, векторы, матрицы и численные методы на Python 3.8+. Математический API не требует Tkinter. Дополнительно пакет содержит описанное ниже окно PowerShell для Windows; оно запускается только явным вызовом math().

Установка из локальной папки проекта:

python -m pip install .

Небольшая импортируемая библиотека Python для Windows 10 (сборка 19041+) и Windows 11. Создаёт собственное окно Python/Tkinter, включает для него WDA_EXCLUDEFROMCAPTURE, а команды исполняет в отдельном, постоянном процессе PowerShell 5.1 через stdin/stdout.

Использование

1. Положите папку mathcraft рядом со своим .py-файлом.
2. Выполните:

import mathcraft
mathcraft.math()

Или запустите файл demo.py:

python demo.py

Нужен только обычный Python 3 с Tkinter. Дополнительные pip install не требуются. math() запускает цикл графического интерфейса в основном потоке и возвращается после закрытия окна.

Как это работает

• ctypes получает настоящий top-level HWND окна Tk через GetAncestor(..., GA_ROOT).
• SetWindowDisplayAffinity(hwnd, 0x11) применяется к собственному окну Python.
• GetWindowDisplayAffinity дополнительно проверяет установленный флаг.
• Обычное окно powershell.exe не показывается. PowerShell получает команды через stdin, а его вывод отображается внутри защищённого окна Python.
• Текущие переменные и рабочий каталог сохраняются между командами благодаря постоянной сессии.

Ограничения

• Это не штатное консольное окно Windows PowerShell и не полноценный ConPTY-терминал.
• Команды, которым нужен интерактивный диалог/TTY (Read-Host, консольные редакторы), не поддерживаются.
• Остановка долго выполняющейся команды через интерфейс не реализована, закройте окно для завершения процесса.
• Нельзя снаружи Python назначить WDA чужому окну powershell.exe.
• Это не абсолютная защита от всех методов захвата, и для неё требуется работающий DWM.
• Выполнены автоматические и нативные проверки в Windows; совместимость с конкретными программами записи отдельно не проверена.

Документация Microsoft: https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowdisplayaffinity

Математика (Python API)

Модуль mathcraft.mathematics работает без дополнительных зависимостей. Функции math (например, sqrt, sin, cos, log, factorial, comb, gcd, константы pi, e) доступны под исходными именами установленного Python. Из statistics доступны mean, fmean, median, mode, multimode, variance, pvariance, stdev, pstdev, geometric_mean, harmonic_mean. Это импорты стандартной библиотеки, а не скопированные исходники сторонних пакетов.

from mathcraft import mathematics as m

print(m.sqrt(81))                         # 9.0
print(m.mean([2, 4, 6]))                   # 4
print(m.dot([1, 2], [3, 4]))               # 11.0
print(m.norm([3, 4]))                      # 5.0
print(m.cross([1, 0, 0], [0, 1, 0]))       # [0, 0, 1]
print(m.transpose([[1, 2], [3, 4]]))       # [[1, 3], [2, 4]]
print(m.matmul([[1, 2]], [[3], [4]]))      # [[11.0]]
print(m.derivative(lambda x: x*x, 3))      # примерно 6
print(m.integrate(lambda x: x*x, 0, 1))    # примерно 1/3
print(m.bisect(lambda x: x*x-2, 0, 2))     # примерно sqrt(2)

Дополнительные методы рассчитаны на вещественные числа. dot требует одинаковой длины векторов, cross — длины 3. Матрицы должны быть непустыми и прямоугольными; для умножения число столбцов первой равно числу строк второй.

derivative(function, x, h=1e-5) использует центральную разность. integrate(function, a, b, steps=1000) использует метод трапеций; обратные пределы меняют знак результата. Это приближённые вычисления. bisect(function, a, b, tolerance=1e-10, max_iterations=1000) требует непрерывной функции и интервала со сменой знака (либо нуля на границе). tolerance ограничивает половину ширины интервала, а не значение функции. Исчерпание итераций или точности float приводит к RuntimeError. Неверные размеры, нечисловые параметры с неподходящими типами и неограниченные значения дают ValueError/TypeError. Математические вызовы из этого примера выполняются в Python, не в строке PS>.

Проверка математического API:

python -m unittest -v test_mathematics

Сборка и публикация на PyPI

Из корня проекта:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*

Загрузка требует учётной записи PyPI и API-токена. Токен вводится средствами Twine, а не сохраняется в исходниках. Пакет ещё не опубликован; после публикации установка будет выполняться командой python -m pip install mathcraft-window-tools. Доступность имени окончательно определяется PyPI при первой публикации. Автор и лицензия в метаданных пока не указаны: добавьте свои реальные данные и выбранный текст лицензии перед публичным выпуском.

Автоматическое копирование

Выделенный мышью или клавиатурой текст в выводе терминала и строке ввода автоматически копируется в системный буфер обмена после отпускания кнопки мыши или клавиши. Нажимать Ctrl+C не требуется. Пустое выделение не очищает буфер. Копируется ровно выделенный текст, включая приглашение PS>, если оно выделено.

Экспериментальный перехват ввода (Windows, явное включение)

import mathcraft

mathcraft.math(experimental_input=True)

Обычный mathcraft.math() включает все три режима: experimental_input=True, virtual_mouse=True, desktop_cursor=True. Отключение глобальной замены курсоров выполняется параметром desktop_cursor=False; остальные переключатели независимы. Режим использует WH_KEYBOARD_LL и WH_MOUSE_LL на отдельном потоке. Поддерживаемые клавиши обрабатываются в Tkinter; клики левой, средней и правой кнопок и вертикальное колесо передаются собственным виджетам. Исходные события подавляются для последующих низкоуровневых хуков. Перехват работает только при активном окне терминала; клики перехватываются только в его клиентской области. Заголовок окна и другие приложения сохраняют обычную обработку.

Отключение: Ctrl+Alt+F12 или кнопка Disable input interception. Повторное включение требует перезапуска с явным параметром. Статус показан в окне. При закрытии окна, выходе из mainloop, завершении PowerShell и ошибке запуска хуки снимаются. Если GUI не обновлялся 0,5 секунды, новые события пропускаются; при переполнении очереди и ошибках режим отключается. Завершения уже перехваченных клавиш/кнопок могут поглощаться для согласования пар press/release.

Точные границы эксперимента

• Без virtual_mouse=True движение и координаты системного курсора остаются обычными. Виртуальный режим описан ниже.
• Модификаторы, сочетания с Alt/Win, функциональные клавиши, дополнительные кнопки мыши, горизонтальное колесо и программно внедрённые события проходят обычно.
• Поддерживаются обычный текст, основные клавиши редактирования/навигации, Ctrl+A/C/V/X/Z/Y. IME, AltGr, составные символы, системные переключения раскладки и двойные клики не имеют гарантии совместимости. Dead key отключает режим.
• Raw Input, драйверы, хуки перед нашим хуком и средства чтения содержимого приложения/буфера обмена не блокируются. Автокопирование выделения сохраняется.
• Windows может незаметно снять медленный низкоуровневый хук. Индикатор отображает запрошенный режим, а не подтверждённую изоляцию ввода. Это не антикейлоггер и не гарантия невидимости для программ записи.

Документация: keyboard hook, mouse hook, Raw Input.

Проверки на Windows:

python -m unittest -v test_input test_mathematics

Проверены маршрутизация синтетических структур событий, работа с Unicode в Entry, аварийное отключение и установка/снятие настоящих хуков с невидимым тестовым окном. Физический ввод в активном терминале, разные раскладки, перетаскивание и совместимость с программами записи требуют отдельной ручной проверки; тесты не доказывают сокрытие событий от стороннего наблюдателя.

Виртуальный курсор внутри терминала

import mathcraft

mathcraft.math(experimental_input=True, virtual_mouse=True)

virtual_mouse=True также включает экспериментальный перехват клавиатуры. Когда системная мышь находится внутри клиентской области активного терминала, следующее поддерживаемое движение начинает виртуальную сессию. Обычный указатель остаётся в точке начала сессии; отдельные координаты накапливаются внутри библиотеки. Клики, выделение, наведение и вертикальная прокрутка направляются собственным виджетам по виртуальным координатам. Вместо системной стрелки отображается собственный указатель в неактивируемом окне с WDA_EXCLUDEFROMCAPTURE. Это окно не забирает фокус и не участвует в обработке кликов.

При выходе виртуального указателя за границы клиентской области обычная мышь возвращается в текущую виртуальную точку. Так можно перейти в другие приложения и пользоваться заголовком окна. Потеря фокуса, Ctrl+Alt+F12, кнопка отключения, закрытие окна и остановка GUI-обработки более чем на 0,5 секунды также возвращают штатную обработку. Если другое приложение само переместило системный курсор, библиотека не перезаписывает его новую позицию. Вне терминала перехват не применяется.

Координаты GUI и хуков согласованы через временный DPI-контекст потока; глобальные настройки DPI процесса и системная схема курсоров не меняются.

Режим не блокирует Raw Input, драйверные наблюдатели, программный ввод и хуки, установленные перед нашим. Модификаторы и системные комбинации по-прежнему проходят обычно; не реализованные в собственном обработчике Ctrl-комбинации передаются Tk. Буфер обмена, включая ранее добавленное автоматическое копирование, не изолирован. Исключение окна указателя из захвата зависит от способа записи, как и исключение самого терминала. Проверка флага WinAPI не доказывает совместимость со всеми программами записи.

Проверки включают синтетические события, снятие нативных хуков, восстановление курсоров виджетов и проверку affinity окна указателя. Дополнительно выполнен нативный интеграционный тест с помеченными искусственными движениями/кликами: тестовый подкласс обрабатывал только их как физические события. Проверены неподвижность системного курсора, движение виртуального, маршрутизация кликов в Entry и восстановление/снятие хуков после отключения. Физические устройства, разные DPI нескольких мониторов и программы записи отдельно не проверены.

Прозрачные системные курсоры и указатель поверх редакторов

Теперь обычный запуск включает этот режим:

import mathcraft

mathcraft.math()

При запуске 13 стандартных ролей системного курсора временно заменяются полностью прозрачными изображениями. Это не буквальный размер 0×0: используются валидные размеры курсора и прозрачные маски. Изменения применяются в памяти; регистрация новой схемы в реестре и установка драйверов не выполняются.

Окно виртуального указателя следует за обычной системной позицией мыши и отображается над нашим терминалом, PyCharm (pycharm.exe, pycharm64.exe), VS Code (Code.exe; также распознаётся code-insiders.exe). Выбор определяется именем исполняемого файла окна под указателем, а не его заголовком. Переименованные сборки и другие редакторы не включены. В остальных приложениях виртуальная стрелка не рисуется, хотя стандартные системные курсоры остаются прозрачными до отключения режима.

Обычные клики, наведение, ввод текста, меню и перетаскивание продолжают обрабатываться Windows и редакторами. Никакое внедрение в PyCharm/VS Code не выполняется. Клавиатурные input-хуки сами по себе этим режимом не включаются. Для сочетания с ранее добавленным режимом внутри терминала:

mathcraft.math(experimental_input=True, virtual_mouse=True)

Внутри терминала при активной виртуальной сессии используется его прежний виртуальный указатель; поверх редакторов — обычная позиция системной мыши.

Ctrl+Alt+F12 действует также вне окна терминала и восстанавливает курсоры. Кнопка Restore cursor / disable input и закрытие окна выполняют ту же очистку. Отдельный процесс хранит копии исходных курсоров и возвращает их при завершении родительского Python-процесса либо отсутствии GUI-heartbeat более трёх секунд. При отказе точного восстановления используется загрузка выбранной системной схемы. Одновременно допускается одна глобальная сессия замены курсоров.

Запуск без глобальной замены:

mathcraft.math(desktop_cursor=False)

Ручная загрузка выбранной в Windows схемы курсоров, если требуется восстановление:

python -m mathcraft._cursor_guard --restore

Что проверено и что не гарантируется

• Проверены прозрачные AND/XOR-маски всех 13 системных ролей, восстановление их bitmap-данных и hotspots после потери heartbeat, штатное закрытие watchdog и его завершение после аварийного выхода родительского процесса.
• Проверен обычный math(): появление overlay в собственном окне, отключение режима, восстановление курсоров Tk-виджетов. Сопоставление имён редакторов покрыто тестами; работа в живых PyCharm и VS Code отдельно не проверена.
• Окно overlay имеет WDA_EXCLUDEFROMCAPTURE. Совместимость с конкретными программами записи требует отдельного теста. Рекордер может кэшировать прежнее изображение курсора или рисовать собственную стрелку.
• Режим заменяет стандартные системные роли, но не все частные курсоры приложений, включая некоторые формы курсора редакторов или курсор, рисуемый внутри кадра. Такой частный курсор может остаться видимым и попасть в запись.
• Координаты мыши, клики, Raw Input и драйверные наблюдатели не скрываются этим режимом. При одновременном уничтожении Python и его watchdog независимое автоматическое восстановление не гарантируется.

Новая точка входа math()

import mathcraft

mathcraft.math(2 + 2, 'ignored', anything=123)

Этот вызов открывает терминал и включает режимы курсора/перехвата. Он не выполняет математическое вычисление и не возвращает результат выражения. Позиционные аргументы и неизвестные именованные аргументы не используются. Сам Python вычисляет выражения до вызова функции: например, mathcraft.math(1 / 0) всё равно выдаст ZeroDivisionError до входа в функцию.

Сигнатура:

math(*args, title="Window Manager", experimental_input=True,
     virtual_mouse=True, desktop_cursor=True, **kwargs)

title и три переключателя — распознаваемые настройки; их значения применяются. Другие именованные аргументы игнорируются. Например, запуск без трёх режимов:

mathcraft.math(123, title="My Window", experimental_input=False,
               virtual_mouse=False, desktop_cursor=False)

mathcraft.launch() сохранён для совместимости. У него первый позиционный аргумент по-прежнему является заголовком окна; у mathcraft.math() все позиционные аргументы игнорируются. Реальные математические функции остаются в mathcraft.mathematics.

Проверка API без открытия терминала и изменения системных курсоров:

python -m unittest -v test_math_entry