diff options
Diffstat (limited to 'share/doc/python.md')
| -rw-r--r-- | share/doc/python.md | 545 |
1 files changed, 545 insertions, 0 deletions
diff --git a/share/doc/python.md b/share/doc/python.md new file mode 100644 index 00000000..d998f9d3 --- /dev/null +++ b/share/doc/python.md @@ -0,0 +1,545 @@ +# 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` |