Python API Reference

The Python API provides a high-level, Pythonic interface to the AppGuard library.

AppGuard Class

app_guard.AG_init(app_handle: str, on_quit_callback: Callable, quit_immediate: bool) → None
app_guard.AG_release() → None
app_guard.AG_is_loaded() → bool
app_guard.AG_is_primary_instance() → bool
app_guard.AG_create_IPCMsg(msg_obj: app_guard.AppGuard.IPCMsg, msg_handle: str, callback: Callable) → None
app_guard.AG_register_msg(msg_obj: object) → None
app_guard.AG_unregister_msg(msg_id: int) → None
app_guard.AG_send_msg_request(msg_handle: str, msg_data: object) → None
app_guard.AG_get_process_id() → int
app_guard.AG_focus_window(window_name: str) → None
class app_guard.IPCMsg

Bases: pybind11_object

__init__(self: app_guard.AppGuard.IPCMsg) → None
property msg_handle
property msg_id
class app_guard.AppGuard[source]

Bases: object

Cross-platform Python wrapper for application instance management and IPC.

This class provides a high-level interface to the AppGuard C++ library, allowing for single-instance application management and inter-process communication.

classmethod init(app_handle: str, on_quit_callback: Callable, quit_immediate: bool = True) → None[source]

Initialize the AppGuard library for application instance management.

The app_handle could be a window name or unique identifier. It is used internally by the library. This function must be called first before any other functions in the library.

Parameters:

  • app_handle (str) – A unique application identifier.

  • on_quit_callback (Callable) – A callback function to be called when the application quits immediately. This callback will only be invoked on secondary instances if the quit_immediate boolean is set to true.

  • quit_immediate (bool, optional) – Whether to quit immediately when a secondary instance of the app is detected. If set to False, the closing of the library/application will be left to the user. Defaults to True.

Raises:

AppGuardError – If initialization fails.

classmethod release() → None[source]

Release AppGuard resources and perform cleanup.

Cleans up the current app instance and IPC related resources.

classmethod is_loaded() → bool[source]

Check if the AppGuard library is loaded and initialized.

Call this function to check if the library is loaded correctly. Returns False if the library is not initialized or was released.

Returns:

True if the library is loaded, False otherwise.

Return type:

bool

classmethod is_primary_instance() → bool[source]

Determine if this is the primary instance of the application.

This function is used internally by the library for certain checks, e.g., if the app should quit if the current process is not a primary instance.

Returns:

True if this is the primary application instance, False otherwise.

Return type:

bool

__init__() → None[source]

Initialize AppGuard instance.

create_ipc_msg(msg_handle: str, callback: Callable) → IPCMsg[source]

Create an IPC message structure for inter-process communication.

Call this function to initialize the IPC message with a handle and a callback. The handle is used for message lookup. Through it, the library calls the function you provided, passing an IPCMsgData as an argument. This is used in conjunction with the register_msg and send_msg_request methods.

Parameters:

  • msg_handle (str) – A message identifier.

  • callback (Callable) – A callback function to be invoked using the message handle when an IPC message request is received.

Returns:

The created IPC message structure.

Return type:

IPCMsg

register_msg(msg: IPCMsg) → None[source]

Register an IPC message for receiving communications.

Call this function after creating the IPC message. The function places an ID on the message struct which can be used to unregister the message.

Parameters:

msg (IPCMsg) – An IPCMsg structure to register.

unregister_msg(msg: IPCMsg) → None[source]

Unregister an IPC message by its message object.

Parameters:

msg (IPCMsg) – The IPCMsg object to unregister.

send_msg_request(msg_handle: str, msg_data: str) → None[source]

Send an IPC message request to another process instance.

This function can be used to send an IPC message to a live instance of the program. This could typically be used to forward data to the program from other secondary instances before exiting, e.g., command line arguments. Only registered messages that are found by the same handle provided will be called with the message data passed to them.

Parameters:

  • msg_handle (str) – The message handle identifier.

  • msg_data (str) – The message data to send.

focus_window(window_name: str) → None[source]

Focus a window by its name.

Parameters:

window_name (str) – The name of the window to focus.

get_process_id() → int[source]

Retrieve the current process ID.

Returns:

The current process ID.

Return type:

int

Exceptions

exception app_guard.NotLoadedError[source]

Bases: Exception

Exception raised when AppGuard is not loaded/initialized.

exception app_guard.AppGuardError[source]

Bases: Exception

General AppGuard exception.

Data Structures

class app_guard.IPCMsg

Bases: pybind11_object

__init__(self: app_guard.AppGuard.IPCMsg) → None
property msg_handle
property msg_id

Low-Level Functions

These functions provide direct access to the C++ library functions. Generally, you should use the AppGuard class instead.

app_guard.AG_init(app_handle: str, on_quit_callback: Callable, quit_immediate: bool) → None
app_guard.AG_release() → None
app_guard.AG_is_loaded() → bool
app_guard.AG_is_primary_instance() → bool
app_guard.AG_create_IPCMsg(msg_obj: app_guard.AppGuard.IPCMsg, msg_handle: str, callback: Callable) → None
app_guard.AG_register_msg(msg_obj: object) → None
app_guard.AG_unregister_msg(msg_id: int) → None
app_guard.AG_send_msg_request(msg_handle: str, msg_data: object) → None
app_guard.AG_get_process_id() → int
app_guard.AG_focus_window(window_name: str) → None