mathcraft-window-tools 0.1.0__tar.gz

mathcraft_window_tools-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include demo.py
+include test_mathematics.py
+include test_input.py
+include test_desktop_cursor.py
+include test_math_entry.py

mathcraft_window_tools-0.1.0/PKG-INFO

@@ -0,0 +1,359 @@
+Metadata-Version: 2.4
+Name: mathcraft-window-tools
+Version: 0.1.0
+Summary: Math helpers and an experimental Windows terminal with input interception and cursor overlays
+Keywords: math,mathematics,vectors,numerical-methods,powershell
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# 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()`.
+
+Установка из локальной папки проекта:
+
+```powershell
+python -m pip install .
+```
+
+Небольшая импортируемая библиотека Python для Windows 10 (сборка 19041+) и Windows 11.
+Создаёт **собственное окно Python/Tkinter**, включает для него `WDA_EXCLUDEFROMCAPTURE`,
+а команды исполняет в отдельном, **постоянном процессе PowerShell 5.1** через stdin/stdout.
+
+## Использование
+
+1. Положите папку `mathcraft` рядом со своим `.py`-файлом.
+2. Выполните:
+
+```python
+import mathcraft
+mathcraft.math()
+```
+
+Или запустите файл `demo.py`:
+
+```powershell
+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`.
+Это импорты стандартной библиотеки, а не скопированные исходники сторонних пакетов.
+
+```python
+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:
+
+```powershell
+python -m unittest -v test_mathematics
+```
+
+
+## Сборка и публикация на PyPI
+
+Из корня проекта:
+
+```powershell
+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, явное включение)
+
+```python
+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](https://learn.microsoft.com/en-us/windows/win32/winmsg/lowlevelkeyboardproc),
+[mouse hook](https://learn.microsoft.com/en-us/windows/win32/winmsg/lowlevelmouseproc),
+[Raw Input](https://learn.microsoft.com/en-us/windows/win32/inputdev/about-raw-input).
+
+Проверки на Windows:
+
+```powershell
+python -m unittest -v test_input test_mathematics
+```
+
+Проверены маршрутизация синтетических структур событий, работа с Unicode в Entry,
+аварийное отключение и установка/снятие настоящих хуков с невидимым тестовым окном.
+Физический ввод в активном терминале, разные раскладки, перетаскивание и совместимость
+с программами записи требуют отдельной ручной проверки; тесты не доказывают
+сокрытие событий от стороннего наблюдателя.
+
+
+## Виртуальный курсор внутри терминала
+
+```python
+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 нескольких мониторов и программы записи отдельно не проверены.
+
+
+## Прозрачные системные курсоры и указатель поверх редакторов
+
+Теперь обычный запуск включает этот режим:
+
+```python
+import mathcraft
+
+mathcraft.math()
+```
+
+При запуске 13 стандартных ролей системного курсора временно заменяются
+полностью прозрачными изображениями. Это не буквальный размер 0×0: используются
+валидные размеры курсора и прозрачные маски. Изменения применяются в памяти;
+регистрация новой схемы в реестре и установка драйверов не выполняются.
+
+Окно виртуального указателя следует за обычной системной позицией мыши и
+отображается над нашим терминалом, PyCharm (`pycharm.exe`, `pycharm64.exe`),
+VS Code (`Code.exe`; также распознаётся `code-insiders.exe`). Выбор определяется именем исполняемого файла окна под
+указателем, а не его заголовком. Переименованные сборки и другие редакторы
+не включены. В остальных приложениях виртуальная стрелка не рисуется,
+хотя стандартные системные курсоры остаются прозрачными до отключения режима.
+
+Обычные клики, наведение, ввод текста, меню и перетаскивание продолжают обрабатываться
+Windows и редакторами. Никакое внедрение в PyCharm/VS Code не выполняется.
+Клавиатурные input-хуки сами по себе этим режимом не включаются.
+Для сочетания с ранее добавленным режимом внутри терминала:
+
+```python
+mathcraft.math(experimental_input=True, virtual_mouse=True)
+```
+
+Внутри терминала при активной виртуальной сессии используется его прежний
+виртуальный указатель; поверх редакторов — обычная позиция системной мыши.
+
+`Ctrl+Alt+F12` действует также вне окна терминала и восстанавливает курсоры.
+Кнопка `Restore cursor / disable input` и закрытие окна выполняют ту же очистку.
+Отдельный процесс хранит копии исходных курсоров и возвращает их при завершении
+родительского Python-процесса либо отсутствии GUI-heartbeat более трёх секунд.
+При отказе точного восстановления используется загрузка выбранной системной схемы.
+Одновременно допускается одна глобальная сессия замены курсоров.
+
+Запуск без глобальной замены:
+
+```python
+mathcraft.math(desktop_cursor=False)
+```
+
+Ручная загрузка выбранной в Windows схемы курсоров, если требуется восстановление:
+
+```powershell
+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()`
+
+```python
+import mathcraft
+
+mathcraft.math(2 + 2, 'ignored', anything=123)
+```
+
+Этот вызов открывает терминал и включает режимы курсора/перехвата. Он не выполняет
+математическое вычисление и не возвращает результат выражения. Позиционные
+аргументы и неизвестные именованные аргументы не используются. Сам Python
+вычисляет выражения до вызова функции: например, `mathcraft.math(1 / 0)` всё равно
+выдаст `ZeroDivisionError` до входа в функцию.
+
+Сигнатура:
+
+```python
+math(*args, title="Window Manager", experimental_input=True,
+     virtual_mouse=True, desktop_cursor=True, **kwargs)
+```
+
+`title` и три переключателя — распознаваемые настройки; их значения применяются.
+Другие именованные аргументы игнорируются. Например, запуск без трёх режимов:
+
+```python
+mathcraft.math(123, title="My Window", experimental_input=False,
+               virtual_mouse=False, desktop_cursor=False)
+```
+
+`mathcraft.launch()` сохранён для совместимости. У него первый позиционный
+аргумент по-прежнему является заголовком окна; у `mathcraft.math()` все
+позиционные аргументы игнорируются. Реальные математические функции остаются
+в `mathcraft.mathematics`.
+
+Проверка API без открытия терминала и изменения системных курсоров:
+
+```powershell
+python -m unittest -v test_math_entry
+```