PyMemoryEditor 3.3.3__tar.gz → 3.4.1__tar.gz

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: PyMemoryEditor
-Version: 3.3.3
+Version: 3.4.1
 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
@@ -38,7 +38,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Provides-Extra: app
 Requires-Dist: psutil<8,>=5.9; extra == 'app'
-Requires-Dist: pyside6<7,>=6.5; extra == 'app'
+Requires-Dist: pyside6<6.12,>=6.5; (python_version < '3.12') and extra == 'app'
+Requires-Dist: pyside6<7,>=6.5; (python_version >= '3.12') and extra == 'app'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: flake8; extra == 'dev'
@@ -46,7 +47,8 @@ Requires-Dist: hypothesis; extra == 'dev'
 Requires-Dist: mcp<3,>=2; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: psutil<8,>=5.9; extra == 'dev'
-Requires-Dist: pyside6<7,>=6.5; extra == 'dev'
+Requires-Dist: pyside6<6.12,>=6.5; (python_version < '3.12') and extra == 'dev'
+Requires-Dist: pyside6<7,>=6.5; (python_version >= '3.12') and extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-qt; extra == 'dev'
@@ -60,7 +62,8 @@ Provides-Extra: tests
 Requires-Dist: hypothesis; extra == 'tests'
 Requires-Dist: mcp<3,>=2; extra == 'tests'
 Requires-Dist: psutil<8,>=5.9; extra == 'tests'
-Requires-Dist: pyside6<7,>=6.5; extra == 'tests'
+Requires-Dist: pyside6<6.12,>=6.5; (python_version < '3.12') and extra == 'tests'
+Requires-Dist: pyside6<7,>=6.5; (python_version >= '3.12') and extra == 'tests'
 Requires-Dist: pytest; extra == 'tests'
 Requires-Dist: pytest-cov; extra == 'tests'
 Requires-Dist: pytest-qt; extra == 'tests'

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/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__ = "3.3.3"
+__version__ = "3.4.1"
 
 import logging
 import sys

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PyMemoryEditor/linux/process.py

@@ -196,12 +196,14 @@ class LinuxProcess(AbstractProcess):
         bufflength: Optional[int] = None,
     ) -> T:
         self.__require_target(hot_path=True)
+        self._require_address(address)
         return read_process_memory(
             self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
         )
 
     def read_process_memory_into(self, address: int, buffer: object) -> int:
         self.__require_target(hot_path=True)
+        self._require_address(address)
         return read_process_memory_into(self.pid, address, buffer)
 
     def _scan_addresses(
@@ -270,6 +272,7 @@ class LinuxProcess(AbstractProcess):
         value: Union[bool, int, float, str, bytes] = UNSET,
     ) -> Union[bool, int, float, str, bytes]:
         self.__require_target()
+        self._require_address(address)
         w_pytype, w_length, w_value = prepare_write(pytype, bufflength, value)
         write_process_memory(self.pid, address, w_pytype, w_length, w_value)
         return value

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PyMemoryEditor/macos/process.py

@@ -255,12 +255,14 @@ class MacProcess(AbstractProcess):
         bufflength: Optional[int] = None,
     ) -> T:
         self._require_open()
+        self._require_address(address)
         return read_process_memory(
             self.__task, address, pytype, resolve_bufflength(pytype, bufflength)
         )
 
     def read_process_memory_into(self, address: int, buffer: object) -> int:
         self._require_open()
