Modpython

Modpython allows you to use modules written on python 3.

Compiling

First, you need to use ./configure with option --enable-python.

To build modpython, you need some files produced by SWIG. They are not shipped with ZNC because of huge size (several megabytes). There're 2 ways to get them:

1. Install swig. Needed files will be generated automatically when you run make in znc source dir to compile znc.
2. Download and unpack these files to <znc-source>/modules/modpython/ (_znc_core.cpp and modpython.i should be in the same dir), and add option --disable-swig to ./configure

Usage

Loading and unloading of python3 modules is similar to C++ modules. For example, you can use /znc loadmod or webadmin.

If you unload modpython, all python modules are automatically unloaded too.

Arguments

This global module takes no arguments.

Read loading modules to learn more about loading modules.

Writing new python3 modules

Basics

Every python module is file named like modulename.py (.pyc and .so are supported too, but I doubt that you want to write ZNC module as C python extension ;) ) and is located in usual modules directories. The file must contain class with exactly the same name as the module itself. The class should be derived from znc.Module.

# pythonexample.py

import znc

class pythonexample(znc.Module):
    description = "Example python3 module for ZNC"

    def OnChanMsg(self, nick, channel, message):
        self.PutModule("Hey, {0} said {1} on {2}".format(nick.GetNick(), message.s, channel.GetName()))
        return znc.CONTINUE

All callbacks have the same name as in C++, and have the same arguments, but with reference to self before first argument, as usually in python.

