PyMemoryEditor 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: PyMemoryEditor
-Version: 2.1.0
+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.1.0 → 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.1.0"
+__version__ = "2.2.0"
 
 import logging
 import sys

{pymemoryeditor-2.1.0 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/cheat_table.py

@@ -48,7 +48,12 @@ from PyMemoryEditor import AbstractProcess
 from ._widgets import parse_hex_address, shutdown_worker_thread
 from .cheat_entry import CheatEntry
 from .cheat_poll_worker import TICK_INTERVAL_MS, _CheatPollWorker
-from .value_types import VALUE_TYPES, ValueTypeSpec, find_spec, parse_value
+from .value_types import (
+    VALUE_TYPES,
+    ValueTypeSpec,
+    find_spec,
+    parse_value_for_write,
+)
 
 
 # Re-exported for backward compatibility with callers that imported the
@@ -197,10 +202,25 @@ class CheatTable(QWidget):
         delete_shortcut.activated.connect(self._on_remove_selected)
 
     def add_entry(self, entry: CheatEntry) -> None:
+        # Every entry enters here, whichever way it was created — promoted from
+        # a scan, from a pointer dialog, added by hand, or loaded from JSON. A
+        # zero-width buffer reads back empty on every poll tick and can't be
+        # spotted from the table, so the floor is enforced once, at the door,
+        # rather than at each of those call sites. (The AOB pattern spec is the
+        # one whose declared length is 0 — the scanner derives its real width
+        # from the pattern.)
+        entry.length = max(1, int(entry.length))
+
         # If the address already exists, just refresh its description/type.
         for existing in self._entries:
             if existing.address == entry.address:
                 existing.description = entry.description or existing.description
+                # Re-promoting an address that is already in the table is the
+                # third place a spec_label changes, and the cached value has to
+                # go with it here too — _rebuild formats it through the new
+                # spec on the way out of this method.
+                if entry.spec_label != existing.spec_label:
+                    _forget_value_read_as_another_type(existing)
                 existing.spec_label = entry.spec_label
                 existing.length = entry.length
                 self._rebuild()
@@ -257,7 +277,11 @@ class CheatTable(QWidget):
         self._table.setItem(row, self.COL_ADDRESS, addr)
 
         type_label = entry.spec_label
-        if entry.spec.accepts_length_override:
+        # Show the width whenever it belongs to the entry rather than to the
+        # spec. An IDA pattern declares none (length 0) yet carries a real one
+        # here — writes are refused against it — so hiding it left the user
+        # told to "widen the entry" with no way to see what it holds.
+        if entry.spec.accepts_length_override or not entry.spec.length:
             type_label += f"  · {entry.length}B"
         type_item = QTableWidgetItem(type_label)
         type_item.setFlags(Qt.ItemIsEnabled | Qt.ItemIsSelectable)
@@ -312,7 +336,9 @@ class CheatTable(QWidget):
                 # Treat empty as "unfreeze and clear" — no-op.
                 return
             try:
-                value, _length = parse_value(entry.spec, text, entry.length)
+                value, _length = parse_value_for_write(
+                    entry.spec, text, entry.length, entry.last_value
+                )
             except ValueError as exc:
                 QMessageBox.warning(self, "Invalid Value", str(exc))
                 self._suspend_signals = True
@@ -390,6 +416,13 @@ class CheatTable(QWidget):
                     continue
                 entry = self._entries[row]
                 entry.last_value = value
+                # A frozen row whose baseline was dropped — its type changed,
+                # so what the old spec had read no longer means anything —
+                # re-adopts the first value read under the new one. The poll
+                # worker skips a frozen entry with no frozen_value, so without
+                # this the Active box stays ticked while nothing is written.
+                if entry.frozen and entry.frozen_value is None:
+                    entry.frozen_value = value
                 self._update_value_cell(row, entry)
         finally:
             self._suspend_signals = False
@@ -528,16 +561,40 @@ class CheatTable(QWidget):
                 if plan.description is not None:
                     entry.description = plan.description
 
-                if plan.spec is not None:
+                # What the row was showing before this plan touched it. A type
+                # change forgets it, but a write in the same pass still needs
+                # it: an IDA '?' keeps the byte that is already there, and
+                # Byte Array → AOB doesn't change what those bytes mean.
+                # parse_value_for_write ignores it when the type genuinely
+                # changed shape, so a stale int can't be misread as bytes.
+                current = entry.last_value
+                retyped = False
+                if plan.spec is not None and plan.spec.label != entry.spec_label:
+                    retyped = True
                     entry.spec_label = plan.spec.label
+                    _forget_value_read_as_another_type(entry)
+                if plan.spec is not None:
                     if not plan.spec.accepts_length_override:
-                        entry.length = plan.spec.length
+                        # `or entry.length`: the AOB pattern spec declares a
+                        # length of 0 — the scanner derives a match's width from
+                        # the pattern, and an entry has none to derive from — so
+                        # keep the width it already has.
+                        entry.length = plan.spec.length or entry.length
 
                 if plan.value_text is not None:
                     spec = entry.spec
+                    # A retype to a variable-width spec re-sizes the entry from
+                    # the value, rather than inheriting the width of the type it
+                    # replaced. Otherwise three Int32 rows retyped to String
+                    # with "hello" all fail on "the entry holds 4 — widen it
+                    # first", and the bulk dialog has no width field, nor does
+                    # a multi-row selection offer one: a dead end.
+                    cap: Optional[int] = entry.length
+                    if retyped and spec.accepts_length_override:
+                        cap = None
                     try:
-                        value, effective_length = parse_value(
-                            spec, plan.value_text, entry.length
+                        value, effective_length = parse_value_for_write(
+                            spec, plan.value_text, cap, current
                         )
                     except ValueError as exc:
                         failures.append((entry.address, str(exc)))
@@ -665,10 +722,15 @@ class CheatTable(QWidget):
         )
         if not ok:
             return
-        self._entries[row].spec_label = chosen
+        entry = self._entries[row]
+        if chosen != entry.spec_label:
+            entry.spec_label = chosen
+            _forget_value_read_as_another_type(entry)
         spec = find_spec(chosen) or VALUE_TYPES[0]
         if not spec.accepts_length_override:
-            self._entries[row].length = spec.length
+            # Same as the bulk edit: the AOB pattern spec declares no width of
+            # its own, so the entry keeps the one it has.
+            entry.length = spec.length or entry.length
         self._rebuild()
 
     def _change_length(self, row: int) -> None:
@@ -678,7 +740,9 @@ class CheatTable(QWidget):
             "Length (bytes):",
             value=self._entries[row].length,
             minValue=1,
-            maxValue=1024,
+            # An entry already wider than the cap can still be shrunk from here;
+            # it just can't grow past it.
+            maxValue=max(MAX_ENTRY_LENGTH, self._entries[row].length),
         )
         if not ok:
             return