+        self._require_address(address)
         return read_process_memory_into(self.__task, address, buffer)
 
     def write_process_memory(
@@ -296,6 +298,7 @@ class MacProcess(AbstractProcess):
         :param value: value to be written.
         """
         self._require_open()
+        self._require_address(address)
         w_pytype, w_length, w_value = prepare_write(pytype, bufflength, value)
         write_process_memory(self.__task, address, w_pytype, w_length, w_value)
         return value
@@ -308,6 +311,7 @@ class MacProcess(AbstractProcess):
 
     def free_memory(self, address: int, size: int = 0) -> bool:
         self._require_open()
+        self._require_address(address)
         # mach_vm_deallocate needs the exact size. Reuse the tracked size when
         # the caller doesn't supply one.
         actual_size = size or self.__allocations.get(address, 0)

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PyMemoryEditor/mcp/toolset.py

@@ -424,6 +424,10 @@ def _parse_signed_int(raw: Any, field: str) -> int:
     negative = text.startswith("-")
     body = text[1:] if negative else text
     try:
+        # int() accepts a sign of its own, so "--5" would strip to "-5" and
+        # the two minuses cancel: a write of "--5" stored +5. One sign only.
+        if negative and body.lstrip()[:1] in ("-", "+"):
+            raise ValueError(body)
         value = int(body, 16) if body[:2].lower() == "0x" else int(body, 10)
     except (ValueError, IndexError):
         raise ToolError(

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PyMemoryEditor/process/abstract.py

@@ -53,15 +53,22 @@ _POINTER_SCAN_FORMAT = "pymemoryeditor-pointerscan"
 _POINTER_SCAN_VERSION = 1
 
 
-class _PointerOutOfRangeError(ValueError, OSError):
-    """A pointer chain step landed outside the address space.
+class _AddressOutOfRangeError(ValueError, OSError):
+    """An address (or a pointer chain step) lies outside the address space.
 
     A ``ValueError`` as documented, and also an ``OSError`` because the failed
     read of the wrapped address it replaces raised one: callers that guard a
-    stale chain with ``except OSError`` keep working.
+    stale chain or a bad address with ``except OSError`` keep working.
     """
 
 
+# One past the highest address this host can pass to the OS. ctypes masks an
+# address argument to the width of the C type it is converted to instead of
+# rejecting it, so a 32-bit Python would turn 0x1_0000_1000 into 0x1000 just as
+# a 64-bit one turns 2**64 + 0x1000 into 0x1000.
+_HOST_ADDRESS_END = min(ADDRESS_SPACE_END, 1 << (8 * ctypes.sizeof(ctypes.c_void_p)))
+
+
 class AbstractProcess(ABC):
     """
     Abstract class to represent a process.
@@ -205,6 +212,23 @@ class AbstractProcess(ABC):
         if not self._target_alive():
             raise ProcessIDNotExistsError(self.pid)
 
+    @staticmethod
+    def _require_address(address: int) -> None:
+        """
+        Refuse an address outside ``[0, host address space)`` before it
+        reaches ctypes, which would mask it to the C type's width and read,
+        write or free a *different*, wrapped address instead of failing.
+        """
+        if not 0 <= address < _HOST_ADDRESS_END:
+            raise _AddressOutOfRangeError(
+                "address %s is outside the %d-bit address space; it would "
+                "wrap around to a different address."
+                % (
+                    ("-0x%X" % -address) if address < 0 else ("0x%X" % address),
+                    _HOST_ADDRESS_END.bit_length() - 1,
+                )
+            )
+
     @abstractmethod
     def _detect_is_64bit(self) -> Optional[bool]:
         """
@@ -736,7 +760,9 @@ class AbstractProcess(ABC):
            and ``convert_from_byte_array``. Callers that need the original
            bytes verbatim (no decoding) should pass ``pytype=bytes``.
 
-        :raises ValueError: if ``pytype`` is unsupported.
+        :raises ValueError: if ``pytype`` is unsupported, or ``address`` is
+            negative or past the end of the address space (also an
+            ``OSError``, so ``except OSError`` still catches it).
         :raises OSError: if the read fails, or returns fewer bytes than
             requested (e.g. the range crosses an unreadable/freed page).
         """
@@ -770,7 +796,9 @@ class AbstractProcess(ABC):
 
         :raises TypeError: if ``buffer`` is not a writable buffer (e.g. an
             immutable ``bytes`` object).
-        :raises ValueError: if ``buffer`` is empty or not contiguous.
+        :raises ValueError: if ``buffer`` is empty or not contiguous, or
+            ``address`` is outside the address space (as in
+            :meth:`read_process_memory`).
         :raises OSError: if the read fails, or returns fewer bytes than
             requested (e.g. the range crosses an unreadable/freed page).
 
@@ -821,7 +849,8 @@ class AbstractProcess(ABC):
             (``write_process_memory(address, int, 4, 99)``).
         :raises ValueError: if ``pytype`` is unsupported, or if an ``int``
             ``value`` does not fit in ``bufflength`` bytes (rejected up front
-            rather than silently truncated).
+            rather than silently truncated), or if ``address`` is outside the
+            address space (as in :meth:`read_process_memory`).
         :raises OSError: if the write fails, or fewer bytes than requested are
             written (e.g. the range crosses an unwritable/freed page).
         :return: the original ``value`` passed in.
@@ -1080,7 +1109,8 @@ class AbstractProcess(ABC):
         :return: ``True`` on success.
 
         :raises ValueError: on macOS and Windows, for a region this object did
-            not allocate when no ``size`` is given.
+            not allocate when no ``size`` is given, or for an ``address``
+            outside the address space.
         :raises NotImplementedError: on Linux (see :meth:`allocate_memory`).
         """
         raise NotImplementedError()
@@ -1190,7 +1220,7 @@ class AbstractProcess(ABC):
             # it, so `ptr + offset` below zero or past 2**64 would silently
             # read a *different*, wrapped address. Refuse it by name instead.
             if not 0 <= addr < ADDRESS_SPACE_END:
-                raise _PointerOutOfRangeError(
+                raise _AddressOutOfRangeError(
                     "pointer chain step produced address %s, outside the "
                     "64-bit address space; the chain is stale (a hop read "
                     "NULL or garbage) or an offset is wrong."

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/PyMemoryEditor/win32/process.py

@@ -303,6 +303,7 @@ class WindowsProcess(AbstractProcess):
     ) -> T:
         self._require_open()
         self.__require_read()
+        self._require_address(address)
         return ReadProcessMemory(
             self.__process_handle,
             address,
@@ -313,6 +314,7 @@ class WindowsProcess(AbstractProcess):
     def read_process_memory_into(self, address: int, buffer: object) -> int:
         self._require_open()
         self.__require_read()
+        self._require_address(address)
         return ReadProcessMemoryInto(self.__process_handle, address, buffer)
 
     def write_process_memory(
@@ -324,6 +326,7 @@ class WindowsProcess(AbstractProcess):
     ) -> Union[bool, int, float, str, bytes]:
         self._require_open()
         self.__require_write()
+        self._require_address(address)
         w_pytype, w_length, w_value = prepare_write(pytype, bufflength, value)
         WriteProcessMemory(
             self.__process_handle,
@@ -344,6 +347,7 @@ class WindowsProcess(AbstractProcess):
     def free_memory(self, address: int, size: int = 0) -> bool:
         self._require_open()
         self.__require_operation()
+        self._require_address(address)
         # MEM_RELEASE tears down whatever VirtualAlloc'd block starts at
         # `address` -- a heap segment or a thread stack just as readily as one
         # of ours -- so an address this object did not allocate is refused

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/docs/conf.py

@@ -23,7 +23,7 @@ copyright = f"{datetime.now().year}, {author}"
 try:
     from PyMemoryEditor import __version__ as release
 except Exception:  # pragma: no cover - docs can build without the package installed
-    release = "3.3.3"
+    release = "3.4.1"
 
 version = ".".join(release.split(".")[:2])
 

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/pyproject.toml

@@ -87,8 +87,18 @@ tests = [
 # psutil 7 removed nothing the app uses (Process.name/create_time,
 # pid_exists, process_iter with pid/name/username, and the three exceptions);
 # the app suite passes on 7.2.2.
+#
+# PySide6 6.12.0 is excluded below Python 3.12: its Linux wheels drop a
+# reference to ``None`` on ordinary void Qt calls (upstream PYSIDE-3474), so
+# a long enough session -- a CI worker that has run the app suite -- aborts
+# with ``Fatal Python error: none_dealloc: deallocating None``. On 3.12+ the
+# singletons are immortal (PEP 683) and the leak is harmless, which is why
+# only the 3.10/3.11 cells of the matrix were exposed. The crash took the
+# xdist worker down, and the session then hung until the job's 20-minute
+# timeout. Lift the cap once a 6.12.x release passes the app suite on 3.11.
 app = [
-  "PySide6>=6.5,<7",
+  "PySide6>=6.5,<6.12; python_version < '3.12'",
+  "PySide6>=6.5,<7; python_version >= '3.12'",
   "psutil>=5.9,<8",
 ]
 # The Model Context Protocol server (PyMemoryEditor.mcp), which lets an AI

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/tests/mcp_server/test_parsing.py

@@ -158,6 +158,15 @@ class TestParseOffset:
         assert parse_offset(hex(MAX_OFFSET_MAGNITUDE)) == MAX_OFFSET_MAGNITUDE
         assert parse_offset(-MAX_OFFSET_MAGNITUDE) == -MAX_OFFSET_MAGNITUDE
 
+    @pytest.mark.parametrize("raw", ["--8", "-+8", "- -8"])
+    def test_a_doubled_sign_is_refused_not_cancelled(self, raw):
+        """``"--8"`` used to strip one minus and let ``int()`` read the other,
+        so the two cancelled and the hop walked forwards instead of back."""
+        from PyMemoryEditor.mcp.toolset import parse_offset
+
+        with pytest.raises(ToolError, match="Could not parse"):
+            parse_offset(raw)
+
 
 class TestNumericArgumentsReachTheModelAsToolError:
     """Only ``ToolError`` text reaches the model.
@@ -253,6 +262,17 @@ class TestParseValue:
         with pytest.raises(ToolError, match="hex"):
             parse_value(bytes, raw)
 
+    @pytest.mark.parametrize("raw", ["--5", "-+5", "- -5", "--0x5"])
+    def test_int_refuses_a_doubled_sign_instead_of_cancelling_it(self, raw):
+        """``"--5"`` parsed as +5, so a ``write_value`` of it stored the
+        opposite sign of what was sent. A typo must fail, not flip."""
+        with pytest.raises(ToolError, match="Could not parse"):
+            parse_value(int, raw)
+
+    @pytest.mark.parametrize("raw, expected", [("+5", 5), ("- 5", -5)])
+    def test_a_single_sign_still_parses(self, raw, expected):
+        assert parse_value(int, raw) == expected
+
     def test_int_rejects_junk_with_actionable_message(self):
         with pytest.raises(ToolError, match="0x"):
             parse_value(int, "one hundred")

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/tests/mcp_server/test_toolset.py

@@ -672,10 +672,10 @@ class TestPointers:
     ):
         # The library's range error is both a ValueError and an OSError; it
         # must read as a stale chain, not as a malformed argument.
-        from PyMemoryEditor.process.abstract import _PointerOutOfRangeError
+        from PyMemoryEditor.process.abstract import _AddressOutOfRangeError
 
         def resolve(*args, **kwargs):
-            raise _PointerOutOfRangeError("pointer chain step produced address -0x100")
+            raise _AddressOutOfRangeError("pointer chain step produced address -0x100")
 
         monkeypatch.setattr(fake_process, "resolve_pointer_chain", resolve)
         with pytest.raises(ToolError) as caught:

{pymemoryeditor-3.3.3 → pymemoryeditor-3.4.1}/tests/memory/test_write_safety.py

@@ -208,3 +208,65 @@ def test_write_to_unmapped_address_raises():
             process.write_int(0x1, 7)
     finally:
         process.close()
+
+
+# --------------------------------------------------------------------------- #
+# (3) an address outside the address space must raise, not wrap.
+#     ctypes masks an address argument to 64 bits (32 on a 32-bit Python), so
+#     ``2**64 + addr`` used to read and write ``addr`` itself, with no error.
+# --------------------------------------------------------------------------- #
+
+_ADDRESS_WIDTH = 8 * ctypes.sizeof(ctypes.c_void_p)
+
+
+def _wrapping_addresses(address):
+    """Addresses that ctypes would mask onto ``address``."""
+    return [address + (1 << _ADDRESS_WIDTH), address - (1 << _ADDRESS_WIDTH)]
+
+
+@pytest.fixture
+def own_process():
+    process = OpenProcess(pid=os.getpid())
+    try:
+        yield process
+    finally:
+        process.close()
+
+
+@pytest.mark.parametrize("which", [0, 1], ids=["past-the-end", "negative"])
+def test_write_to_a_wrapping_address_raises_and_leaves_memory_untouched(own_process, which):
+    target = ctypes.c_int32(1234)
+    wrapped = _wrapping_addresses(ctypes.addressof(target))[which]
+
+    with pytest.raises(ValueError, match="outside the %d-bit address space" % _ADDRESS_WIDTH):
+        own_process.write_process_memory(wrapped, int, 4, 4321)
+    with pytest.raises(ValueError, match="outside"):
+        own_process.write_int(wrapped, 4321)
+
+    assert target.value == 1234
+
+
+@pytest.mark.parametrize("which", [0, 1], ids=["past-the-end", "negative"])
+def test_read_of_a_wrapping_address_raises(own_process, which):
+    target = ctypes.c_int32(1234)
+    wrapped = _wrapping_addresses(ctypes.addressof(target))[which]
+
+    with pytest.raises(ValueError, match="outside"):
+        own_process.read_process_memory(wrapped, int, 4)
+    with pytest.raises(ValueError, match="outside"):
+        own_process.read_process_memory_into(wrapped, bytearray(4))
+
+
+def test_out_of_range_address_is_still_an_os_error(own_process):
+    """A negative address used to fail inside the OS read with ``OSError``;
+    callers guarding a bad address with ``except OSError`` must still catch it."""
+    with pytest.raises(OSError, match="outside"):
+        own_process.read_process_memory(-1, int, 4)
+
+
+def test_the_last_address_of_the_space_is_not_refused_by_the_range_check(own_process):
+    """The top address is in range: whatever happens there is the OS's call
+    (unmapped, so ``OSError``), not the range check's ``ValueError``."""
+    with pytest.raises(OSError) as error:
+        own_process.read_process_memory((1 << _ADDRESS_WIDTH) - 1, bytes, 1)
+    assert not isinstance(error.value, ValueError)