PyMemoryEditor 1.5.7__tar.gz → 1.5.9__tar.gz

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/.github/workflows/python-package.yml

@@ -34,7 +34,7 @@ jobs:
         pip install -r requirements.txt
     - name: Test with pytest
       run: |
-        pytest tests -v -s
+        pytest tests -v -s -x
     - name: Install package
       run: |
         pip install PyMemoryEditor

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: PyMemoryEditor
-Version: 1.5.7
-Summary: Multi-platform library developed with ctypes for reading, writing and searching process memory, in a simple and friendly way with Python 3. It supports Windows and Linux (32-bit and 64-bit).
+Version: 1.5.9
+Summary: Multi-platform library developed with ctypes for reading, writing and searching process memory, in a simple and friendly way with Python 3.
 Project-URL: Homepage, https://github.com/JeanExtreme002/PyMemoryEditor
 Author-email: Jean Loui Bernard Silva de Jesus <jeanextreme002@gmail.com>
 License-Expression: MIT
@@ -47,6 +47,9 @@ reading and writing values in the process memory.
 pip3 install PyMemoryEditor
 ```
 
+### Tkinter application sample:
+You can run a simple tkinter application to scan the memory of a process by typing `pymemoryeditor` at the CLI.
+
 # Basic Usage:
 Import `PyMemoryEditor` and open a process using the `OpenProcess` class, passing a window title, process name <br>
 or PID as an argument. You can use the context manager to do this.
@@ -103,14 +106,22 @@ All methods described above work even for strings, including the method `search_
 ## Progress information on searching:
 These methods has the `progress_information` parameter that returns a dictionary containing the search progress information.
 ```py
-for address, info process.search_by_value(..., progress_information = True):
+for address, info in process.search_by_value(..., progress_information = True):
     template = "Address: 0x{:<10X} | Progress: {:.1f}%"
     progress = info["progress"] * 100
     
     print(template.format(address, progress))
 ```
 
