PyMemoryEditor 2.2.0__tar.gz → 2.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: PyMemoryEditor
-Version: 2.2.0
+Version: 2.2.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
@@ -71,18 +71,19 @@ A pure-Python library (built on [ctypes](https://docs.python.org/3/library/ctype
   <i>One unified API. Three operating systems. No C compiler. No native build step.</i>
 </p>
 
-<p align="center">
-  Runs on <b>🪟 Windows</b> · <b>🐧 Linux</b> · <b>🍎 macOS</b> — 32-bit and 64-bit.
-</p>
-
 <p align="center">
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml"><img src="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml/badge.svg" alt="Python Package" /></a>
+  <a href="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor"><img src="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor/branch/main/graph/badge.svg" alt="Coverage" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://img.shields.io/pypi/v/PyMemoryEditor" alt="Pypi" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/pypi/l/PyMemoryEditor" alt="License" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/badge/python-3.10+-8A2BE2" alt="Python Version" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://static.pepy.tech/personalized-badge/pymemoryeditor?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads" alt="Downloads" /></a>
 </p>
 
+<p align="center">
+  Runs on <b>Windows</b> · <b>Linux</b> · <b>macOS</b> — 32-bit and 64-bit.
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/JeanExtreme002/PyMemoryEditor/main/assets/screenshots/app.png" alt="PyMemoryEditor app attached to a running process" width="820" />
 </p>

{pymemoryeditor-2.2.0 → pymemoryeditor-2.2.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__ = "2.2.0"
+__version__ = "2.2.1"
 
 import logging
 import sys

{pymemoryeditor-2.2.0 → pymemoryeditor-2.2.1}/PyMemoryEditor/macos/functions.py

@@ -311,6 +311,31 @@ _PAGE_GONE_KRS = (
     KERN_MEMORY_ERROR,
 )
 
+# KERN_PROTECTION_FAILURE is tolerated by a full-address-space *sweep* only,
+# never by a read of caller-supplied addresses — hence a second tuple rather
+# than another entry above.
+#
+# The sweeps walk every region the filter accepted and have no opinion about
+# any single one: a range the kernel declines to hand over is a range with no
+# matches in it, and aborting the whole scan over it loses every region that
+# came after. `search_values_by_addresses` is the opposite case — the caller
+# named those addresses, and its documented `raise_error=True` must still be
+# able to report that one of them could not be read. Anything in the tuple
+# above is swallowed even when `raise_error` is set (see
+# process.scanning.iter_values_for_addresses), so putting kr=2 there would
+# silently turn "permission denied" into the same `(address, None)` the caller
+# gets for an address in a gap.
+#
+# Honest limits of what is known here. This was added because a plain
+# search_by_value over the current process died with kr=2 on GitHub's
+# virtualized macOS runners, on a 22 MB region that reported VM_PROT_READ and
+# Shared=False. The mechanism was not established. It does *not* reproduce
+# locally: probing all 135 scannable regions of a live process yields only kr=1
+# and kr=10, and a page deliberately re-protected to PROT_NONE (or never
+# mapped) answers KERN_INVALID_ADDRESS, not kr=2 — so the usual
+# "protection changed under us" story does not explain it.
+_SWEEP_SKIPPABLE_KRS = _PAGE_GONE_KRS + (KERN_PROTECTION_FAILURE,)
+
 
 class MachReadError(OSError):
     """OSError subclass that carries the underlying kern_return_t."""
@@ -494,6 +519,14 @@ def _is_transient(exc: BaseException) -> bool:
     return isinstance(exc, MachReadError) and exc.kr in _PAGE_GONE_KRS
 
 
+def _is_skippable_by_sweep(exc: BaseException) -> bool:
+    """
+    Same as :func:`_is_transient`, plus the codes only a full-address-space
+    sweep may skip. See :data:`_SWEEP_SKIPPABLE_KRS`.
+    """
+    return isinstance(exc, MachReadError) and exc.kr in _SWEEP_SKIPPABLE_KRS
+
+
 def _query_region(task: int, address: int):
     """Return the region containing `address`, or None when the query fails."""
     addr = mach_vm_address_t(address)
@@ -683,7 +716,7 @@ def search_addresses_by_value(
         scan_type,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 
@@ -1044,7 +1077,7 @@ def search_addresses_by_pattern(
         length,
         _make_read_chunk(task),
         progress_information=progress_information,
-        transient_error_check=_is_transient,
+        transient_error_check=_is_skippable_by_sweep,
     )
 
 

{pymemoryeditor-2.2.0 → pymemoryeditor-2.2.1}/README.md

@@ -13,18 +13,19 @@ A pure-Python library (built on [ctypes](https://docs.python.org/3/library/ctype
   <i>One unified API. Three operating systems. No C compiler. No native build step.</i>
 </p>
 
-<p align="center">
-  Runs on <b>🪟 Windows</b> · <b>🐧 Linux</b> · <b>🍎 macOS</b> — 32-bit and 64-bit.
-</p>
-
 <p align="center">
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml"><img src="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml/badge.svg" alt="Python Package" /></a>
+  <a href="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor"><img src="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor/branch/main/graph/badge.svg" alt="Coverage" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://img.shields.io/pypi/v/PyMemoryEditor" alt="Pypi" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/pypi/l/PyMemoryEditor" alt="License" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/badge/python-3.10+-8A2BE2" alt="Python Version" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://static.pepy.tech/personalized-badge/pymemoryeditor?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads" alt="Downloads" /></a>
 </p>
 
+<p align="center">
+  Runs on <b>Windows</b> · <b>Linux</b> · <b>macOS</b> — 32-bit and 64-bit.
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/JeanExtreme002/PyMemoryEditor/main/assets/screenshots/app.png" alt="PyMemoryEditor app attached to a running process" width="820" />
 </p>

{pymemoryeditor-2.2.0 → pymemoryeditor-2.2.1}/docs/index.md

@@ -15,6 +15,7 @@
 
 <p align="center">
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml"><img src="https://github.com/JeanExtreme002/PyMemoryEditor/actions/workflows/python-package.yml/badge.svg" alt="Python Package" /></a>
+  <a href="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor"><img src="https://codecov.io/gh/JeanExtreme002/PyMemoryEditor/branch/main/graph/badge.svg" alt="Coverage" /></a>
   <a href="https://pypi.org/project/PyMemoryEditor/"><img src="https://img.shields.io/pypi/v/PyMemoryEditor" alt="Pypi" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/pypi/l/PyMemoryEditor" alt="License" /></a>
   <a href="https://github.com/JeanExtreme002/PyMemoryEditor"><img src="https://img.shields.io/badge/python-3.10+-8A2BE2" alt="Python Version" /></a>

{pymemoryeditor-2.2.0 → pymemoryeditor-2.2.1}/tests/platforms/test_macos_transient_reads.py

@@ -25,6 +25,7 @@ if sys.platform != "darwin":
 from PyMemoryEditor.macos.functions import (  # noqa: E402
     MachPartialReadError,
     MachReadError,
+    _is_skippable_by_sweep,
     _is_transient,
 )
 from PyMemoryEditor.macos.types import (  # noqa: E402
@@ -59,6 +60,12 @@ def test_a_vanished_page_lets_the_scan_continue(kr):
 # KERN_MEMORY_FAILURE directly above KERN_MEMORY_ERROR and documents it as
 # permanent, which is exactly the distinction being drawn here; KERN_FAILURE is
 # what task_for_pid returns without the debugger entitlement.
+#
+# KERN_PROTECTION_FAILURE stays here even though a *sweep* skips it (see
+# test_a_sweep_may_skip_a_protected_range below): this classifier also drives
+# search_values_by_addresses, whose caller named the addresses and whose
+# documented raise_error=True must still be able to report one it could not
+# read.
 @pytest.mark.parametrize(
     "kr", (KERN_FAILURE, KERN_PROTECTION_FAILURE, KERN_MEMORY_FAILURE)
 )
@@ -79,3 +86,35 @@ def test_a_short_read_lets_the_scan_continue():
 def test_a_non_mach_error_is_never_transient():
     assert not _is_transient(OSError("some unrelated failure"))
     assert not _is_transient(ValueError("not an OSError at all"))
+
+
+# A full-address-space sweep is the one caller allowed to skip a range the
+# kernel refuses to hand over. It has no opinion about any single region, and
+# aborting on one loses every region that came after it — which is how a plain
+# search_by_value died on a virtualized macOS CI runner.
+@pytest.mark.parametrize(
+    "kr",
+    (
+        KERN_INVALID_ADDRESS,
+        KERN_INVALID_ARGUMENT,
+        KERN_NO_ACCESS,
+        KERN_MEMORY_ERROR,
+        KERN_PROTECTION_FAILURE,
+    ),
+)
+def test_a_sweep_may_skip_a_protected_range(kr):
+    assert _is_skippable_by_sweep(MachReadError(kr, "read failed (kr=%d)" % kr))
+
+
+# The sweep is more tolerant, not unconditionally tolerant: a task-level
+# failure still has to stop it.
+@pytest.mark.parametrize("kr", (KERN_FAILURE, KERN_MEMORY_FAILURE))
+def test_a_sweep_still_stops_on_a_task_level_failure(kr):
+    assert not _is_skippable_by_sweep(MachReadError(kr, "read failed (kr=%d)" % kr))
+
+
+def test_only_the_sweep_skips_a_protected_range():
+    """The two classifiers must disagree on exactly one code, and this is it."""
+    exc = MachReadError(KERN_PROTECTION_FAILURE, "read failed")
+    assert _is_skippable_by_sweep(exc)
+    assert not _is_transient(exc)