Tech Art Bits: Getting started with Clacks

clacks (find it here on github: https://github.com/MaVCArt/clacks) is a modular TCP framework, designed to be as extensible as possible through the user of various factory-pattern and class-composition-inspired techniques. 

In this article, we'll go through a step-by-step guide on how to set up your own server instance in a native python interpreter, and how to attach your code to it through the ServerInterface class, which comes built-in with the vanilla clacks environment.

This is repeated at the end of the article, but if you want to skip right to the end and just download the code, you can do so here:

https://github.com/MaVCArt/clacks_tutorials/tree/main/01_GettingStarted

Table of Contents

Step 1: setting up the server

First, run the following pip command to install the clacks library;

pip install git+https://github.com/MaVCArt/clacks.git@main

This will install the default library, with all the bits and pieces you will need to get a fully functional server instance running in a Python terminal. Next, let's see if our installation was successful; run the following code in a python interpreter.

Congratulations! You're now on your way to create your first Clacks server! The instance you just created doesn't do much, of course - you haven't attached any of your functionalities to it. However, Clacks comes with several pre-built interfaces out of the box, so in this example we've added the "standard" interface, for convenience.

Step 2: Setting up the Proxy

Next, we have to learn to talk to our server. While some of Clacks' extension libraries make this easy enough that you don't need clacks itself to talk to them, for the sake of this example we will not involve those yet. 

In bog-standard clacks, you will need to use the ClientProxyBase class to communicate with a server instance. The rule set is simple; to communicate with a server, find out which handler you're talking to it through. As stated in "the zen of Clacks", each server instance can have an infinite number of handlers, but only one handler/marshaller combination can listen to or speak to one port at the same time. 

Thus, to talk to our "simple" handler, which uses a SimpleRequestHandler class as its handler, and the SimplePackageMarshaller class as its marshaller, you will need the same handler/marshaller combination on the proxy side to talk to that handler. Let's illustrate by doing this.

Simple, right? So, that gets us up and running with a simple server/proxy setup. On to the last step, adding your own methods!

Step 3: Create your own interface

The last step to exposing your own methods to the server is to create your own Interface class. This class needs to inherit from the clacks.ServerInterface base class, but other than that there aren't too many requirements. As you can see below, creating your own interface is incredibly easy. Simply inherit the clacks.ServerInterface base class, and you're on your way implementing as much behaviour as you want.

Step 4: Attaching the interface to the server

Returning to our earlier example, we can now import our custom interface (which we saved in a file called "interface.py" next to this snippet), and attach it to the server. You can use the "register_interface" method on the server class for this. As you can see, because have not registered this interface class as a library-available Interface class, we have to manually register the interface instance itself. But as you can see, this makes little difference.

Download the code

And that's it! Thanks for getting this far, and if you wish, you can download all the code in this article from github from the "clacks_tutorials" github repository, linked below. 

https://github.com/MaVCArt/clacks_tutorials/tree/main/01_GettingStarted