feat: add read_process_memory_into for zero-copy buffer reuse (#71)

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or

PyMemoryEditor/linux/functions.py

@@ -30,6 +30,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -378,6 +379,18 @@ def read_process_memory(pid: int, address: int, pytype: Type[T], bufflength: int
  return data.value
 
 
+def read_process_memory_into(pid: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``_LinuxPartialIOError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _process_vm_readv(pid, addressof(c_buffer), address, size)
+
+
 def search_addresses_by_value(
  pid: int,
  pytype: Type[T],

PyMemoryEditor/linux/process.py

@@ -21,6 +21,7 @@
  get_modules,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  search_addresses_by_pattern,
  search_addresses_by_value,
  search_values_by_addresses,
@@ -117,6 +118,10 @@ def read_process_memory(
  self.pid, address, pytype, resolve_bufflength(pytype, bufflength)
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ return read_process_memory_into(self.pid, address, buffer)
+
  def search_by_addresses(
  self,
  pytype: Type[T],

PyMemoryEditor/macos/functions.py

@@ -28,6 +28,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -545,6 +546,18 @@ def read_process_memory(
  return data.value
 
 
+def read_process_memory_into(task: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read (always the buffer's byte length on success; a short read raises
+ ``MachPartialReadError``).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ return _mach_read(task, address, ctypes.addressof(c_buffer), size)
+
+
 def write_process_memory(
  task: int,
  address: int,

PyMemoryEditor/macos/process.py

@@ -25,6 +25,7 @@
  get_task_for_pid,
  get_threads,
  read_process_memory,
+ read_process_memory_into,
  release_task,
  search_addresses_by_pattern,
  search_addresses_by_value,
@@ -292,6 +293,10 @@ def 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()
+ return read_process_memory_into(self.__task, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

PyMemoryEditor/process/abstract.py

@@ -449,6 +449,49 @@ def read_process_memory(
  """
  raise NotImplementedError()
 
+ @abstractmethod
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` and return the number of bytes read.
+
+ This is the zero-copy counterpart of :meth:`read_process_memory`: where
+ that method allocates a fresh object on every call, this one fills a
+ buffer you own and reuse. In a tight polling / recording loop that reads
+ the same-sized region over and over, reusing one buffer keeps memory use
+ constant instead of producing a stream of short-lived objects for the
+ garbage collector to reclaim.
+
+ :param address: target memory address (ex: 0x006A9EC0).
+ :param buffer: any writable, contiguous buffer-protocol object — a
+ ``bytearray``, a ``ctypes`` array, a writable ``memoryview``, a
+ ``numpy`` array, etc. Its byte length determines how many bytes are
+ read; an element-typed buffer (e.g. a ``numpy`` ``int32`` array) is
+ sized in **bytes**, not elements. The bytes are written in place; no
+ decoding is performed (this is the raw-``bytes`` read path). Decode
+ or reinterpret them yourself afterwards
+ (``int.from_bytes`` / ``struct.unpack`` / ``numpy`` views / ...).
+ :return: the number of bytes read — always equal to the buffer's byte
+ length on success (a short read raises instead, mirroring
+ :meth:`read_process_memory`).
+
+ :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 OSError: if the read fails, or returns fewer bytes than
+ requested (e.g. the range crosses an unreadable/freed page).
+
+ Example
+ -------
+ ::
+
+ buffer = bytearray(16)
+ while recording:
+ process.read_process_memory_into(addr, buffer)
+ handle(buffer) # same buffer reused every iteration
+ """
+ raise NotImplementedError()
+
  @abstractmethod
  def write_process_memory(
  self,

PyMemoryEditor/util/__init__.py

@@ -4,6 +4,7 @@
  UNSET,
  _check_int_fits,
  _validate_pytype,
+ as_writable_c_buffer,
  convert_from_byte_array,
  get_c_type_of,
  prepare_write,

PyMemoryEditor/util/convert.py

@@ -209,6 +209,54 @@ def prepare_write(
  return pytype, length, value
 
 
+def as_writable_c_buffer(buffer: Any) -> "ctypes.Array":
+ """
+ Wrap a writable buffer-protocol object as a ``ctypes`` ``c_char`` array
+ that shares the same underlying storage, so a backend can read process
+ memory *directly into the caller's buffer* with no intermediate
+ allocation. Returning the ``ctypes`` array (rather than a bare address)
+ keeps a reference to the source alive for as long as the caller holds it,
+ which is what makes the address safe to pass to the OS read call.
+
+ Accepts anything exposing a writable, contiguous buffer — ``bytearray``,
+ a ``ctypes`` array, a writable ``memoryview``, a ``numpy`` array, etc. The
+ array's byte length is taken from the buffer itself (``memoryview.nbytes``),
+ so element-typed buffers like a ``numpy`` ``int32`` array are sized in
+ bytes, not elements.
+
+ :raises TypeError: if ``buffer`` does not support the buffer protocol or is
+ read-only (e.g. ``bytes`` — use ``bytearray`` instead).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ """
+ try:
+ view = memoryview(buffer)
+ except TypeError:
+ raise TypeError(
+ "buffer must support the writable buffer protocol "
+ "(e.g. bytearray, a ctypes array, or a numpy array), got %s."
+ % type(buffer).__name__
+ )
+
+ try:
+ if view.readonly:
+ raise TypeError(
+ "buffer must be writable; got a read-only buffer "
+ "(e.g. bytes). Use bytearray or another writable buffer."
+ )
+ if not view.contiguous:
+ raise ValueError("buffer must be contiguous.")
+ nbytes = view.nbytes
+ finally:
+ # Release the inspection view promptly so it never lingers as an extra
+ # export on the source object (e.g. blocking a later bytearray resize).
+ view.release()
+
+ if nbytes == 0:
+ raise ValueError("buffer must have a non-zero length.")
+
+ return (ctypes.c_char * nbytes).from_buffer(buffer)
+
+
 def convert_from_byte_array(
  byte_array: ctypes.Array, pytype: Type[T], length: int
 ) -> T:

PyMemoryEditor/win32/functions.py

@@ -27,6 +27,7 @@
 from ..process.thread_info import ThreadInfo
 from ..util import (
  _validate_pytype,
+ as_writable_c_buffer,
  get_c_type_of,
  values_to_bytes,
 )
@@ -501,6 +502,40 @@ def ReadProcessMemory(
  return data.value
 
 
+def ReadProcessMemoryInto(process_handle: int, address: int, buffer) -> int:
+ """
+ Read ``len(buffer)`` bytes from ``address`` directly into the writable
+ ``buffer``, with no intermediate allocation. Returns the number of bytes
+ read.
+
+ Raises OSError if the read fails or returns fewer bytes than requested
+ (same partial-read guard as :func:`ReadProcessMemory`).
+ """
+ c_buffer = as_writable_c_buffer(buffer)
+ size = len(c_buffer)
+ bytes_read = ctypes.c_size_t(0)
+
+ ctypes.set_last_error(0)
+ success = kernel32.ReadProcessMemory(
+ process_handle,
+ ctypes.c_void_p(address),
+ ctypes.byref(c_buffer),
+ size,
+ ctypes.byref(bytes_read),
+ )
+
+ if not success:
+ _raise_last_error("ReadProcessMemory")
+
+ if bytes_read.value != size:
+ raise OSError(
+ "ReadProcessMemory partial read at 0x%X: %d of %d bytes read."
+ % (address, bytes_read.value, size)
+ )
+
+ return bytes_read.value
+
+
 def _read_region(process_handle: int, address: int, size: int):
  """Read a memory region; returns the byte buffer or None on failure."""
  region_data = (ctypes.c_byte * size)()

PyMemoryEditor/win32/process.py

@@ -27,6 +27,7 @@
  GetProcessHandle,
  GetThreads,
  ReadProcessMemory,
+ ReadProcessMemoryInto,
  SearchAddressesByPattern,
  SearchAddressesByValue,
  SearchValuesByAddresses,
@@ -313,6 +314,11 @@ def read_process_memory(
  resolve_bufflength(pytype, bufflength),
  )
 
+ def read_process_memory_into(self, address: int, buffer: object) -> int:
+ self.__require_open()
+ self.__require_read()
+ return ReadProcessMemoryInto(self.__process_handle, address, buffer)
+
  def write_process_memory(
  self,
  address: int,

docs/api/openprocess.md

@@ -158,6 +158,23 @@ with OpenProcess(
  :returns: the original ``value`` you passed in — **not** the truncated/encoded
  form actually written (a capped ``str``/``bytes`` write returns the full
  original value).
+
+.. py:method:: read_process_memory_into(address, buffer)
+
+ Read ``len(buffer)`` raw bytes from ``address`` directly into a
+ pre-allocated, writable ``buffer`` (no intermediate allocation) — the
+ zero-copy counterpart of :py:meth:`read_process_memory` for tight
+ read-the-same-region loops. See :doc:`../guide/read-write` for examples.
+
+ :param int address: target memory address.
+ :param buffer: any writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes land
+ verbatim (no decoding).
+ :returns: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
 ```
 
 ### Typed shortcuts

docs/guide/read-write.md

@@ -195,6 +195,60 @@ Need the raw bytes with zero interpretation? Use `read_bytes(address, length)`
 and `write_bytes(address, data)`.
 ```
 
+## Reusing a buffer (zero-copy reads)
+
+Every `read_process_memory` call **allocates a fresh Python object** for the
+result. That's fine for one-off reads, but in a tight loop that reads the same
+region thousands of times — a recorder, a live overlay, a poller — those
+throwaway objects pile up and keep the garbage collector busy.
+
+`read_process_memory_into(address, buffer)` reads straight into a buffer **you
+own and reuse**, so a long-running loop runs with constant memory instead of a
+steady stream of allocations:
+
+```python
+buffer = bytearray(16) # allocate once
+
+with OpenProcess(name="game.exe") as process:
+ while recording:
+ process.read_process_memory_into(0x7FF40010, buffer)
+ handle(buffer) # same buffer, refilled in place every loop
+```
+
+It fills **`len(buffer)` bytes** (the buffer's size decides how much is read)
+and returns the number of bytes read. The bytes land verbatim — no decoding —
+so reinterpret them yourself with `int.from_bytes`, `struct.unpack`, a `numpy`
+view, and so on.
+
+Any writable, contiguous buffer works — a `bytearray`, a `ctypes` array, a
+writable `memoryview`, or a `numpy` array (sized in **bytes**, so a 4-element
+`int32` array reads 16 bytes):
+
+```python
+import numpy as np
+
+frame = np.zeros(4, dtype=np.int32) # 16 bytes
+process.read_process_memory_into(0x7FF40010, frame)
+# frame now holds the four int32 values, no per-read allocation
+```
+
+### Method signature
+
+```{eval-rst}
+.. py:method:: read_process_memory_into(address, buffer)
+ :no-index:
+
+ :param int address: target memory address.
+ :param buffer: a writable, contiguous buffer-protocol object
+ (``bytearray``, ``ctypes`` array, writable ``memoryview``, ``numpy``
+ array, …). Its byte length sets how many bytes are read; the bytes are
+ written in place with no decoding.
+ :return: the number of bytes read (the buffer's byte length on success).
+ :raises TypeError: if ``buffer`` is not a writable buffer (e.g. ``bytes``).
+ :raises ValueError: if ``buffer`` is empty or not contiguous.
+ :raises OSError: if the read fails or returns fewer bytes than requested.
+```
+
 ## Common errors
 
 - **`OSError`** — the address may have been freed between scan and write, or