Skip to Content
Utilities

Utilities

Helper Classes

zwylib.SingletonMeta

class SingletonMeta(type)

Metaclass implementing the singleton pattern. Use it as the metaclass for any class that must have only one instance.

Example

class MyManager(metaclass=SingletonMeta):
    ...
 
a = MyManager()
b = MyManager()
 
assert a is b  # True

zwylib.Callback1

zwylib.Callback1(func: (Any) -> None)

Wrapper class allowing a Python function to be passed into Java code via Chaquopy, emulating the Utilities.Callback Java interface.

Constructor Arguments

  • fn (Callable[[Any], None]): A Python function that accepts a single argument and returns nothing. Called from Java via .run(...).

Methods

run
Callback1.run(arg: Any) -> None

Called from Java, forwards the provided argument to the Python function. Exceptions are logged internally and not raised.

Example

def my_python_callback(value):
    print(f"Received from Java: {value}")
 
callback = zwylib.Callback1(my_python_callback)
some_java_object.setCallback(callback)

Helper Functions

zwylib.copy_to_clipboard

zwylib.copy_to_clipboard(bulletin_helper: Optional[BulletinHelper], text_to_copy: str) -> None

Copies the provided text to the clipboard and displays a “Copied to clipboard” bulletin if successful and a BulletinHelper is provided.

Arguments

  • bulletin_helper (Optional[[BulletinHelper](https://plugins.exteragram.app/docs/bulletin-helper)]): Instance of a bulletin helper to show the success message. If None, no bulletin is shown.
  • text_to_copy (str): Text to copy to the clipboard.

Returns

  • None: Does not return a value.

Example

bulletins = zwylib.build_bulletin_helper("MyPlugin")
zwylib.copy_to_clipboard(bulletins, "example text")
# Copies "example text" to clipboard and shows a bulletin

zwylib.download_and_install_plugin

zwylib.download_and_install_plugin(msg, plugin_id: str, max_tries = 10, is_queued = False, current_try = 0) -> None

Downloads a plugin file from a message’s document and installs it using the PluginsController. If the file is not yet downloaded, it queues the download and retries.

Arguments

  • msg (Any): Message object containing the plugin file as a document in msg.media.
  • plugin_id (str): Identifier of the plugin to install.
  • max_tries (int, default 10): Must not be set manually. Maximum tries of plugin downloading.
  • is_queued (bool, default False): Must not be set manually. Indicates whether the function is called as part of a queued retry.
  • current_try (int, default 0): Must not be set manually. Current plugin download try.

Example

logger = zwylib.build_log("MyPlugin")
zwylib.download_and_install_plugin(message, "example_plugin")
# Logs download/install progress and shows error bulletin if installation fails

zwylib.get_plugin

zwylib.get_plugin(plugin_id: str) -> Optional[Plugin]

Retrieves a plugin instance from the PluginsController by its identifier.

Arguments

  • plugin_id (str): Identifier of the plugin to retrieve.

Returns

  • Optional[Plugin]: The plugin instance if found, or None if no plugin matches the plugin_id.

Example

plugin = zwylib.get_plugin("example_plugin")
if plugin:
    print(f"Found plugin: {plugin}")
else:
    print("Plugin not found")

zwylib.arraylist_to_list

zwylib.arraylist_to_list(jarray: ArrayList) -> Optional[List]

Converts a Java ArrayList to a Python list.

Arguments

  • jarray (ArrayList): The Java ArrayList to convert. If None, returns None.

Returns

  • Optional[List]: A Python list containing the elements of the ArrayList, or None if the input is None.

Example

java_array = ArrayList()
java_array.add("item1")
java_array.add("item2")
python_list = zwylib.arraylist_to_list(java_array)
# python_list is ["item1", "item2"]

zwylib.list_to_arraylist

zwylib.list_to_arraylist(python_list: Optional[List], int_auto_convert = True) -> Optional[ArrayList]

Converts a Python list to a Java ArrayList, optionally automatic converting Python integers to Java jint types.

Arguments

  • python_list (Optional[List]): The Python list to convert. If None or empty, returns None.
  • int_auto_convert (bool, default True): If True, converts Python int values to Java jint when adding to the ArrayList.

Returns

  • Optional[ArrayList]: A Java ArrayList containing the elements of the input list, or None if the input is None.

Example

python_list = [1, "item2"]
java_array = zwylib.list_to_arraylist(python_list)
# java_array contains [jint(1), "item2"]

zwylib.format_exc

zwylib.format_exc() -> str

Formats the current exception traceback as a string, similar to traceback.format_exc().

Returns

  • str: A string containing the formatted traceback of the current exception, stripped of leading/trailing whitespace.

Example

try:
    1 / 0
except ZeroDivisionError:
    error_trace = zwylib.format_exc()
    print(error_trace)  # Prints the formatted traceback

zwylib.format_exc_from

zwylib.format_exc_from(e: Exception) -> str

Formats the traceback of a specific exception as a string.

Arguments

  • e (Exception): The exception whose traceback should be formatted.

Returns

  • str: A string containing the formatted traceback of the exception, stripped of leading/trailing whitespace.

Example

try:
    1 / 0
except ZeroDivisionError as e:
    error_trace = zwylib.format_exc_from(e)
    print(error_trace)  # Prints the formatted traceback

zwylib.format_exc_only

zwylib.format_exc_only(e: Exception) -> str

Formats only the exception message and type (without the full traceback) as a string.

Arguments

  • e (Exception): The exception whose message and type should be formatted.

Returns

  • str: A string containing the formatted exception message and type, stripped of leading/trailing whitespace.

Example

try:
    1 / 0
except ZeroDivisionError as e:
    error_msg = zwylib.format_exc_only(e)
    print(error_msg)  # Prints: ZeroDivisionError: division by zero

Helper Functions

zwylib.is_zwylib_version_sufficient

zwylib.is_zwylib_version_sufficient(
    plugin_name: str,
    version: str,
    show_bulletin: bool = True
) -> bool

Checks whether the current ZwyLib version is greater than or equal to the required version. If the version is insufficient and show_bulletin is True, a bulletin is shown with a button allowing the user to navigate to the update.

Arguments

  • plugin_name (str): Plugin name shown in the bulletin.
  • version (str): Minimum required ZwyLib version.
  • show_bulletin (bool, default True): Whether to show a bulletin on version mismatch.

Returns

  • bool: True if current ZwyLib version is sufficient, False otherwise.

Example

zwylib.is_zwylib_version_sufficient("MyPlugin", "1.2.0")
Last updated on
Requests