Skip to content

feat: drop the psutil dependency and fix documentation divergences#44

Merged
JeanExtreme002 merged 1 commit into
mainfrom
jeanextreme002/drop-psutil-dependency
Jun 5, 2026
Merged

feat: drop the psutil dependency and fix documentation divergences#44
JeanExtreme002 merged 1 commit into
mainfrom
jeanextreme002/drop-psutil-dependency

Conversation

@JeanExtreme002
Copy link
Copy Markdown
Owner

Summary

Makes the core library truly dependency-free by replacing psutil with native per-platform process discovery, and corrects a set of documentation/docstring claims that did not match the actual runtime behavior.

Drop psutil

psutil was the only hard runtime dependency, used solely to resolve a process name to a PID and to check whether a PID exists. Both are now done natively:

  • WindowsCreateToolhelp32Snapshot(TH32CS_SNAPPROCESS) + Process32First/Next; pid check via OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION).
  • Linux — enumerate /proc/<pid>, read the name from /proc/<pid>/comm; pid check via /proc/<pid>.
  • macOS — libproc proc_listpids + proc_name (basename of proc_pidpath as fallback); pid check via os.kill(pid, 0).

process.util now dispatches to the per-OS backend. psutil moves from a required dependency to the [app] extra — the desktop GUI's process picker still uses its richer username/memory info, which is beyond what the core needs.

Process-name matching semantics (case_sensitive, exact_match) are preserved. On Linux the name comes from comm, which the kernel truncates to 15 characters — the same limitation psutil had here.

Documentation/docstring fixes

  • DEFAULT_MAX_REGION_CHUNK is 256 MiB (was documented as 16 MiB).
  • iter_region_chunks chunks are contiguous, not overlapping (pattern-boundary handling happens in the scanner).
  • Partial reads raise OSError — they are not logged as WARNING.
  • ThreadInfo.start_address is always None on every backend (documented as reserved).
  • RemotePointer bufflength is required only to read str/bytes; writing accepts None.
  • Corrected the compile_pattern example output.
  • OpenProcess signature now shows the real platform-specific defaults.
  • macOS ModuleInfo name/path are both empty when the image path can't be resolved (the fallback only applies on Windows).
  • read_string reads exactly byte_count bytes (raises on a short read), not "up to".
  • ptr_size defaults to None (auto-detected from target bitness) across the pointer APIs.
  • Migrated search_by_value / search_by_addresses examples to keyword arguments.

Testing

  • New tests/test_process_enumeration.py exercises the native enumeration and pid_exists on the host OS.
  • Existing lookup tests rewired off psutil.
  • Full non-GUI suite passes (312 passed, 13 skipped). The Windows/Linux native paths are covered by CI on those platforms, as with the existing thread/module enumeration tests.

@JeanExtreme002 JeanExtreme002 changed the title Drop the psutil dependency and fix documentation divergences feat: drop the psutil dependency and fix documentation divergences Jun 5, 2026
Make the core library truly dependency-free by replacing psutil with
native per-platform process discovery, and correct a set of doc/docstring
claims that did not match runtime behavior.

Drop psutil:
- Native process enumeration and pid checks: CreateToolhelp32Snapshot
  (Windows), /proc (Linux), libproc proc_listpids/proc_name (macOS).
- process.util now dispatches to the per-OS backend instead of psutil.
- psutil moves from a hard runtime dependency to the [app] extra (the GUI
  process picker still uses its richer username/memory info).
- Add tests/test_process_enumeration.py and rewire the lookup tests off
  psutil.

Docs/docstring fixes:
- DEFAULT_MAX_REGION_CHUNK is 256 MiB (was documented as 16 MiB).
- iter_region_chunks chunks are contiguous, not overlapping.
- partial reads raise OSError; they are not logged as WARNING.
- ThreadInfo.start_address is always None on every backend.
- RemotePointer bufflength is required only to read str/bytes, not write.
- Correct the compile_pattern example output.
- OpenProcess signature shows the real platform-specific defaults.
- macOS ModuleInfo name/path are both empty when the path is unresolvable.
- read_string reads exactly byte_count bytes (raises on a short read).
- ptr_size defaults to None (auto-detected) across the pointer APIs.
- Migrate search_by_value/search_by_addresses examples to keyword args.
@JeanExtreme002 JeanExtreme002 force-pushed the jeanextreme002/drop-psutil-dependency branch from 6b21cf6 to 7e5923b Compare June 5, 2026 01:11
@JeanExtreme002 JeanExtreme002 merged commit e9f754b into main Jun 5, 2026
12 checks passed
@github-actions github-actions Bot deleted the jeanextreme002/drop-psutil-dependency branch June 5, 2026 01:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant