Core bots

General-purpose bots

SocketBot

This generic bot is mostly inspired from this Gist. It also handles system's proxy settings using an implementation inspired from this recipe.

It can be instantiated using the following arguments:

Argument	Default	Description
host		Hostname or IP address
port		Port number
disp	False	Display all exchanged messages
verbose	False	Verbose mode
prefix	False	Prefix messages for display (i.e. [SRC] for the server, [BOT] for the bot)
no_proxy	False	Force ignoring system proxy settings

When a SocketBot is instantiated, it only registers the input arguments as attributes and creates an empty buffer for collecting the received data. In order to initiate a communication, the connect method must be used. This way, the associated socket can be reconnected or connections to other remote hosts can be made with the same bot.

For communicating, the bot has six methods:

• write: for writing to the socket (using, by default, "\n" as the EOL character)
• send: alias for write
• read: for reading on the socket a given length of bytes
• read_until: for reading blocks until a given pattern is reached
• receive: alias for read and read_until
• send_receive: for combining write then read_until

Each time a read/write method is used, it returns the collected data.

An example of use of the SocketBot class is the Netcat bot (see next section).

WebBot

This generic bot aims to handle an HTTP session using predefined headers and relies on the requests library. It holds a _request attribute with the requests.Request instance and a response attribute with the requests.Response one. It has also a method for setting a cookie.

It can be instantiated using the following arguments:

Argument	Default	Description
url		URL of the website (e.g. http://example.com)
verbose	False	Verbose mode
no_proxy	False	Force ignoring system proxy settings

For communicating, the bot has a few methods (the first being generic and the others being particularization of the first):

• request: generic method for requesting resources, holding a method argument for defining the HTTP method to be used
• get, post, header, options, put, delete: request method using method=...

At instantiation, HTTP-related methods are dynamically bound so that get, post, header, options, put and delete become available.

---

Protocol-related bots

TCPBot

This bot implements a Netcat-like bot that handles a single connection with a remote host, by default executing a preamble that reads from the server up to the first newline and displays the received data.

Here is an example:

with TCPBot(ip_address, port) as nc:
    nc.write("Hello !")

Another example, redefining the preamble, writing with a different EOL character:

class MyBot(TCPBot):
    def preamble(self):
        self.read_until(">")

with MyBot(ip_address, port) as nc:
    nc.write("dir", eol="\r\n")

IRCBot

This bot aims to manage conversations on an IRC server using a msg method. It connects and sends user's data (by default, the nickname is ircbot and the full name is IRC Bot). It then executes the user-defined preamble and finally tries to connect to the input channel.

class MyIRCBot(IRCBot):
    def preamble(self):
        self.msg("hellosrv", "HELLO")

with MyIRCBot(ip_address, port, channel="#a_channel") as irc:
    irc.msg("all", "Hello world!")

HTTPbot

This bot is an inherited class of the WebBot in that it adds a parsing of the current response using BeautifulSoup, stored in a new soup attribute.

with HTTPBot(url) as bot:
    bot.get("/")
    print(bot.soup.prettify())

JSONBot

This bot is an inherited class of the WebBot in that it adds a parsing of the current response using the json built-in module, stored in a new json attribute. Also, while initializing, it automatically adds the right Content-Type HTTP header so that the bot communicates with JSON objects.

with JSONBot(url) as bot:
    bot.get("/")
    print(bot.json)

---

API definition classes

API

This class allows to define RESTful API's using HTTP or JSON. It handles caching of request results for sparing exchanges with the remote API's. This is done in combination with multiple method decorators that aim to successfully communicate.

Name	Parameters	Description
apicall		This flags a method as an API call ; required for caching
cache	duration (seconds)	This allows to define a caching duration after which the entry is expired and removed
invalidate	other_function	This
private		This is aimed to flag a method as only usable in private (or paid, or with an API plan) mode
time_throttle	min_duration, max_duration, n_requests	defines time throttling

SearchAPI