Skip to content

opening-process.md

Latest commit

 

History

History
154 lines (116 loc) · 4.33 KB

opening-process.md

File metadata and controls

154 lines (116 loc) · 4.33 KB

Opening a process

Everything starts with OpenProcess — the unified entry point for all three operating systems. Under the hood it returns the right backend (WindowsProcess, LinuxProcess or MacProcess), but you never have to care: the API is identical.

Basic usage

from PyMemoryEditor import OpenProcess

with OpenProcess(process_name="notepad.exe") as process:
    print("PID:", process.pid)

The with block automatically calls process.close() when you leave it, releasing any OS handle the backend acquired.

Identify the process — by name or PID

You can identify the target in two ways:

Argument What it does
process_name="notepad.exe" Looks up the PID by name. Most natural way for desktop apps and games.
pid=1234 Skip the name lookup and attach to a known PID directly.

If you pass both, pid wins. If you pass neither, TypeError is raised.

Name matching: case and partial matches

By default, process_name matching is:

  • Case-sensitive on Linux and macOS.
  • Case-insensitive on Windows (matches the OS convention).
  • Exact: the name has to match the executable name exactly.

You can override both with keyword arguments:

# Match "chrome.exe", "ChroMe.EXE", "chrome" — anywhere case-insensitively.
OpenProcess(process_name="chrome", case_sensitive=False, exact_match=False)
Argument Type Default Effect
case_sensitive bool platform-dependent When False, ignores case.
exact_match bool True When False, matches as a substring.

If a partial match resolves to more than one process, an AmbiguousProcessNameError is raised — pick one PID from the listed candidates and pass it via pid= instead.

Permissions (Windows-only)

Only the Windows backend accepts a permission= mask — it maps directly to the PROCESS_* access rights of OpenProcess. The default opens a read + write handle:

# Default — same as:
OpenProcess(
    process_name="notepad.exe",
    permission=(
        ProcessOperationsEnum.PROCESS_VM_READ
        | ProcessOperationsEnum.PROCESS_VM_WRITE
        | ProcessOperationsEnum.PROCESS_VM_OPERATION
        | ProcessOperationsEnum.PROCESS_QUERY_INFORMATION
    ),
)

For a read-only handle (less powerful but useful for static analysis):

from PyMemoryEditor import OpenProcess, ProcessOperationsEnum

OpenProcess(
    process_name="notepad.exe",
    permission=ProcessOperationsEnum.PROCESS_VM_READ
        | ProcessOperationsEnum.PROCESS_QUERY_INFORMATION,
)

For full control:

OpenProcess(
    process_name="notepad.exe",
    permission=ProcessOperationsEnum.PROCESS_ALL_ACCESS,
)
:class: note

The `permission` argument is **ignored** — those platforms govern access via
`ptrace_scope` (Linux) or Mach entitlements (macOS). Passing a value emits a
`UserWarning` so a Windows-shaped mask doesn't disappear silently.

See [Platform Notes](../platform-notes.md) for details.

Closing the handle

When you're done, close the process:

process.close()

Or use the context manager (recommended):

with OpenProcess(pid=1234) as process:
    ...
# process is closed here, even if an exception was raised

Once closed, any further call raises ClosedProcess.

Common errors

Exception Meaning
ProcessNotFoundError No process matches the given process_name.
ProcessIDNotExistsError The given pid doesn't exist on the system.
AmbiguousProcessNameError More than one process matches a partial name — pick a PID from .pids.
PermissionError The OS denied access — usually fixable; see Troubleshooting.
ClosedProcess Operation attempted on an already-closed handle.

All exceptions inherit from PyMemoryEditorError, so you can catch them collectively:

from PyMemoryEditor import OpenProcess, PyMemoryEditorError

try:
    with OpenProcess(process_name="game.exe") as process:
        ...
except PyMemoryEditorError as e:
    print("Failed to open process:", e)