PyMemoryEditor 2.0.1__tar.gz → 2.2.0__tar.gz

{pymemoryeditor-2.0.1 → pymemoryeditor-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: PyMemoryEditor
-Version: 2.0.1
+Version: 2.2.0
 Summary: Read, write and scan process memory in a few lines of Python — Cheat Engine-style scans, pointer chains and AOB search on Windows, Linux and macOS.
 Project-URL: Homepage, https://github.com/JeanExtreme002/PyMemoryEditor
 Project-URL: Documentation, https://pymemoryeditor.readthedocs.io
@@ -138,32 +138,6 @@ That's it — read, write or scan another process in three lines, the same way o
 
 ---
 
-## What's inside
-
-### 🐍 The Python library
-
-Full control over another process's memory — in a few lines of Python:
-
-- ✅ **Read & write** values (`int`, `float`, `bool`, `str`, `bytes`)
-- 🔍 **Value scan** with eight comparison modes
-- 🎯 **Pattern scan** (IDA-style AOB & regex)
-- 🔗 **Pointer chains** + a live `RemotePointer` handle
-- 🧭 **Pointer scan** — find static pointers that survive ASLR
-- 🗺️ **Memory map**, **modules**, **threads**
-- 🧱 **Allocate & free** remote memory (Windows / macOS)
-
-### 🖥️ The bundled GUI app
-
-All the library's power — no code required:
-- ⚡ **Zero setup** — attach to a process and start scanning in seconds
-- 🧲 **Refine workflow** — First Scan → Next Scan with live visual feedback
-- 📋 **Cheat table** — freeze / write values on the fly, JSON import/export
-- 🔬 **Hex viewer** — browse raw memory and write back inline
-- 🧩 **Pointer scan UI** — scan, export & rescan across sessions with a few clicks
-- 🎨 **One-click access** — every feature at your fingertips, no code needed
-
----
-
 ## 📖 Documentation
 
 Full documentation lives at **[pymemoryeditor.readthedocs.io](https://pymemoryeditor.readthedocs.io)** — installation, the Cheat Engine workflow, every method and parameter, the GUI app guide, platform notes and troubleshooting.

{pymemoryeditor-2.0.1 → pymemoryeditor-2.2.0}/PyMemoryEditor/__init__.py

@@ -8,7 +8,7 @@ Supported platforms: Windows, Linux and macOS (32-bit and 64-bit).
 """
 
 __author__ = "Jean Loui Bernard Silva de Jesus"
-__version__ = "2.0.1"
+__version__ = "2.2.0"
 
 import logging
 import sys

pymemoryeditor-2.2.0/PyMemoryEditor/__main__.py

@@ -0,0 +1,4 @@
+from PyMemoryEditor.app.application import main_cli
+
+if __name__ == "__main__":
+    main_cli()

pymemoryeditor-2.2.0/PyMemoryEditor/app/__init__.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""
+PyMemoryEditor App.
+
+A Cheat-Engine-inspired memory editor built on PySide6 (Qt for Python).
+Cross-platform: works on Windows, Linux and macOS.
+
+Entry points: PyMemoryEditor.app.application:main_cli for the console script
+(adds Ctrl+C handling), :main to run the app in-process without touching the
+caller's signal handlers.
+"""

pymemoryeditor-2.2.0/PyMemoryEditor/app/_auto_refresh_dialog.py

@@ -0,0 +1,244 @@
+# -*- coding: utf-8 -*-
+"""
+Shared base for the read-only, auto-refreshing table dialogs (Memory Map,
+Modules, Threads).
+
+All three did the same dance — run a one-shot read off the UI thread, repopulate
+a sortable table when it returns, poll on a timer, and tear the worker down
+safely on close — each with its own near-identical ``_*Worker(QThread)`` and
+lifecycle boilerplate. That triplicated the fiddly bits (the in-flight guard
+that self-throttles the poll, the detach-on-shutdown safety) where a fix to one
+copy wouldn't reach the others. This owns the lifecycle once; subclasses provide
+only what differs: how to fetch the data, and how to render it.
+
+It also owns *when* a failure is worth interrupting the user — see
+:meth:`AutoRefreshTableDialog._handle_failed`.
+"""
+from typing import Callable, Optional
+
+from PySide6.QtCore import QElapsedTimer, QThread, QTimer, Signal
+from PySide6.QtWidgets import QDialog
+
+from ._widgets import TearsDownOnClose, shutdown_worker_thread
+
+
+# How long a target may keep failing before the auto-refresh gives up. Not
+# every failure is terminal (``CreateToolhelp32Snapshot`` is documented to fail
+# transiently while a target loads images), so a blip must not freeze a window
+# that would recover next tick. In wall-clock, not ticks: the intervals differ
+# by more than 10x across the windows that share this budget.
+_FAILURE_GRACE_MS = 3000
+
+
+class _DataWorker(QThread):
+    """Runs a no-arg ``fetch`` callable off the UI thread, once."""
+
+    ready = Signal(object)
+    failed = Signal(str)
+
+    def __init__(self, fetch: Callable[[], object], parent=None):
+        super().__init__(parent)
+        self._fetch = fetch
+
+    def run(self) -> None:
+        try:
+            data = self._fetch()
+        except Exception as exc:  # noqa: BLE001 — surfaced to the UI as a string
+            self.failed.emit(str(exc))
+            return
+        self.ready.emit(data)
+
+
+class AutoRefreshTableDialog(TearsDownOnClose, QDialog):
+    """Owns the fetch-worker lifecycle + auto-refresh timer for a table dialog.
+
+    Subclasses must:
+
+    * call ``super().__init__(process, refresh_interval_ms=..., parent=...)``,
+      then build their UI, then ``refresh()``, then ``_start_auto_refresh()``;
+    * implement :meth:`_fetch_data` (runs in the worker thread) and
+      :meth:`_on_data_ready` (runs on the UI thread);
+    * implement :meth:`_on_data_failed` and (optionally) :meth:`_set_loading_hint`.
+    """
+
+    def __init__(self, process, *, refresh_interval_ms: int, parent=None):
+        super().__init__(parent)
+        self._process = process
+        self._worker: Optional[_DataWorker] = None
+        self._has_data = False
+        self._refresh_interval_ms = refresh_interval_ms
+        self._auto_timer: Optional[QTimer] = None
+        # Failure state, all reset by a success or an explicit refresh(). See
+        # _handle_failed for how they decide what reaches the user.
+        self._last_error: Optional[str] = None  # doubles as "already reported"
+        self._failing_since: Optional[QElapsedTimer] = None  # streak clock
+        # Read by subclasses that rebuild their status line on user input, so
+        # the "stopped" note isn't replaced by a count that looks live.
+        self._polling_gave_up = False
+
+    def _start_auto_refresh(self) -> None:
+        """Begin polling. Call once, after the first ``refresh()``.
+
+        The ``refresh()`` in-flight guard self-throttles the cadence to however
+        long a fetch actually takes, so the timer can't stack workers on a slow
+        target.
+        """
+        self._auto_timer = QTimer(self)
+        self._auto_timer.setInterval(self._refresh_interval_ms)
+        self._auto_timer.timeout.connect(self._auto_refresh_tick)
+        self._auto_timer.start()
+
+    # ------------------------------------------------------------------ #
+    # Hooks for subclasses
+    # ------------------------------------------------------------------ #
+
+    def _fetch_data(self):
+        """Read the data to display. Runs in the worker thread; may raise."""
+        raise NotImplementedError
+
+    def _on_data_ready(self, data) -> None:
+        """Render ``data`` into the table. Runs on the UI thread."""
+        raise NotImplementedError
+
+    def _on_data_failed(self, message: str) -> None:
+        """Report a failed fetch. Runs on the UI thread.
+
+        Called only for a failure the user needs to see — the first fetch, or
+        the one that makes the poll give up — and never twice for the same
+        error (see :meth:`_handle_failed`), so a modal is safe here.
+        """
+        raise NotImplementedError
+
+    def _set_loading_hint(self) -> None:
+        """Optionally show a one-time loading message before the first fetch."""
+
+    def _on_polling_stopped(self) -> None:
+        """Note that the auto-refresh gave up. Runs on the UI thread.
+
+        Fires once, when a target has been failing for ``_FAILURE_GRACE_MS``.
+        The table is frozen on its last good data from here on, so subclasses
+        should say so. Optional.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle (shared)
+    # ------------------------------------------------------------------ #
+
+    def refresh(self) -> None:
+        """Fetch now, on the user's behalf.
+
+        Clears the error latch and restarts a poll that repeated failures
+        stopped. The timer goes through :meth:`_auto_refresh_tick` instead,
+        which must *not* re-arm — and neither may a dismissed dialog, whose
+        teardown latch is one-way.
+        """
+        if self._is_dismissed():
+            return
+        self._last_error = None
+        self._failing_since = None
+        self._polling_gave_up = False
+        if self._auto_timer is not None and not self._auto_timer.isActive():
+            self._auto_timer.start()
+        self._start_fetch()
+
+    def _auto_refresh_tick(self) -> None:
+        """Timer-driven fetch — never re-arms after a failure."""
+        self._start_fetch()
+
+    def _start_fetch(self) -> None:
+        # A worker started after the teardown could never be joined again.
+        if self._is_dismissed():
+            return
+
+        # Skip if a fetch is already in flight — the timer would otherwise stack
+        # workers on a slow target. This self-throttles to the real fetch time.
+        if self._worker is not None and self._worker.isRunning():
+            return
+
+        # Loading hint only before the first successful fetch; the periodic
+        # refresh updates silently to avoid flicker.
+        if not self._has_data:
+            self._set_loading_hint()
+
+        worker = _DataWorker(self._fetch_data, self)
+        worker.ready.connect(self._handle_ready)
+        worker.failed.connect(self._handle_failed)
+        worker.finished.connect(lambda w=worker: self._on_worker_finished(w))
+        self._worker = worker
+        worker.start()
+
+    def _handle_ready(self, data) -> None:
+        if self._is_dismissed():
+            return
+        self._has_data = True
+        self._last_error = None
+        self._failing_since = None
+        self._on_data_ready(data)
+
+    def _handle_failed(self, message: str) -> None:
+        """Handle a failed fetch: report it only when the user needs to know.
+
+        Once the target is gone (or its handle was closed by File → Change
+        Process) *every* tick fails, and ``_on_data_failed`` pops a **modal**
+        dialog. A modal runs a nested event loop, so the timer fires again while
+        it is up and the failures stack — hundreds of focus-stealing dialogs the
+        user could only escape by killing the app from another TTY (issue #74).
+
+        Reporting is therefore tied to the two moments where a failure changes
+        what the user sees: the **first** fetch (empty window) and the one that
+        makes the poll **give up** (frozen table). Everything in between heals
+        quietly — and that silence is load-bearing: reporting every failure
+        re-opens the spam, since a target failing on alternating ticks stacks a
+        modal per failure until the stack runs out.
+
+        A dismissed dialog reports nothing. The teardown disconnects the worker,
+        but a delivery already queued then must not raise a modal over a window
+        that is gone — during ``MainWindow.closeEvent`` that would be a nested
+        event loop in the middle of teardown.
+        """
+        if self._is_dismissed():
+            return
+
+        if self._failing_since is None:
+            self._failing_since = QElapsedTimer()
+            self._failing_since.start()
+            gave_up = False
+        else:
+            gave_up = (
+                self._failing_since.elapsed() >= _FAILURE_GRACE_MS
+                and self._auto_timer is not None
+                and self._auto_timer.isActive()
+            )
+
+        if gave_up and self._auto_timer is not None:
+            self._auto_timer.stop()
+            self._polling_gave_up = True
+
+        never_reported_yet = not self._has_data and self._last_error is None
+        if (gave_up or never_reported_yet) and message != self._last_error:
+            self._last_error = message
+            self._on_data_failed(message)
+
+        # After the report, so the "stopped" note is what stays on screen.
+        if gave_up:
+            self._on_polling_stopped()
+
+    def _on_worker_finished(self, worker) -> None:
+        """Retire the worker that just finished — and only that one.
+
+        ``finished`` is queued, so it can arrive after the next tick already
+        started a replacement. Clearing ``self._worker`` blindly would drop the
+        reference to that *running* worker and ``deleteLater()`` it — destroying
+        a live QThread aborts the process.
+        """
+        if worker is self._worker:
+            self._worker = None
+        worker.deleteLater()
+
+    def _teardown(self) -> None:
+        if self._auto_timer is not None:
+            self._auto_timer.stop()
+        # Unhook + join the worker; if it can't stop in time it's detached
+        # rather than destroyed under us.
+        shutdown_worker_thread(self._worker, wait_ms=1000)
+        self._worker = None

{pymemoryeditor-2.0.1 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/_widgets.py

@@ -6,12 +6,17 @@ Centralises tiny helpers (numeric sort items, hex address parsing) that
 previously appeared duplicated across several dialog modules.
 """
 
-from typing import Callable, Iterable, List, Optional, Tuple
+from typing import Any, Callable, Iterable, List, Optional, Tuple
 
-from PySide6.QtCore import Qt, QThread
+from PySide6.QtCore import QObject, Qt, QThread
 from PySide6.QtGui import QStandardItem
 
 
+# Monospace stack used across the app for address/value text. An explicit
+# family list rather than the platform's default fixed font, so every table
+# renders addresses at the same family and size on every OS.
+MONOSPACE_FAMILY = "Menlo, Consolas, Courier New"
+
 # Workers that wouldn't stop in time on close are parked here so they are never
 # destroyed while still running (that aborts the whole process with
 # "QThread: Destroyed while thread is still running"). The list is module-level
@@ -39,7 +44,11 @@ def shutdown_worker_thread(worker: Optional[QThread], wait_ms: int = 2000) -> No
     if callable(cancel):
         cancel()
     try:
-        worker.disconnect()  # drop every outgoing connection at once
+        # The four-argument static form on purpose: bare `worker.disconnect()`
+        # raises TypeError in PySide6 (so this except swallowed it and nothing
+        # was disconnected), and `worker.disconnect(worker)` only drops
+        # connections whose *receiver* is the worker — ours belong to the dialog.
+        QObject.disconnect(worker, None, None, None)
     except (RuntimeError, TypeError):
         pass
 
@@ -47,31 +56,114 @@ def shutdown_worker_thread(worker: Optional[QThread], wait_ms: int = 2000) -> No
         worker.wait(wait_ms)
 
     if worker.isRunning():
-        worker.setParent(None)
-        _DETACHED_WORKERS.append(worker)
-        worker.finished.connect(lambda: _reap_detached_worker(worker))
+        detach_worker(worker)
     else:
         worker.deleteLater()
 
 
+def detach_worker(worker: QThread) -> None:
+    """Park a worker that wouldn't stop, so its owner can be destroyed.
+
+    Reparents it away from the dying widget and holds it in the module-level
+    registry until it finishes on its own. Callers that stop workers their own
+    way park them here too, so threads that outlived their owner are all in one
+    place.
+    """
+    worker.setParent(None)
+    _DETACHED_WORKERS.append(worker)
+    worker.finished.connect(lambda: _reap_detached_worker(worker))
+    # A worker that finished before this connect already emitted, so the reaper
+    # would never run and it would sit here for good.
+    if worker.isFinished():
+        _reap_detached_worker(worker)
+
+
 def _reap_detached_worker(worker: QThread) -> None:
     if worker in _DETACHED_WORKERS:
         _DETACHED_WORKERS.remove(worker)
     worker.deleteLater()
 
 
+class TearsDownOnClose:
+    """Mixin that runs a dialog's teardown on *every* way out, not just close.
+
+    ``QDialog`` delivers a ``QCloseEvent`` only for a real close. The app's own
+    "Close" buttons call ``accept()`` and Esc reaches ``reject()``; both land in
+    ``done()``, which hides the dialog and emits ``finished`` *without* any
+    close event — so a teardown living in ``closeEvent`` never ran, and the
+    dialog kept polling, hidden and unreachable.
+
+    Subclasses implement :meth:`_teardown`; the mixin runs it exactly once,
+    whichever way the dialog is dismissed, and must precede ``QDialog`` in the
+    bases so its overrides win. Running once makes instances single-use, which
+    is what every caller here assumes.
+    """
+
+    def _teardown(self) -> None:
+        """Release timers and background threads. Runs exactly once."""
+        raise NotImplementedError
+
+    def _is_dismissed(self) -> bool:
+        """Whether the teardown has run. Guards live on this, not on a repeated
+        attribute lookup a typo could silently disable."""
+        return getattr(self, "_teardown_done", False)
+
+    def _run_teardown_once(self) -> None:
+        if self._is_dismissed():
+            return
+        self._teardown_done = True
+        self._teardown()
+
+    def done(self, result: int) -> None:  # noqa: N802 — Qt naming
+        self._run_teardown_once()
+        super().done(result)
+
+    def closeEvent(self, event) -> None:  # noqa: N802 — Qt naming
+        self._run_teardown_once()
+        super().closeEvent(event)
+
+
 class NumericItem(QStandardItem):
     """A QStandardItem that compares by its Qt.UserRole int payload.
 
     Used by columns showing formatted numbers (sizes, addresses, PIDs) so the
     table sorts by the underlying value rather than the lexical label.
+
+    The data storage interface is overridden because Qt keeps item data in a
+    QVariant, whose integers cap at qint64. Values past 2**63 can't make that
+    conversion — Linux x86-64 maps [vsyscall] at 0xffffffffff600000, so the
+    memory map hands one such address to the C++ side and gets "OverflowError:
+    int too big to convert", leaving the table half-populated. The workaround
+    is to keep user-role payloads on the Python side, where an int is an int.
+
+    The flip side: those payloads never reach the C++ model, so read them off
+    the item (``item.data(role)``) and never through ``model.data(index,
+    role)`` — that path converts the value back into a QVariant and overflows
+    all over again.
     """
 
-    def __lt__(self, other):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._user_data: dict[int, Any] = {}
+
+    def setData(self, value: Any, role: int = Qt.UserRole):
+        if role >= Qt.UserRole:
+            self._user_data[int(role)] = value
+            self.emitDataChanged()
+        else:
+            super().setData(value, role)
+
+    def data(self, role: int = Qt.UserRole) -> Any:
+        if role >= Qt.UserRole:
+            return self._user_data.get(int(role))
+        else:
+            return super().data(role)
+
+    def __lt__(self, other: QStandardItem) -> bool:
         try:
-            return int(self.data(Qt.UserRole)) < int(other.data(Qt.UserRole))
+            return int(self.data()) < int(other.data())
         except (TypeError, ValueError):
-            return super().__lt__(other)
+            return self.text() < other.text()
 
 
 def parse_hex_address(text: str) -> Optional[int]:

{pymemoryeditor-2.0.1 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/application.py

@@ -6,6 +6,8 @@ A Cheat-Engine-inspired memory scanner built on PySide6 (Qt for Python),
 working on Windows, Linux and macOS.
 """
 import sys
+import signal
+import contextlib
 from dataclasses import dataclass
 
 from PyMemoryEditor import __version__
@@ -451,14 +453,50 @@ QLabel#processBadge {
 """
 
 
+@contextlib.contextmanager
+def _scoped_signal_handler(signalnum, handler):
+    """
+    Temporarily change a signal handler in the scope of a with block.
+
+    Becomes a no-op off the main thread, where `signal.signal` raises
+    ValueError: an embedder driving the app from a worker thread shouldn't be
+    hard-crashed just because the Ctrl+C handler can't be installed there.
+    """
+    try:
+        previous_handler = signal.signal(signalnum, handler)
+    except ValueError:
+        # Off the main thread. (`signal.signal` also raises ValueError for a
+        # signal number the platform rejects, but the only call site passes
+        # SIGINT, which every supported platform has.)
+        yield
+        return
+    try:
+        yield
+    finally:
+        # `signal.signal` reports None when "an unknown handler is in effect",
+        # i.e. one installed outside Python — plausible when the app is
+        # embedded in a host that set SIGINT up in C before the signal module
+        # initialized. Passing that None back raises TypeError, which would
+        # blow up on the way out of a run that otherwise succeeded, so leave
+        # the handler alone instead: SIG_DFL is closer to the host's intent
+        # than a crash.
+        if previous_handler is not None:
+            signal.signal(signalnum, previous_handler)
+
+
 def main(argv=None):
     """
-    Entry point for the ``pymemoryeditor`` console script.
+    Run the app. Safe to call in-process: it installs no signal handler.
 
     ``argv`` defaults to ``sys.argv`` so packaging tools (which call
     ``main()`` with no arguments) keep working. Tests and embedders can pass
     an explicit list — previously a positional ``*args`` was accepted but
     ignored, which made the parameter meaningless.
+
+    Terminal users want Ctrl+C to kill the app, which takes a process-wide
+    signal change — see :func:`main_cli`, the console-script entry point.
+    Library callers get this function untouched so embedding the app can't
+    disturb the host's own SIGINT handling.
     """
     if argv is None:
         argv = sys.argv
@@ -501,10 +539,30 @@ def main(argv=None):
         app.exec()
     finally:
         try:
-            process.close()
+            # `process` is only the handle the picker opened; File → Change
+            # Process… released that one and attached the window to another.
+            window.process.close()
         except Exception:
             pass
 
 
+def main_cli(argv=None):
+    """
+    Entry point for the ``pymemoryeditor`` console script and ``python -m``.
+
+    Qt's event loop blocks inside C++, so Python's default SIGINT handler only
+    runs once the interpreter next regains control. In practice it raised
+    KeyboardInterrupt inside our own _PointerCursorFilter.eventFilter override,
+    where PySide6 swallows it and merely prints a traceback (#76). Hand SIGINT
+    back to the OS for the duration of the run so Ctrl+C from a terminal
+    terminates the app immediately.
+
+    Kept separate from :func:`main` so that process-wide change only happens
+    when the app *is* the process, never when it is embedded in someone else's.
+    """
+    with _scoped_signal_handler(signal.SIGINT, signal.SIG_DFL):
+        return main(argv)
+
+
 if __name__ == "__main__":
-    main()
+    main_cli()

{pymemoryeditor-2.0.1 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/cheat_poll_worker.py

@@ -106,6 +106,11 @@ class _CheatPollWorker(QThread):
         with QMutexLocker(self._mutex):
             self._pending_writes.append((address, pytype, length, value))
 
+    def _stopping(self) -> bool:
+        """Whether ``stop`` was asked for. Cheap enough to check per entry."""
+        with QMutexLocker(self._mutex):
+            return self._stop
+
     def stop(self) -> None:
         with QMutexLocker(self._mutex):
             self._stop = True
@@ -126,6 +131,8 @@ class _CheatPollWorker(QThread):
 
         failures: List[Tuple[int, type, int, str]] = []
         for address, pytype, length, value in pending:
+            if self._stopping():
+                break  # the handle is about to go — see _poll_once
             try:
                 self._process.write_process_memory(address, pytype, length, value)
             except Exception as exc:  # noqa: BLE001
@@ -206,6 +213,11 @@ class _CheatPollWorker(QThread):
                     values_by_address = None
 
             for address in addresses:
+                # Per entry, not per tick: shutdown() closes the handle right
+                # after stop(), and a write on a recycled one hits another
+                # process.
+                if self._stopping():
+                    return results
                 frozen_value, is_frozen = freeze_by_addr[(pytype, length, address)]
                 if values_by_address is not None:
                     current = values_by_address.get(address)