Script API Reference - edgeof8/tIRC GitHub Wiki

This page provides a reference for the ScriptAPIHandler object, which is exposed to tIRC scripts as self.api. This API is the primary way scripts interact with the tIRC client, send commands, handle events, and access client information.

For a general guide on writing scripts, see Scripting tIRC.

The following methods are available on the self.api object within your script. Methods that perform I/O or interact with the asyncio event loop are typically async and should be awaited.

• async send_raw(data: str): Sends a raw string directly to the connected IRC server.

  • data: The raw IRC protocol line to send.

• async send_message(target: str, message: str): Sends a PRIVMSG to the specified target (channel or nickname).

  • target: The channel name or user's nickname.
  • message: The text of the message to send.

• async send_action(target: str, action_text: str): Sends a CTCP ACTION (/me) message to the specified target.

  • target: The channel name or user's nickname.
  • action_text: The text of the action.

• async send_notice(target: str, message: str): Sends a NOTICE to the specified target.

  • target: The channel name or user's nickname.
  • message: The text of the notice.

• async join_channel(channel_name: str, key: Optional[str] = None): Joins the specified IRC channel.

  • channel_name: The name of the channel to join (e.g., #example).
  • key: Optional channel key (password).

• async part_channel(channel_name: str, reason: Optional[str] = None): Parts (leaves) the specified IRC channel.

  • channel_name: The name of the channel to part.
  • reason: Optional reason for parting.

• async set_nick(new_nick: str): Attempts to change the client's nickname.

  • new_nick: The desired new nickname.
  • Returns bool: True if the NICK command was sent, False otherwise (e.g., if not connected).

• async execute_command(command_line: str): Executes a client command as if the user typed it.

  • command_line: The full command string (e.g., /join #channel or /my_script_command arg1).

• register_command(name: str, handler: Callable, help_text: Union[str, Dict[str, Any]], aliases: Optional[List[str]] = None): Registers a new slash command that users can execute.

  • name: The primary name of the command (without /).
  • handler: The function (or async coroutine) in your script that will handle this command. It will receive args_str: str as an argument.
  • help_text: Either a simple string for basic help, or a dictionary for richer help, e.g., {"usage": "/cmd <arg>", "description": "Does something.", "examples": ["/cmd Alice", "/cmd"]}. The README.md indicates the dictionary format is supported for richer help.
  • aliases: An optional list of alternative names for the command.

• unregister_command(name: str): Unregisters a previously registered command.

  • name: The primary name of the command to unregister.

• subscribe_to_event(event_name: str, handler: Callable): Subscribes a handler function to a specific event.

  • event_name: The name of the event to subscribe to (e.g., "PRIVMSG", "CLIENT_CONNECTED").
  • handler: The function (or async coroutine) in your script to call when the event occurs. It will receive event_data: Dict[str, Any] as an argument.

• unsubscribe_from_event(event_name: str, handler: Callable): Unsubscribes a handler function from a specific event.

  • event_name: The name of the event.
  • handler: The handler function to remove.

• async add_message_to_context(context_name: str, text: str, color_key_or_attr: Optional[Any] = None, source_full_ident: Optional[str] = None, is_privmsg_or_notice: bool = False): Adds a message line to the specified UI context (window).

  • context_name: The name of the context (e.g., "Status", a channel name like "#example", or a query nickname).
  • text: The message text to display.
  • color_key_or_attr: Optional color information for the message.
  • source_full_ident: Optional source identifier for the message.
  • is_privmsg_or_notice: Boolean indicating if this is a user-generated message.

• get_client_nick() -> Optional[str]: Returns the current nickname of the client, or None if not connected/registered.

• get_current_context_name() -> Optional[str]: Returns the name of the currently active UI context (window).

• get_context_messages(context_name: str, count: Optional[int] = None) -> List[str]: Retrieves message history for a given context.

  • context_name: The name of the context.
  • count: Optional number of recent messages to retrieve.

• get_client_state(key: str, default: Optional[Any] = None) -> Any: Retrieves a value from the StateManager.

  • key: The state key.
  • default: Default value if key not found.

• log_info(message: str): Logs an informational message from the script.

• log_warning(message: str): Logs a warning message.

• log_error(message: str): Logs an error message.

• log_debug(message: str): Logs a debug message.

• get_script_dir() -> str: Returns the absolute path to the directory where the current script file is located. Useful for loading script-specific resources.

• get_script_data_dir() -> str: Returns the absolute path to a dedicated data directory for the current script (e.g., scripts/data/your_script_name/). tIRC typically creates this directory if it doesn't exist. Useful for persistent script data.

• add_trigger(...)
• remove_trigger(...)
• list_triggers(...)

Scripts can subscribe to a variety of events. The event_data dictionary passed to handlers typically includes timestamp, raw_line (if applicable from a server message), and client_nick. Below are key events mentioned in README.md and their specific additional event_data keys.

• CLIENT_CONNECTING: Fired when a new connection attempt is initiated.
  • event_data keys: server (str), port (int), nick (str), ssl (bool).
• CLIENT_CONNECTED: Fired when TCP/IP connection is established and CAP negotiation begins.
  • event_data keys: server (str), port (int), nick (str), ssl (bool).
• CLIENT_CAP_NEGOTIATION_START: Fired when capability negotiation begins.
  • event_data keys: capabilities (List[str] - requested capabilities).
• CLIENT_CAP_NEGOTIATION_COMPLETE: Fired when capability negotiation completes.
  • event_data keys: negotiated_capabilities (List[str]).
• CLIENT_AUTHENTICATING: Fired when SASL authentication begins.
  • event_data keys: mechanism (str).
• CLIENT_AUTHENTICATED: Fired upon successful SASL authentication.
  • event_data keys: account (str - account name if available).
• CLIENT_REGISTERING: Fired when sending NICK/USER registration commands.
  • event_data keys: nick (str), username (str), realname (str).
• CLIENT_REGISTERED: Fired upon receiving RPL_WELCOME (001).
  • event_data keys: nick (str), server_message (str), hostname (str).
• CLIENT_READY: Fired after successful registration and initial auto-join actions.
  • event_data keys: nick (str), channels (List[str]).
• CLIENT_DISCONNECTED: Fired when connection is lost or closed.
  • event_data keys: server (str), port (int), reason (str), reconnecting (bool).
• CLIENT_RECONNECTING: Fired when a reconnection attempt is initiated.
  • event_data keys: attempt (int), max_attempts (int).
• CLIENT_MESSAGE_ADDED_TO_CONTEXT: Fired when any message is added to any context's buffer by IRCClient_Logic.add_message.
  • event_data keys: context_name (str), text (str - the full line added, including timestamp/prefix), color_key_or_attr (Any), source_full_ident (Optional[str]), is_privmsg_or_notice (bool).
• CLIENT_NICK_CHANGED: Fired specifically when tIRC's own nickname successfully changes.
  • event_data additional keys: old_nick (str), new_nick (str).
• CLIENT_SHUTDOWN_FINAL: Fired just before application exit, after curses UI is down (if UI was active).

• PRIVMSG: For channel and private messages.
  • event_data additional keys: nick (str), userhost (str), target (str), message (str), is_channel_msg (bool), tags (Dict[str, Any] - parsed IRCv3 message tags).
• NOTICE: For IRC NOTICEs.
  • event_data additional keys: nick (str), userhost (str), target (str), message (str), is_channel_notice (bool), tags (Dict[str, Any]).
• JOIN: When a user (including client) joins.
  • event_data additional keys: nick (str), userhost (str - if available from server, e.g. with extended-join), channel (str), account (str - if available, e.g. with extended-join), real_name (str - if available, e.g. with extended-join), is_self (bool).
• CHANNEL_FULLY_JOINED: Fired after a channel is successfully joined and RPL_ENDOFNAMES (or equivalent) is received.
  • event_data additional keys: channel_name (str).
• PART: When a user (including client) parts.
  • event_data additional keys: nick (str), userhost (str), channel (str), reason (str), is_self (bool).
• QUIT: When a user quits.
  • event_data additional keys: nick (str), userhost (str), reason (str).
• NICK: When any user changes their nickname.
  • event_data additional keys: old_nick (str), new_nick (str), userhost (str), is_self (bool).
• MODE: When a mode change occurs (raw event).
  • event_data additional keys: nick (str - setter), userhost (str - setter's host), target (str - channel/nick affected), modes_and_params (str - raw mode string), parsed_modes (List[Dict] - structured mode changes).
• CHANNEL_MODE_APPLIED: Fired after a channel MODE is processed and applied.
  • event_data additional keys: channel (str), setter_nick (str), setter_userhost (str), mode_changes (List[Dict] - structured), current_channel_modes (List[str]).
• TOPIC: When a channel topic is changed or viewed.
  • event_data additional keys: nick (str - setter), userhost (str), channel (str), topic (str).
• CHGHOST: When a user's host changes.
  • event_data additional keys: nick (str), new_ident (str), new_host (str), userhost (str - old userhost).

• RAW_IRC_LINE: Fired for every complete raw line received from the server before tIRC's internal parsing.
  • event_data keys: raw_line (str).
• RAW_IRC_NUMERIC: Fired for all numeric replies from the server.
  • event_data keys: numeric (int), source (str - server name), params_list (List[str] - full parameters), display_params_list (List[str] - parameters with client nick removed if first), trailing (Optional[str]), tags (Dict[str, Any]).

Example Event Subscription:

async def my_privmsg_handler(event_data: Dict[str, Any]):
    nick = event_data.get("nick")
    message = event_data.get("message")
    # ... do something ...

self.api.subscribe_to_event("PRIVMSG", my_privmsg_handler)

Note: This API reference is based on information available in README.md and related documentation. The exact method signatures, return types, and available events might have evolved. Always refer to the latest tIRC source code (especially tirc_core/scripting/script_api_handler.py) for the most accurate and complete API details.