gh-76: Improve calling pymhf from code and document

Author: monkeyman192

docs/docs/change_log.rst

@@ -8,6 +8,7 @@ Current (0.1.16.dev)
 - Fixed an issue running mods where attach to already existing processes.
 - Fixed an issue with getting the caller offset address.
 - Added the ability to specify an already running processes' PID to attach pyMHF. (`#75 <https://github.com/monkeyman192/pyMHF/issues/75>`_)
+- Made :py:func:`~pymhf.main.run_module` a public method as the recommended way to invoke pyMHF from code. (`#76 <https://github.com/monkeyman192/pyMHF/issues/76>`_)
 
 0.1.15 (16/07/2025)
 -------------------

docs/docs/index.rst

@@ -4,6 +4,7 @@ Usage guide
 .. toctree::
    :maxdepth: 1
 
+   usage
    settings
    writing_mods
    creating_hook_definitions

docs/docs/inter_mod_functionality.rst

@@ -88,7 +88,7 @@ Running multiple mods in a single folder
 ----------------------------------------
 
 Similar to how single-file mods work. pyMHF can be pointed to a folder to run (ie. the path you provide to the ``pymhf run`` command is the folder.)
-Currently, for this to work the folder must contain the ``pymhf.toml`` file as if it were a library (see the [settings](../settings.md) docs for more details).
+Currently, for this to work the folder must contain the ``pymhf.toml`` file as if it were a library (see :doc:`/docs/settings` for more details).
 
 Caveats / Things to keep in mind
 --------------------------------

docs/docs/settings.rst

@@ -22,6 +22,8 @@ This section handles properties which relate to the game or program that the lib
 ``exe``
 """""""
 
+*Required unless ``pid`` specified*
+
 If :ref:`settings-pymhf.start_exe` is ``True`` (the default) - either the absolute path to the binary being run, or the name of the exe which is being run by steam.
 
 If :ref:`settings-pymhf.start_exe` is ``False`` - the exe name (ie. ``notepad.exe``) of an already running process to attach to.
@@ -31,6 +33,8 @@ If :ref:`settings-pymhf.start_exe` is ``False`` - the exe name (ie. ``notepad.ex
 ``pid``
 """""""
 
+*Optional*
+
 The process id to attach pyMHF to. This will have no effect if :ref:`settings-pymhf.exe` is specified and also if :ref:`settings-pymhf.start_exe` is False.
 
 .. _settings-pymhf.steam_guid:

docs/docs/usage.rst

@@ -0,0 +1,39 @@
+Usage
+=====
+
+There are a number of convenient ways to use pyMHF:
+
+Command line
+------------
+
+pyMHF registers ``pymhf`` as a command which can be called from your shell. This command has a number of options (call ``pymhf --help`` for more details).
+
+From code
+---------
+
+pyMHF may also be invoked from code in the case of a more complex situation (eg, needing to hook some dynamically generated subprocess).
+
+.. code-block:: py
+
+    import os.path as op
+    from subprocess import Popen
+
+    from pymhf import run_module
+
+    if __name__ == "__main__":
+        # Run a mod by creating the process and then attaching pymhf later.
+        proc = Popen("notepad.exe")
+        CONFIG = {
+            "pid": proc.pid,
+            "start_paused": False,
+            "start_exe": False,
+        }
+        run_module(op.join(op.dirname(__file__), "test_mod.py"), CONFIG, None, None)
+
+In the above we are passing the absolute path to the file (or it could be mod folder) to be loaded, as well as the explicit configuration to be loaded.
+
+.. note::
+    See :doc:`/docs/settings` for details on the keys which the config can have. Keep in mind that the keys under the ``pymhf`` section are top level keys, and keys under the subsections (eg. ``pymhf.logging``) will have a top-level key of ``logging`` and then the keys are under that.
+
+.. note::
+    See :py:func:`~pymhf.main.run_module` for details on the other arguments (they are only required if you are calling a library which is VERY unlikely from code...)

examples/run_mod_from_code.py

@@ -0,0 +1,15 @@
+import os.path as op
+from subprocess import Popen
+
+from pymhf import run_module
+
+if __name__ == "__main__":
+    # Run a mod by creating the process and then attaching pymhf later.
+    # It is generally recommended that you just use pyMHF's built-in functionality for doing this.
+    proc = Popen("notepad.exe")
+    CONFIG = {
+        "pid": proc.pid,
+        "start_paused": False,
+        "start_exe": False,
+    }
+    run_module(op.join(op.dirname(__file__), "test_mod.py"), CONFIG, None, None)

examples/test_mod.py

@@ -16,7 +16,7 @@
 # ///
 from logging import getLogger
 
-from pymhf import Mod
+from pymhf import Mod, load_mod_file
 
 logger = getLogger("TestMod")
 
@@ -28,3 +28,7 @@ class TestMod(Mod):
     def __init__(self):
         super().__init__()
         logger.info("Loaded Test mod!")
+
+
+if __name__ == "__main__":
+    load_mod_file(__file__)

pymhf/__init__.py

@@ -13,7 +13,7 @@
 from .core._types import FUNCDEF  # noqa
 from .core.hooking import FuncHook  # noqa
 from .core.mod_loader import Mod, ModState  # noqa
-from .main import load_mod_file, load_module  # noqa
+from .main import load_mod_file, load_module, run_module  # noqa
 from .utils.imports import SPHINX_AUTODOC_RUNNING
 
 try:

pymhf/core/_internal.py

@@ -1,14 +1,7 @@
 import ctypes
 from concurrent.futures import ThreadPoolExecutor
-from enum import Enum
-
-
-class LoadTypeEnum(Enum):
-    INVALID = 0
-    SINGLE_FILE = 1
-    LIBRARY = 2
-    MOD_FOLDER = 3
 
+from pymhf.core._types import LoadTypeEnum
 
 CWD: str = ""
 MODULE_PATH: str = ""

pymhf/core/_types.py

@@ -1,6 +1,40 @@
 from enum import Enum
 from typing import Any, NamedTuple, Optional, Protocol
 
+from typing_extensions import NotRequired, TypedDict
+
+
+class pymhfGUIConfig(TypedDict):
+    shown: NotRequired[bool]
+    scale: NotRequired[float]
+    always_on_top: NotRequired[bool]
+
+
+class pymhfLoggingConfig(TypedDict):
+    default_log_dir: NotRequired[str]
+    log_level: NotRequired[str]
+    window_name_override: NotRequired[str]
+
+
+class pymhfConfig(TypedDict):
+    exe: NotRequired[str]
+    pid: NotRequired[int]
+    steam_guid: NotRequired[int]
+    required_assemblies: NotRequired[list[str]]
+    start_paused: NotRequired[bool]
+    default_mod_save_dir: NotRequired[str]
+    internal_mod_dir: NotRequired[str]
+    start_exe: NotRequired[bool]
+    logging: NotRequired[pymhfLoggingConfig]
+    gui: NotRequired[pymhfGUIConfig]
+
+
+class LoadTypeEnum(Enum):
+    INVALID = 0
+    SINGLE_FILE = 1
+    LIBRARY = 2
+    MOD_FOLDER = 3
+
 
 class FunctionIdentifier(NamedTuple):
     name: str