Here are some of the features of the python plugin interface:
As of HexChat 2.9.6 the plugin supports both so which should you pick:
As a user most older scripts will not be updated for Python 3 so 2 is your best bet.
As a developer I would just recommend you make your scripts compatible for both but do note that Python 2 on Windows does not support threads while Python 3 does.
The Python plugin comes with a py command that takes these arguments.
Load a script with given filename. /load will also work.
Unload module with given filename, or module name. /unload will also work.
Reload module with given filename, or module name. /reload will also work.
List Python scripts loaded
Execute given Python command interactively. For example:
/py exec import xchat; print(xchat.get_info(‘channel’))
Open the Python interactive console in a query >>python<<. Every message sent will be intercepted by the Python plugin interface, and interpreted interactively. Notice that the console and /py exec commands live in the same interpreter state.
Show some information about the Python plugin interface.
If you want some module to be autoloaded together with the Python plugin interface (which usually loads at startup time), just make sure it has a .py extension and put it in the addons subdir of HexChat’s config directory.
Before starting to explain what the API offers, I’ll do a short introduction about the HexChat context concept. Not because it’s something hard to understand, but because you’ll understand better the API explanations if you know what I’m talking about.
You can think about a context as an HexChat channel, server, or query tab. Each of these tabs, has its own context, and is related to a given server and channel (queries are a special kind of channel).
The current context is the one where HexChat passes control to the module. For example, when HexChat receives a command in a specific channel, and you have asked HexChat to tell you about this event, the current context will be set to this channel before your module is called.
For example this will print underlined red text:
print('\037\00304Text!')
Here is the traditional hello world example.
__module_name__ = "helloworld"
__module_version__ = "1.0"
__module_description__ = "Python module example"
print("Hello world!")
This module will print “Hello world!” in the HexChat console, and sleep forever until it’s unloaded. It’s a simple module, but already introduces some concepts. Notice how the module information is set. This information is obligatory, and will be shown when listing the loaded HexChat modules.
The xchat module is your passport to every HexChat functionality offered by the Python plugin interface. Here’s a simple example:
import xchat
xchat.prnt("Hi everyone!")
The following functions are available in the xchat module.
Priority given to hooks.
Used as return values for callbacks.
Tuple of (MAJOR_VERSION, MINOR_VERSION)
This function will print string in the current context. It’s mainly useful as a parameter to pass to some other function, since the usual print statement will have the same results. You have a usage example above.
This function is badly named because "print" is a reserved keyword of the Python language.
This function will generate a print event with the given arguments. To check which events are available, and the number and meaning of arguments, have a look at the Settings ‣ Text Events window. Here is one example:
xchat.emit_print("Channel Message", "John", "Hi there", "@")
With plugin version 1.0+ this function takes Keywords for certain Attributes such as time
Execute the given command in the current context. This has the same results as executing a command in the HexChat window, but notice that the / prefix is not used. Here is an example:
xchat.command("server irc.openprojects.net")
This function will do an RFC1459 compliant string comparison and is useful to compare channels and nicknames.
| Returns: | Returns 0 if they match and less than or greater than 0 if s1 is less than or greather than s2 |
|---|
if xchat.nickcmp(nick, "mynick") == 0:
print("They are the same!")
This function can strip colors and attributes from text.
| Parameters: |
|
|---|---|
| Returns: | Stripped String |
text = '\00304\002test' # Bold red text
print(text)
print(xchat.strip(text, len(text), 1)) # Bold uncolored text
Retrieve the information specified by the type string in the current context. At the moment of this writing, the following information types are available to be queried:
Example:
if xchat.get_info("server") == 'freenode':
xchat.prnt('connected!')
Retrieve the HexChat setting information specified by the name string, as available by the /set command. For example:
print("Current preferred nick: " + xchat.get_prefs("irc_nick1"))
With this function you may retrieve a list containing the selected information from the current context, like a DCC list, a channel list, a user list, etc. Each list item will have its attributes set dynamically depending on the information provided by the list type.
The example below is a rewrite of the example provided with HexChat’s plugin API documentation. It prints a list of every DCC transfer happening at the moment. Notice how similar the interface is to the C API provided by HexChat.
list = xchat.get_list("dcc")
if list:
print("--- DCC LIST ------------------")
print("File To/From KB/s Position")
for i in list:
print("%6s %10s %.2f %d" % (i.file, i.nick, i.cps/1024, i.pos))
Below you will find what each list type has to offer.
The channels list type gives you access to the channels, queries and their servers. The folloing attributes are available in each list item:
The dcc list type gives you access to a list of DCC file transfers. The following attributes are available in each list item:
The users list type gives you access to a list of users in the current channel. The following attributes are available in each list item:
The ignore list type gives you access to the current ignored list. The following attributes are available in each list item:
The notify list shows users on your friends list and their status:
These functions allow one to hook into HexChat events.
A callback is the function that will be called when the event happens.
The callback supposed to return one of the EAT_* constants, it is able control how HexChat will proceed after the callback returns. These are the available constants, and their meanings:
Note
Returning None is the same as returning EAT_NONE.
The parameter userdata, if given, allows you to pass a custom object to your callback.
If you create a hook with hook_server_attrs() or hook_print_attrs() the last argument in the callback will be an Attribute object.
The time the event occurred (from server-time) or 0
When a priority keyword parameter is accepted, it means that this callback may be hooked with five different priorities which are constants will define the order in which your plugin will be called. Most of the time, you won’t want to change its default value (PRI_NORM).
These parameters, when available in a callback, are lists of strings which contain the parameters the user entered for the particular command. For example, if you executed:
/command NICK Hi there!
This function allows you to hook into the name HexChat command. It means that everytime you type /name ..., callback will be called. Parameters userdata and priority have their meanings explained above, and the parameter help, if given, allows you to pass a help text which will be shown when /help name is executed.
| Returns: | New Hook Handler |
|---|
def onotice_cb(word, word_eol, userdata):
if len(word) < 2:
print("Second arg must be the message!")
else:
xchat.command("NOTICE @{} {}".format(xchat.get_info("channel"), word_eol[1]))
return xchat.EAT_ALL
xchat.hook_command("ONOTICE", onotice_cb, help="/ONOTICE <message> Sends a notice to all ops")
You may return one of EAT_* constants in the callback, to control HexChat’s behavior, as explained above.
This function allows you to register a callback to trap any print events. The event names are available in the Settings ‣ Text Events window. Parameters userdata and priority have their meanings explained above.
| Returns: | New Hook Handler |
|---|
def youpart_cb(word, word_eol, userdata):
print("You have left channel " + word[2])
return xchat.EAT_XCHAT # Don't let HexChat do its normal printing
xchat.hook_print("You Part", youpart_cb)
Along with Text Events there are a handfull of special events you can hook with this:
Open Context: Called when a new context is created.
Close Context: Called when a context is closed.
Focus Tab: Called when a tab is brought to front.
Focus Window: Called a toplevel window is focused, or the main tab-window is focused by the window manager.
This function is the same as hook_print() except its callback will have a new Attribute argument.
| Returns: | New Hook Handler |
|---|
New in version 1.0.
def youpart_cb(word, word_eol, userdata, attributes):
if attributes.time: # Time may be 0 if server-time is not enabled.
print("You have left channel {} at {}".format(word[2], attributes.time))
return xchat.EAT_XCHAT
xchat.hook_print_attrs("You Part", youpart_cb)
This function allows you to register a callback to be called when a certain server event occurs. You can use this to trap PRIVMSG, NOTICE, PART, a server numeric, etc. Parameters userdata and priority have their meanings explained above.
| Returns: | New Hook Handler |
|---|
def kick_cb(word, word_eol, userdata):
print('{} was kicked from {} ({})'.format(word[3], word[2], word_eol[4]))
# Don't eat this event, let other plugins and HexChat see it too
return xchat.EAT_NONE
xchat.hook_server("KICK", kick_cb)
This function is the same as hook_server() Except its callback will have a new Attribute argument.
| Returns: | New Hook Handler |
|---|
New in version 1.0.
def kick_cb(word, word_eol, userdata, attributes):
if attributes.time: # Time may be 0 if server-time is not enabled.
print('He was kicked at {}'.format(attributes.time))
return xchat.EAT_NONE
xchat.hook_server_attrs("KICK", kick_cb)
This function allows you to register a callback to be called every timeout milliseconds. Parameters userdata and priority have their meanings explained above.
| Returns: | New Hook Handler |
|---|
myhook = None
def stop_cb(word, word_eol, userdata):
global myhook
if myhook is not None:
xchat.unhook(myhook)
myhook = None
print("Timeout removed!")
def timeout_cb(userdata):
print("Annoying message every 5 seconds! Type /STOP to stop it.")
return 1 # Keep the timeout going
myhook = xchat.hook_timer(5000, timeout_cb)
xchat.hook_command("STOP", stop_cb)
If you return a true value from the callback, the timer will be keeped, otherwise it is removed.
This function allows you to register a callback to be called when the plugin is going to be unloaded. Parameters userdata and priority have their meanings explained above.
| Returns: | New Hook Handler |
|---|
def unload_cb(userdata):
print("We're being unloaded!")
xchat.hook_unload(unload_cb)
Unhooks any hook registered with the hook functions above.
| Parameters: | handler – Handler returned from hook_print(), hook_command(), hook_server() or hook_timer() |
|---|
As of version 1.0 of the plugin hooks from hook_print() and hook_command() can be unhooked by their names.
You can use pluginpref to easily store and retrieve settings.
Stores settings in addon_python.conf in the config dir.
| Returns: |
|
|---|
New in version 0.9.
Note
Until the plugin uses different a config file per script it’s recommened to use ‘scriptname_settingname’ to avoid conflicts.
This will return the value of the variable of that name. If there is none by this name it will return None.
| Returns: | String or Integer of stored setting or None if it does not exist. |
|---|
Note
Strings of numbers are always returned as Integers.
New in version 0.9.
Deletes the specified variable.
| Returns: |
|
|---|
New in version 0.9.
Returns a list of all currently set preferences.
| Return type: | List of Strings |
|---|
New in version 0.9.
Below you will find information about how to work with contexts.
As explained in the Context theory session above, contexts give access to a specific channel/query/server tab of HexChat. Every function available in the xchat module will be evaluated in the current context, which will be specified by HexChat itself before passing control to the module. Sometimes you may want to work in a specific context, and that’s where context objects come into play.
You may create a context object using get_context() or find_context() functions as explained below, or trough the get_list() function, as explained above.
| Return type: | context |
|---|
Finds a context based on a channel and servername.
| Parameters: |
|
|---|---|
| Return type: | context |
cnc = xchat.find_context(channel='#conectiva')
cnc.command('whois niemeyer')
The context object returned by the functions listed above has these methods:
Changes the current context to be the one represented by this context object.
Does the same as the emit_print() function but in the given context.
Does the same as the get_info() function but in the given context.
Does the same as the get_list() function but in the given context.
Maintained by: TingPing
Original Author: Gustavo Niemeyer gustavo@niemeyer.net