-# Getting memory regions:
+# Reading multiple addresses efficiently:
+If you have a large number of addresses where their values need to be read from memory, using the `search_by_addresses` method is much more efficient than reading the value of each address one by one.
+```py
+for address, value in process.search_by_addresses(int, 4, addresses_list):
+    print(f"Address", address, "holds the value", value)
+```
+The key advantage of this method is that it reads a memory page just once, obtaining the values of the addresses within the page. This approach reduces the frequency of system calls.
+
+## Getting memory regions:
 Use the method `get_memory_regions()` to get the base address, size and more information of all memory regions used by the process.
 
 ```py

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/PyMemoryEditor/__init__.py

@@ -8,7 +8,7 @@ The package supports Windows and Linux (32-bit and 64-bit).
 """
 
 __author__ = "Jean Loui Bernard Silva de Jesus"
-__version__ = "1.5.7"
+__version__ = "1.5.9"
 
 
 from .enums import ScanTypesEnum

pymemoryeditor-1.5.9/PyMemoryEditor/errors.py

@@ -0,0 +1,6 @@
+from .process.errors import ProcessIDNotExistsError, ProcessNotFoundError
+
+
+class ClosedProcess(Exception):
+    def __str__(self):
+        return "operation on closed process."

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/PyMemoryEditor/linux/functions.py

@@ -7,10 +7,10 @@
 # https://man7.org/linux/man-pages/man5/proc.5.html
 
 from ctypes import addressof, sizeof
-from typing import Generator, Tuple, Type, TypeVar, Union
+from typing import Dict, Generator, Optional, Sequence, Tuple, Type, TypeVar, Union
 
 from ..enums import ScanTypesEnum
-from ..util import get_c_type_of, scan_memory, scan_memory_for_exact_value
+from ..util import convert_from_bytearray, get_c_type_of, scan_memory, scan_memory_for_exact_value
 from .ptrace import libc
 from .types import MEMORY_BASIC_INFORMATION, iovec
 
@@ -67,10 +67,10 @@ def read_process_memory(
         pid, (iovec * 1)(iovec(addressof(data), sizeof(data))),
         1, (iovec * 1)(iovec(address, sizeof(data))), 1, 0
     )
-    return str(data.value) if pytype is str else data.value
+    return data.value.decode() if pytype is str else data.value
 
 
-def search_all_memory(
+def search_addresses_by_value(
     pid: int,
     pytype: Type[T],
     bufflength: int,
@@ -147,6 +147,70 @@ def search_all_memory(
         checked_memory_size += size
 
 
+def search_values_by_addresses(
+    pid: int,
+    pytype: Type[T],
+    bufflength: int,
+    addresses: Sequence[int],
+    *,
+    memory_regions: Optional[Sequence[Dict]] = None,
+    raise_error: bool = False,
+) -> Generator[Tuple[int, Optional[T]], None, None]:
+    """
+    Search the whole memory space, accessible to the process,
+    for the provided list of addresses, returning their values.
+    """
+    if pytype not in [bool, int, float, str, bytes]:
+        raise ValueError("The type must be bool, int, float, str or bytes.")
+
+    memory_regions = list(memory_regions) if memory_regions else list()
+    addresses = sorted(addresses)
+
+    # If no memory page has been given, get all readable memory pages.
+    if not memory_regions:
+        for region in get_memory_regions(pid):
+            if not b"r" in region["struct"].Privileges: continue
+            memory_regions.append(region)
+
+    memory_regions.sort(key=lambda region: region["address"])
+    address_index = 0
+
+    # Walk by each memory region.
+    for region in memory_regions:
+        if address_index >= len(addresses): continue
+
+        target_address = addresses[address_index]
+
+        # Check if the memory region contains the target address.
+        base_address, size = region["address"], region["size"]
+        if not (base_address <= target_address < base_address + size): continue
+
+        region_data = (ctypes.c_byte * size)()
+
+        # Get data from the region.
+        libc.process_vm_readv(
+            pid, (iovec * 1)(iovec(addressof(region_data), sizeof(region_data))),
+            1, (iovec * 1)(iovec(base_address, sizeof(region_data))), 1, 0
+        )
+
+        # Get the value of each address.
+        while base_address <= target_address < base_address + size:
+            offset = target_address - base_address
+            address_index += 1
+
+            try:
+                data = region_data[offset: offset + bufflength]
+                data = (ctypes.c_byte * bufflength)(*data)
+                yield target_address, convert_from_bytearray(data, pytype, bufflength)
+
+            except Exception as error:
+                if raise_error: raise error
+                yield target_address, None
+
+            if address_index >= len(addresses): break
+            target_address = addresses[address_index]
+
+
 def write_process_memory(
     pid: int,
     address: int,

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/PyMemoryEditor/linux/process.py

@@ -3,8 +3,14 @@
 from ..enums import ScanTypesEnum
 from ..errors import ClosedProcess
 from ..process import AbstractProcess
-from .functions import get_memory_regions, read_process_memory, search_all_memory, write_process_memory
-from typing import Generator, Optional, Tuple, Type, TypeVar, Union
+from .functions import (
+    get_memory_regions,
+    read_process_memory,
+    search_addresses_by_value,
+    search_values_by_addresses,
+    write_process_memory
+)
+from typing import Generator, Optional, Sequence, Tuple, Type, TypeVar, Union
 
 
 T = TypeVar("T")
@@ -68,6 +74,21 @@ class LinuxProcess(AbstractProcess):
 
         return read_process_memory(self.pid, address, pytype, bufflength)
 
+    def search_by_addresses(
+        self,
+        pytype: Type[T],
+        bufflength: int,
+        addresses: Sequence[int],
+        *,
+        raise_error: bool = False,
+    ) -> Generator[Tuple[int, Optional[T]], None, None]:
+        """
+        Search the whole memory space, accessible to the process,
+        for the provided list of addresses, returning their values.
+        """
+        if self.__closed: raise ClosedProcess()
+        return search_values_by_addresses(self.pid, pytype, bufflength, addresses, raise_error=raise_error)
+
     def search_by_value(
         self,
         pytype: Type[T],
@@ -94,7 +115,7 @@ class LinuxProcess(AbstractProcess):
         if scan_type in [ScanTypesEnum.VALUE_BETWEEN, ScanTypesEnum.NOT_VALUE_BETWEEN]:
             raise ValueError("Use the method search_by_value_between(...) to search within a range of values.")
 
-        return search_all_memory(self.pid, pytype, bufflength, value, scan_type, progress_information, writeable_only)
+        return search_addresses_by_value(self.pid, pytype, bufflength, value, scan_type, progress_information, writeable_only)
 
     def search_by_value_between(
         self,
@@ -122,7 +143,7 @@ class LinuxProcess(AbstractProcess):
         if self.__closed: raise ClosedProcess()
 
         scan_type = ScanTypesEnum.NOT_VALUE_BETWEEN if not_between else ScanTypesEnum.VALUE_BETWEEN
-        return search_all_memory(self.pid, pytype, bufflength, (start, end), scan_type, progress_information, writeable_only)
+        return search_addresses_by_value(self.pid, pytype, bufflength, (start, end), scan_type, progress_information, writeable_only)
 
     def write_process_memory(
         self,

{pymemoryeditor-1.5.7 → pymemoryeditor-1.5.9}/PyMemoryEditor/process/__init__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 from abc import ABC, abstractmethod
-from typing import Generator, Optional, Tuple, Type, TypeVar, Union
+from typing import Generator, Optional, Sequence, Tuple, Type, TypeVar, Union
 
 from ..enums import ScanTypesEnum
 from ..process.info import ProcessInfo
@@ -61,6 +61,21 @@ class AbstractProcess(ABC):
         """
         raise NotImplementedError()
 
+    @abstractmethod
+    def search_by_addresses(
+        self,
+        pytype: Type[T],
+        bufflength: int,
+        addresses: Sequence[int],
+        *,
+        raise_error: bool = False,
+    ) -> Generator[Tuple[int, Optional[T]], None, None]:
+        """
+        Search the whole memory space, accessible to the process,
+        for the provided list of addresses, returning their values.
+        """
+        raise NotImplementedError()
+
     @abstractmethod
     def search_by_value(
         self,

pymemoryeditor-1.5.9/PyMemoryEditor/sample/application.py

@@ -0,0 +1,15 @@
+from .main_application_window import ApplicationWindow
+from .open_process_window import OpenProcessWindow
+
+
+def main(*args, **kwargs):
+    open_process_window = OpenProcessWindow()
+    process = open_process_window.get_process()
+
+    if process:
+        ApplicationWindow(process)
+        process.close()
+
+
+if __name__ == "__main__":
+    main()