@@ -736,6 +800,41 @@ class CheatTable(QWidget):
                 QMessageBox.warning(self, "Import", f"Skipped a bad entry: {exc}")
 
 
+# Ceiling for an entry's buffer width. Entries are promoted at the width of the
+# value scanned for, which the scanner doesn't cap, so 1024 was too tight — but
+# the poll worker allocates this many bytes per entry on every 100 ms tick, so
+# an unbounded field turns one typo into a multi-gigabyte allocation the tick's
+# blanket except swallows and retries forever. A megabyte is far past any real
+# value and still cheap to read ten times a second.
+MAX_ENTRY_LENGTH = 1_048_576
+
+
+def _forget_value_read_as_another_type(entry: CheatEntry) -> None:
+    """Drop the cached value when ``new_spec`` can't read what produced it.
+
+    ``last_value`` and ``frozen_value`` hold whatever the *previous* spec
+    decoded — an int, a str, raw bytes. Nothing waits for a fresh poll tick
+    before the new spec is used on them, and a spec's ``format`` only accepts
+    what its own ``pytype`` produces: ``_fmt_bytes(1234)`` raises TypeError from
+    inside a Qt slot, and a frozen entry would be re-published to the poll
+    worker to write the old type's value through the new type's ``pytype``.
+    The next tick refills both, so forgetting them costs a single frame.
+
+    Unconditional: even a switch that keeps the ``pytype`` can change the
+    width, and a value decoded at the old one means nothing at the new. A
+    caller that still needs the bytes — the bulk edit writes a value in the
+    same pass — must capture them before calling.
+
+    The freeze is released with it. Leaving the box ticked with no target would
+    make the next poll tick adopt whatever the address happens to hold, pinning
+    a value the user never chose; a released box is visible and re-arming it is
+    one click.
+    """
+    entry.last_value = None
+    entry.frozen_value = None
+    entry.frozen = False
+
+
 def prompt_for_manual_entry(parent) -> Optional[CheatEntry]:
     """Sequential QInputDialog flow for the "Add Address Manually" button."""
     description, ok = QInputDialog.getText(
@@ -763,13 +862,16 @@ def prompt_for_manual_entry(parent) -> Optional[CheatEntry]:
         return None
     spec = find_spec(spec_label) or VALUE_TYPES[0]
 
+    # The AOB pattern spec declares a length of 0 (the scanner derives a match's
+    # width from the pattern), and an address added by hand has no pattern to
+    # measure — so ask for the width instead of minting a zero-byte buffer.
     length = spec.length
-    if spec.accepts_length_override:
+    if spec.accepts_length_override or not spec.length:
         length, ok = QInputDialog.getInt(
             parent,
             "Add address",
             "Buffer length (bytes):",
-            value=spec.length,
+            value=spec.length or 4,
             minValue=1,
             maxValue=1024,
         )

{pymemoryeditor-2.1.0 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/pointer_chain_dialog.py

@@ -47,7 +47,12 @@ from PySide6.QtWidgets import (
 from PyMemoryEditor import AbstractProcess
 
 from ._widgets import parse_hex_address, parse_offsets, resolve_base_address
-from .value_types import VALUE_TYPES, ValueTypeSpec, find_spec
+from .value_types import (
+    VALUE_TYPES,
+    ValueTypeSpec,
+    find_spec,
+    has_readable_width,
+)
 
 
 # Child of "PyMemoryEditor" — surfaced by the Log Console via propagation.
@@ -216,6 +221,13 @@ class PointerChainDialog(QDialog):
 
         self._value_type_combo = QComboBox()
         for spec in VALUE_TYPES:
+            # The address is already known here, so the only spec that can't be
+            # offered is the one with no width of its own — an IDA pattern,
+            # which would read zero bytes. A regex is welcome: its width comes
+            # from the Length field and it renders the bytes as text up to the
+            # first NUL, which "String (UTF-8)" doesn't do.
+            if not has_readable_width(spec):
+                continue
             self._value_type_combo.addItem(spec.label)
         form.addRow("Read value as:", self._value_type_combo)
 

{pymemoryeditor-2.1.0 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/pointer_scan_dialog.py

@@ -59,7 +59,12 @@ from ._widgets import (
     parse_hex_address,
     shutdown_worker_thread,
 )
-from .value_types import VALUE_TYPES, ValueTypeSpec, find_spec
+from .value_types import (
+    VALUE_TYPES,
+    ValueTypeSpec,
+    find_spec,
+    has_readable_width,
+)
 
 
 _LOG = logging.getLogger(__name__)
@@ -409,8 +414,13 @@ class PointerScanDialog(TearsDownOnClose, QDialog):
         # type into the cheat table on promotion.
         self._value_type_combo = QComboBox()
         for spec in VALUE_TYPES:
-            if spec.is_pattern:
-                continue  # reading a value "as a pattern" is meaningless here
+            # The address is already known here, so the only spec that can't be
+            # offered is the one with no width of its own — an IDA pattern,
+            # which would read zero bytes. A regex is welcome: its width comes
+            # from the Length field and it renders the bytes as text up to the
+            # first NUL, which "String (UTF-8)" doesn't do.
+            if not has_readable_width(spec):
+                continue
             self._value_type_combo.addItem(spec.label)
         self._value_type_combo.currentTextChanged.connect(self._on_value_type_changed)
         form.addRow("Read value as:", self._value_type_combo)

{pymemoryeditor-2.1.0 → pymemoryeditor-2.2.0}/PyMemoryEditor/app/scan_worker.py

@@ -22,7 +22,12 @@ from PySide6.QtCore import QThread, Signal
 
 from PyMemoryEditor import AbstractProcess, MemoryRegion, ScanTypesEnum
 
-from .scan_types import NextScanType, NO_VALUE_SCAN_TYPES, ScanType
+from .scan_types import (
+    DELTA_SCAN_TYPES,
+    NextScanType,
+    NO_VALUE_SCAN_TYPES,
+    ScanType,
+)
 from .value_types import parse_value, ValueTypeSpec
 
 
@@ -85,6 +90,7 @@ def build_scan_request(
     value_text: str,
     second_value_text: str = "",
     length_spin_value: Optional[int] = None,
+    previous_scan_length: Optional[int] = None,
     writeable_only: bool = False,
     with_value: bool = True,
 ) -> ScanRequest:
@@ -93,11 +99,19 @@ def build_scan_request(
 
     This is the pure core of ``ScannerPanel._build_request`` lifted out of the
     widget so the request-assembly rules (pattern short-circuit, the
-    str-ignores-length override, range parsing, the no-value scan types) can be
-    unit-tested without a ``QApplication``. The widget keeps only the bits that
-    are genuinely UI: reading the fields and showing a ``QMessageBox`` on the
-    ``ValueError`` raised here.
-
+    value-derived width for str / bytes, range parsing, the no-value scan types)
+    can be unit-tested without a ``QApplication``. The widget keeps only the
+    bits that are genuinely UI: reading the fields and showing a ``QMessageBox``
+    on the ``ValueError`` raised here.
+
+    :param length_spin_value: the Length field. Only the regex type reads it
+        (as ``byte_length``) — every other type derives its width from the spec
+        or from the value itself.
+    :param previous_scan_length: the width the scan that produced the current
+        results used. Only the no-value comparisons read it, and only for the
+        variable-width types, whose baseline is meaningless at another width.
+        (The ``*_BY`` deltas compare against the baseline too, but they are
+        rejected outright for those types — see below.)
     :raises ValueError: if a value/pattern fails to parse (message is
         user-facing — the caller picks the dialog title from ``spec.is_pattern``).
     """
@@ -116,19 +130,35 @@ def build_scan_request(
             writeable_only=writeable_only,
         )
 
-    # String (UTF-8) ignores the length field: pass None so parse_value derives
-    # the buffer width from the typed text's UTF-8 byte length. Byte Array still
-    # honours the user-set override.
-    length_override = (
-        length_spin_value
-        if spec.accepts_length_override and spec.pytype is not str
-        else None
-    )
+    # "Increased/Decreased value BY" adds the delta to the baseline, which only
+    # means anything for a number: on str/bytes ``prev + exp`` concatenates (so
+    # the comparison is never true) and ``prev - exp`` raises TypeError, which
+    # the refine worker swallows into "doesn't match". Either way every address
+    # is dropped and the user is told nothing, so reject the combination with a
+    # message instead. Checked *after* the pattern short-circuit above: the
+    # pattern specs are bytes-typed too, but they force EXACT regardless of the
+    # scan type passed, and the comparisons this message points at are disabled
+    # in pattern mode anyway.
+    if scan_type in DELTA_SCAN_TYPES and spec.pytype in (str, bytes):
+        raise ValueError(
+            "Increased/Decreased Value By adds a numeric amount to the previous "
+            "value, which doesn't apply to %s. Use Changed Value or Unchanged "
+            "Value to compare against the previous scan." % spec.label
+        )
 
-    # Increased/Decreased/Changed/Unchanged compare current vs previous and need
-    # no target value — just the value shape (type + length).
+    # Increased/Decreased/Changed/Unchanged compare the value read now against
+    # the one the *previous* scan recorded, so they need no target value — but
+    # they must re-read at the width that baseline was recorded with. Reading
+    # 16 bytes where the first scan recorded 4 yields "olá\0\0…" against "olá",
+    # which never compares equal, so every address would report as Changed.
+    # ``previous_scan_length`` carries that width for the variable-width types;
+    # the fixed-width types own theirs and ignore it.
     if scan_type in NO_VALUE_SCAN_TYPES:
-        length = length_override if length_override is not None else spec.length
+        length = (
+            previous_scan_length
+            if spec.accepts_length_override and previous_scan_length
+            else spec.length
+        )
         return ScanRequest(
             spec=spec,
             length=int(length),
@@ -137,14 +167,22 @@ def build_scan_request(
             writeable_only=writeable_only,
         )
 
+    # Every scan that carries a value sizes its buffer from that value: the
+    # numeric types have a fixed width, and str / bytes derive theirs in
+    # parse_value (the text's UTF-8 byte length / the number of hex bytes
+    # entered). So no length override is passed here. Letting the Length field
+    # win could only break the scan — a width below the value's raises
+    # "byte string too long" from the fixed-width ctypes buffer, and a width
+    # above it NUL-pads the target, silently searching for "the value followed
+    # by zeros". Partial matching has its own value type (AOB Pattern).
     value: Any
     if scan_type in (ScanTypesEnum.VALUE_BETWEEN, ScanTypesEnum.NOT_VALUE_BETWEEN):
-        lo, lo_len = parse_value(spec, value_text, length_override)
-        hi, hi_len = parse_value(spec, second_value_text, length_override)
+        lo, lo_len = parse_value(spec, value_text)
+        hi, hi_len = parse_value(spec, second_value_text)
         length = max(lo_len, hi_len)
         value = (lo, hi)
     else:
-        value, length = parse_value(spec, value_text, length_override)
+        value, length = parse_value(spec, value_text)
 
     if not with_value:
         value = None  # Used by callers that only need spec/length/scan_type.