mirror of
https://github.com/moparisthebest/hexchat
synced 2024-12-25 00:58:52 -05:00
540 lines
20 KiB
Markdown
540 lines
20 KiB
Markdown
# HexChat Python Interface
|
||
|
||
## Features
|
||
|
||
Here are some of the features of the python plugin interface:
|
||
|
||
- Comprehensive, consistent and straightforward API
|
||
- Load, unload, reload, and autoload support
|
||
- Per plugin independent interpreter state
|
||
- Python interactive console
|
||
- Python interactive command execution
|
||
- Full thread support
|
||
- Stdout and stderr redirected to xchat console
|
||
- Dynamic list management
|
||
- Nice context treatment
|
||
- Plugin preferences
|
||
|
||
## Commands
|
||
|
||
The following commands will be intercepted by the Python Plugin interface module, when it is loaded.
|
||
|
||
---------------------------------------------------------------------------------------------------------------------------------------------
|
||
*Command* *Description*
|
||
---------------------------------- ---------------------------------------------------------------------------------------------------------
|
||
/py load <filename> Load module with given filename.
|
||
|
||
/py unload <filename|module name> Unload module with given filename, or module name.
|
||
|
||
/py reload <filename|module name> Reload module with given filename, or module name.
|
||
|
||
/py list List Python modules loaded.
|
||
|
||
/py exec <command> Execute given Python command interactively. For example:
|
||
`/py exec import xchat`
|
||
`/py exec print xchat.get_info('channel')`
|
||
|
||
/py console 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.
|
||
|
||
/py about Show some information about the Python plugin interface.
|
||
----------------------------------------------------------------------------------------------------------------------------------------------
|
||
|
||
|
||
## Autoloading modules
|
||
|
||
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 your HexChat directory (~/.config/hexchat/addons, %APPDATA%\\HexChat\\addons).
|
||
|
||
## Context theory
|
||
|
||
Before starting to explain what the API offers, I'll do a short
|
||
introduction about the xchat 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 xchat 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 xchat passes control to the
|
||
module. For example, when xchat receives a command in a specific
|
||
channel, and you have asked xchat to tell you about this event, the
|
||
current context will be set to this channel before your module is
|
||
called.
|
||
|
||
## Hello world
|
||
|
||
Here is the traditional *hello world* example.
|
||
|
||
~~~~~~~~~~ {.python}
|
||
__module_name__ = "helloworld"
|
||
__module_version__ = "1.0"
|
||
__module_description__ = "Python module example"
|
||
|
||
print "Hello world!"
|
||
~~~~~~~~~~
|
||
|
||
This module will print "Hello world!" in the xchat 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
|
||
xchat modules.
|
||
|
||
## xchat module
|
||
|
||
The xchat module is your passport to every xchat functionality offered
|
||
by the Python plugin interface. Here's a simple example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
import xchat
|
||
xchat.prnt("Hi everyone!")
|
||
~~~~~~~~~~
|
||
|
||
The following functions are available in the xchat module.
|
||
|
||
### Generic functions
|
||
|
||
#### xchat.prnt(string)
|
||
|
||
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.
|
||
|
||
#### xchat.emit_print(event_name, *args)
|
||
|
||
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 > Lists > Text Events` window.
|
||
Here is one example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
xchat.emit_print("Channel Message", "John", "Hi there", "@")
|
||
~~~~~~~~~~`
|
||
|
||
#### xchat.command(string)
|
||
|
||
Execute the given command in the current context. This has the same
|
||
results as executing a command in the xchat window, but notice that the
|
||
`/` prefix is not used. Here is an example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
xchat.command("server irc.openprojects.net")
|
||
~~~~~~~~~~
|
||
|
||
#### xchat.nickcmp(s1, s2)
|
||
|
||
This function will do an RFC1459 compliant string comparing between `s1`
|
||
and `s2`, and is useful to compare channels and nicknames. It returns an
|
||
integer less than, equal to, or greater than zero if `s1` is found,
|
||
respectively, to be less than, to match, or be greater than `s2`. For
|
||
example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
if xchat.nickcmp(nick, "mynick") == 0:
|
||
print "They are the same!"
|
||
~~~~~~~~~~
|
||
|
||
### Information retreiving functions
|
||
|
||
#### xchat.get_info(type)
|
||
|
||
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:
|
||
|
||
-----------------------------------------------------------------------------------------------
|
||
*Type* *Description*
|
||
-------- -----------------------------------------------------------------------------------
|
||
away Away reason or None if you are not away.
|
||
|
||
channels Channel of the current context.
|
||
|
||
hostname Real hostname of the server you connected to.
|
||
|
||
network Current network name or None.
|
||
|
||
nick Your current nick name.
|
||
|
||
server Current server name (what the server claims to be) or None if you are not connected.
|
||
|
||
topic Current channel topic.
|
||
|
||
version hexchat version number.
|
||
|
||
xchatdir hexchat config directory e.g.: "~/.config/hexchat".
|
||
------------------------------------------------------------------------------------------------
|
||
|
||
Example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
if xchat.get_info("server") is None:
|
||
xchat.prnt("Not connected!")
|
||
~~~~~~~~~~
|
||
|
||
#### xchat.get_prefs(name)
|
||
|
||
Retrieve the xchat setting information specified by the `name` string,
|
||
as available by the `/set` command. For example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
print "Current preferred nick:", xchat.get_prefs("irc_nick1")
|
||
~~~~~~~~~~
|
||
|
||
#### xchat.get_list(type)
|
||
|
||
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 xchat'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 xchat.
|
||
|
||
~~~~~~~~~~ {.python}
|
||
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.
|
||
|
||
This information was
|
||
taken from xchat's plugin documentation. You may find any types not
|
||
listed here, if they exist at all, in an updated xchat documentation.
|
||
Any list types accepted by xchat should be dynamically accepted by the
|
||
Python plugin interface.
|
||
|
||
##### channels
|
||
|
||
The channels list type gives you access to the channels, queries and
|
||
their servers. The folloing attributes are available in each list item:
|
||
|
||
-------------------------------------------------------------------
|
||
*Type* *Description*
|
||
------- -------------------------------------------------------
|
||
channel Channel or query name.
|
||
|
||
context A context object, giving access to that channel/server.
|
||
|
||
network Network name to which this channel belongs.
|
||
|
||
server Server name to which this channel belongs.
|
||
|
||
type Type of context (1=Server, 2=Channel, 3=Dialog).
|
||
-------------------------------------------------------------------
|
||
|
||
##### dcc
|
||
|
||
The dcc list type gives you access to a list of DCC file transfers. The
|
||
following attributes are available in each list item:
|
||
|
||
---------------------------------------------------------------------------------------
|
||
*Type* *Description*
|
||
--------- ---------------------------------------------------------------------------
|
||
address32 Address of the remote user (ipv4 address, as an int).
|
||
|
||
cps Bytes per second (speed).
|
||
|
||
destfile Destination full pathname.
|
||
|
||
file Filename.
|
||
|
||
nick Nickname of person who the file is from/to.
|
||
|
||
port TCP port number.
|
||
|
||
pos Bytes sent/received.
|
||
|
||
resume Point at which this file was resumed (or zero if it was not resumed).
|
||
|
||
size File size in bytes.
|
||
|
||
status DCC status (queued=0, active=1, failed=2, done=3, connecting=4, aborted=5).
|
||
|
||
type DCC type (send=0, receive=1, chatrecv=2, chatsend=3).
|
||
---------------------------------------------------------------------------------------
|
||
|
||
##### users
|
||
|
||
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:
|
||
|
||
----------------------------------------------------------------
|
||
*Type* *Description*
|
||
------ --------------------------------------------------------
|
||
nick Nick name.
|
||
|
||
host Host name in the form user@host (or None, if not known).
|
||
|
||
prefix Prefix character, .e.g: @ or +. Points to a single char.
|
||
----------------------------------------------------------------
|
||
|
||
##### ignore
|
||
|
||
The ignore list type gives you access to the current ignored list. The
|
||
following attributes are available in each list item:
|
||
|
||
-----------------------------------------------------------------------------------------------------------
|
||
*Type* *Description*
|
||
----- ---------------------------------------------------------------------------------------------------
|
||
mask Ignore mask (for example, "*!*@*.aol.com").
|
||
|
||
flags Bit field of flags (0=private, 1=notice, 2=channel, 3=ctcp, 4=invite, 5=unignore, 6=nosave, 7=dcc).
|
||
-----------------------------------------------------------------------------------------------------------
|
||
|
||
### Hook functions
|
||
|
||
These functions allow one to hook into xchat events.
|
||
|
||
#### Priorities
|
||
|
||
When a priority keyword parameter is accepted, it means that this
|
||
callback may be hooked with five different priorities: PRI_HIGHEST,
|
||
PRI_HIGH, PRI_NORM, PRI_LOW, and PRI_LOWEST. The usage of these
|
||
constants, which are available in the xchat module, 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).
|
||
|
||
#### Parameters word and word_eol
|
||
|
||
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!
|
||
|
||
- **word[0]** is `command`
|
||
- **word[1]** is `NICK`
|
||
- **word[2]** is `Hi`
|
||
- **word[3]** is `there!`
|
||
- **word_eol[0]** is `command NICK Hi there!`
|
||
- **word_eol[1]** is `NICK Hi there!`
|
||
- **word_eol[2]** is `Hi there!`
|
||
- **word_eol[3]** is `there!`
|
||
|
||
#### Parameter userdata
|
||
|
||
The parameter userdata, if given, allows you to pass a custom object to
|
||
your callback.
|
||
|
||
#### Callback return constants (EAT_*)
|
||
|
||
When a callback is supposed to return one of the EAT_* macros, it is
|
||
able control how xchat will proceed after the callback returns. These
|
||
are the available constants, and their meanings:
|
||
|
||
---------------------------------------------------------
|
||
*Constant* *Description*
|
||
----------- ---------------------------------------------
|
||
EAT_PLUGIN Don't let any other plugin receive this event.
|
||
|
||
EAT_XCHAT Don't let xchat treat this event as usual.
|
||
|
||
EAT_ALL Eat the event completely.
|
||
|
||
EAT_NONE Let everything happen as usual.
|
||
---------------------------------------------------------
|
||
|
||
Returning `None` is the same as returning `EAT_NONE`.
|
||
|
||
#### xchat.hook_command(name, callback, userdata=None, priority=PRI_NORM, help=None)
|
||
|
||
This function allows you to hook into the name xchat 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. This function returns
|
||
a hook handler which may be used in the `xchat.unhook()` function. For
|
||
example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
def onotice_cb(word, word_eol, userdata):
|
||
if len(word) < 2:
|
||
print "Second arg must be the message!"
|
||
else:
|
||
xchat.command("NOTICE @%s %s" % (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
|
||
xchat's behavior, as explained above.
|
||
|
||
#### xchat.hook_print(name, callback, userdata=None, priority=PRI_NORM)
|
||
|
||
This function allows you to register a callback to trap any print
|
||
events. The event names are available in the *Edit Event Texts* window.
|
||
Parameters `userdata` and `priority` have their meanings explained
|
||
above. This function returns a hook handler which may be used in the
|
||
`xchat.unhook()` function. For example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
def youpart_cb(word, word_eol, userdata):
|
||
print "You have left channel", word[2]
|
||
return xchat.EAT_XCHAT # Don't let xchat do its normal printing
|
||
|
||
xchat.hook_print("You Part", youpart_cb)
|
||
~~~~~~~~~~
|
||
|
||
You may return one of `EAT_*` constants in the callback, to control
|
||
xchat's behavior, as explained above.
|
||
|
||
#### xchat.hook_server(name, callback, userdata=None, priority=PRI_NORM)
|
||
|
||
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. This function returns a
|
||
hook handler which may be used in the `xchat.unhook()` function. For
|
||
example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
def kick_cb(word, word_eol, userdata):
|
||
print "%s was kicked from %s (%s)" % (word[3], word[2], word_eol[4])
|
||
# Don't eat this event, let other plugins and xchat see it too
|
||
return xchat.EAT_NONE
|
||
|
||
xchat.hook_server("KICK", kick_cb)
|
||
~~~~~~~~~~
|
||
|
||
You may return one of `EAT_*` constants in the callback, to control
|
||
xchat's behavior, as explained above.
|
||
|
||
#### xchat.hook_timer(timeout, callback, userdata=None)
|
||
|
||
This function allows you to register a callback to be called every
|
||
timeout milliseconds. Parameters userdata and priority have their
|
||
meanings explained above. This function returns a hook handler which may
|
||
be used in the `xchat.unhook()` function. For example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
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.
|
||
|
||
#### xchat.hook_unload(timeout, callback, userdata=None)
|
||
|
||
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. This function returns a hook
|
||
handler which may be used in the `xchat.unhook()` function. For example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
def unload_cb(userdata):
|
||
print "We're being unloaded!"
|
||
|
||
xchat.hook_unload(unload_cb)
|
||
~~~~~~~~~~
|
||
|
||
#### xchat.unhook(handler)
|
||
|
||
Unhooks any hook registered with the hook functions above.
|
||
|
||
### Plugin preferences
|
||
|
||
You can use pluginpref to easily store and retrieve settings. This was added in the Python plugin version 0.9
|
||
|
||
#### xchat.set_pluginpref(name, value)
|
||
|
||
If neccessary creates a .conf file in the HexChat config dir named addon_python.conf and stores the value in it. Returns 1 on success 0 on failure.
|
||
|
||
> Note: Until the plugin uses different a conf file per script it's recommened to use 'PluginName-SettingName' to avoid conflicts.
|
||
|
||
#### xchat.get_pluginpref(name)
|
||
|
||
This will return the value of the variable of that name. If there is none by this name it will return `None`. Numbers are always returned as Integers.
|
||
|
||
#### xchat.del_pluginpref(name)
|
||
|
||
Deletes specified variable. Returns 1 on success (or never existing), 0 on failure.
|
||
|
||
#### xchat.list_pluginpref()
|
||
|
||
Returns a list of all currently set preferences.
|
||
|
||
### Context handling
|
||
|
||
Below you will find information about how to work with contexts.
|
||
|
||
#### Context objects
|
||
|
||
As explained in the Context theory session above, contexts give access
|
||
to a specific channel/query/server tab of xchat. Every function
|
||
available in the xchat module will be evaluated in the current context,
|
||
which will be specified by xchat 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 the `xchat.get_context()` or
|
||
`xchat.find_context()`, functions as explained below, or trough the
|
||
`xchat.get_list()` function, as explained in its respective session.
|
||
|
||
Each context object offers the following methods:
|
||
|
||
-------------------------------------------------------------------------------------------------------------------------
|
||
*Methods* *Description*
|
||
---------------------------------------- -----------------------------------------------------------------------------
|
||
context.set() Changes the current context to be the one represented by this context object.
|
||
|
||
context.prnt(string) Does the same as the xchat.prnt() function, but in the given context.
|
||
|
||
context.emit_print(event_name, *args) Does the same as the emit_print() function, but in the given context.
|
||
|
||
context.command(string) Does the same as the xchat.command() function, but in the given context.
|
||
|
||
context.get_info(type) Does the same as the xchat.get_info() function, but in the given context.
|
||
|
||
context.get_list(type) Does the same as the xchat.get_list() function, but in the given context.
|
||
-------------------------------------------------------------------------------------------------------------------------
|
||
|
||
#### xchat.get_context()
|
||
|
||
Returns a context object corresponding the the current context.
|
||
|
||
#### xchat.find_context(server=None, channel=None)
|
||
|
||
Finds a context based on a channel and servername. If `server` is
|
||
`None`, it finds any channel (or query) by the given name. If `channel`
|
||
is `None`, it finds the front-most tab/window of the given server. For
|
||
example:
|
||
|
||
~~~~~~~~~~ {.python}
|
||
cnc = xchat.find_context(channel='#conectiva')
|
||
cnc.command('whois niemeyer')
|
||
~~~~~~~~~~
|
||
|
||
* * * * *
|
||
|
||
Original Author: Gustavo Niemeyer [gustavo@niemeyer.net](mailto:gustavo@niemeyer.net)
|
||
|
||
For purty html: `pandoc --toc python.md -s --highlight-style haddock -o python.html`
|