def OnShutdown is used as destructor (instead of python's __del__). OnShutdown is called when the module is going to be unloaded.

If a callback returns None, a reasonable default is substituted. If a callback raises an exception, the default value is assumed too.

When a module callback should return CModule::EModRet, you can use values as znc.CModule.CONTINUE or just znc.CONTINUE.

ZNC C++ API can be found here. Most of it should just work for python modules. The following text describes mostly features, differences and caveats.

Strings

All ZNC classes are accessible from python with znc. prefix. The exception is CString. All uses of CString by value is transparently translated to/from python string objects.

// C++
void Foo(const CString& s);

# python
znc.Foo("bar")

The same for case where you get CString by value:

// C++
class CModule {
    ...
    virtual bool OnLoad(const CString& sArgsi, CString& sMessage);
};

# python
class foo(znc.Module):
    def OnLoad(self, args, message):
        if args == "bar":
            return True
        return False

If you need to use CString by reference, use class znc.String and its attribute s:

// C++
void Foo(CString& s) {
    s = "bar";
}

# python
x = znc.String()
znc.Foo(x);
print(x.s); # prints 'bar' to stdout

The same if you get CString& as argument:

// C++
class CModule {
    ...
    virtual bool OnLoad(const CString& sArgsi, CString& sMessage);
};

# python
class foo(znc.Module):
    def OnLoad(self, args, message):
        message.s = 'bar'
        return True

Note: don't try to use the string which you got in the overloaded method for calls to other methods

# C++
class CModule {
    virtual void OnFoo(CString& sMsg);
    void Bar(CString& sMsg); // appends "Bar" to sMsg
}

# python, wrong way
class foo(znc.Module):
    def OnFoo(self, msg):
        self.Bar(msg) # ZNC crashes here

# python
class foo(znc.Module):
    def OnFoo(self, msg):
        s = znc.String()
        s.s = msg.s # so that old value is preserved
        self.Bar(s)
        msg.s = s.s # put result back to msg

So, you want to override a hook void OnFoo(const CString& sBar) and you actually don't want to write to sBar. So you probably will want to use the argument as python string. But, let's assume that in next ZNC version OnFoo's signature will be changed to void OnFoo(CString& sBar). This will break your module! To be on safe side, convert the argument to string with usual str() function. (Note: support for str() was added in ZNC 0.099)

// C++
class CModule {
    ...
    virtual bool OnLoad(const CString& sArgs, CString& sMessage);
    virtual EModRet OnRaw(CString& sLine);
};

# python
class foo(znc.Module):
    def OnLoad(self, args, message):
        if str(args).startswith('bar'):
            ...
    def OnRaw(self, line):
        if str(line).startswith('bar'):
            ...

Module's NV

module.nv is a dict-like object, which can be used as normal dict, but stores it's data on disk. Both keys and values should be strings.

class foo(znc.Module):
    def OnLoad(self, args, message):
        self.nv['bar'] = 'baz'
        if 'abcde' in self.nv:
            try:
                message.s = self.nv['qwerty']
            except KeyError:
                message.s = self.nv['abcde']
        for k, v = self.nv.items():
            ...

Web

To show your module's page or subpages in the menu, need to define GetWebMenuTitle which should return visual name for the module.

class test(znc.Module):
    def GetWebMenuTitle(self):
        return "Python test module"

CTemplate

Probably need to explain here that it's not CGI and where to write HTML?

Instead of operator[] use set:

// C++
CTemplate& tmpl = ...;
tmpl["name"] = "value";
CTemplate& row = tmpl.AddRow("SomeTable");
row["foo"] = "bar";

# python equivalent
tmpl = ...;
tmpl.set("name", "value")
row = tmpl.AddRow("SomeTable")
row.set("foo", "bar")

Subpages

If you want to have subpages for the module, besides the main page, use helper function znc.CreateWebSubPage. It accepts one required argument - name of the subpage, and several optional arguments:

• title - text for displaying subpage name. By default it's the same as name.
• params - dict of parameters which will be used in URL linking to the subpage.
• admin - set to True if subpage should be accessible only by admins.

def OnLoad(self, args, message):
    self.AddSubPage(znc.CreateWebSubPage('page1'));
    self.AddSubPage(znc.CreateWebSubPage('page2', title='Page N2'))
    self.AddSubPage(znc.CreateWebSubPage('page3', params=dict(var1='value1', var2='value2'), admin=True))
    return True

Timers

Use helper function CreateTimer. It gets following arguments:

• timer (required) - reference to your Timer class. It should be derived from znc.Timer. You can override 2 methods: RunJob and OnShutdown.
• interval - Interval between calls, in seconds. Default is 10.
• cycles - Number of times to run the RunJob function. 0 means infinite. Default is 1.
• description - Text description of the timer. Default doesn't matter.

# timertest.py
import znc

class testtimer(znc.Timer):
    def RunJob(self):
        self.GetModule.PutStatus('foo {0}'.format(self.msg))

class timertest(znc.Module):
    def OnModCommand(self, cmd):
        timer = self.CreateTimer(testtimer, interval=4, cycles=1, description='Says "foo bar" after 4 seconds')
        timer.msg = 'bar'

You can use methods of C++ class CTimer (like Stop) for your timer.

Sockets

If module needs to know whether ZNC was compiled with IPv6, SSL and c-ares support, you can use special variables, which are True if the feature is supported.

if znc.HaveIPv6:
    ...
if znc.HaveSSL:
    ...
if znc.HaveCAres:
    ...

All sockets are instances of special classes derived from znc.Socket. znc.Socket has all the same methods as Csock, except Connect, Listen and Write. Csock's reference can be found here. To get reference to associated module, use GetModule. Callbacks have different names from ones of Csock, they are described later.

To create socket, use module's method CreateSocket. First argument is reference to your socket class. The function creates socket and calls method Init of it with the rest of arguments. Reference to the new socket is returned.

To connect socket, use method Connect. It gets 2 required arguments - hostname and port, and several optional arguments:

• timeout - Time in seconds to wait for connection. Default is 60.
• ssl - Whether to use SSL for connection.
• bindhost - Local interface to use for the connection.

Returns true value if connection scheduled successfully.

# networkconn.py
import znc
class connsock(znc.Socket):
    def Init(self, line): # line and other arguments, including named arguments can be specified in CreateSocket
        self.Connect('google.com', 80)
        self.EnableReadLine()
        self.Write("{0}\r\n".format(line))
    def OnReadLine(self, line):
        self.GetModule().PutStatus(line) # this puts also \n and \r to status, which is not very good, but this is just an example, so...

class networkconn(znc.Module):
    def OnModCommand(self, cmd):
        sock = self.CreateSocket(connsock, "GET {0} HTTP/1.0\r\n".format(cmd))

# socketconn.py
import znc
class conn(znc.Socket):
    def OnReadLine(self, line):
        self.GetModule().PutStatus(line)

class socketconn(znc.Module):
    def OnModCommand(self, cmd):
        sock = self.CreateSocket(conn)
        sock.Connect('google.com', 443, ssl=True)
        sock.EnableReadLine()
        sock.Write("GET {0} HTTP/1.0\r\n\r\n".format(cmd))

To create listening socket, use method Listen. It gets following optional named arguments:

• port - Port number to listen on. If not presented, random port is choosed.
• bindhost - Interface to listen on. If not presented, socket will listen on all interfaces.
• addrtype - Chooses protocol family. Possible values are 'all', 'ipv4' and 'ipv6'. Default is all.
• ssl - Whether to use SSL for incoming connections.
• maxconns - Maximum number of connections. Default is SOMAXCONN.
• timeout - time in seconds, for timeout.

Returns 0 on error and port number on success.

# listmodule.py
import znc

class accepted(znc.Socket):
    def Init(self, host, port):
        self.Write("Hello, {0}:{1}!\n".format(host, port))
    def OnReadData(self, data):
        self.WriteBytes(data) # echo back everything

class listensock(znc.Socket):
    def OnAccepted(self, host, port):
        return self.GetModule().CreateSocket(accepted, host, port)

class listmodule(znc.Module):
    def OnLoad(self, args, message):
        sock = self.CreateSocket(listensock)
        port = sock.Listen(ssl=True, addrtype='ipv6');
        if port > 0:
            message.s = "Listening on all IPv6 interfaces on port {0} using SSL".format(port)

Use Write to write strings, and WriteBytes to write binary data.

Sockets can override following callbacks:

• Init - is called from CreateSocket, first argument is reference to socket, the rest is from arguments to CreateSocket.
• OnConnected
• OnDisconnected
• OnTimeout
• OnConnectionRefused
• OnReadData - gets bytes as second argument
• OnReadLine - is called for every new line from socket. The line, including ending \n (or \r\n) is in argument. It's called only if you enabled this feature for the socket.
• OnAccepted - is called for listening socket for every new connection. Arguments are hostname and port of remote end. The callback should return None if you don't need the connection, or reference to new socket, which will be used for this connection.
• OnShutdown - destructor of the socket.

If callback On* raises an exception, the socket is closed, but if you want to close socket, use method Close instead. If Init raises an exception, behavior is undefined.

Getting ZNC version

If you just want to show ZNC version to humans, usually just znc.CZNC.GetTag() is good.

znc.CZNC.GetTag() # Returns, for example, 'ZNC 0.097 - http://znc.sourceforge.net'

Check ZNC C++ documentation for details.

For getting ZNC version, you can use read following variables:

znc.Version # For example, number 0.097
znc.VersionMajor # 0
znc.VersionMinor # 97
znc.VersionExtra # build-specific string

Module providers

Hopefully, nobody will ever need this. And it's black magic, so don't use it unless you're black magician :)

So, some lyrics first. What is modpython? It's just a C++ module, but it's able to provide some stuff (actally, .py files) as ZNC modules. So it's some kind of module provider, as it makes some unknown to C++ stuff (those .py files) to be visible in webadmin, in /znc listmods, /znc listavailmods as normal ZNC modules.

Modpython does it using module hooks OnModuleLoading, OnModuleUnloading, OnGetModInfo and OnGetAvailableMods.

The good news is that since 0.207 you can override those hooks too in your global python modules. (TOOD: except OnGetAvailableMods, which will work soon too).

TODO: here comes the example of simple module provider