|
1 | | -# Contrib bots |
2 | | - |
3 | | -This is the documentation for an experimental new system for writing |
4 | | -bots that react to messages. It explains how to run the code, and also |
5 | | -talks about the architecture for creating such bots. |
6 | | - |
7 | | -This directory contains library code for running them. |
8 | | - |
9 | | -## Design goals |
10 | | - |
11 | | -The goal is to have a common framework for hosting a bot that reacts |
12 | | -to messages in any of the following settings: |
13 | | - |
14 | | -* Run as a long-running process using `call_on_each_event`. |
15 | | - |
16 | | -* Run via a simple web service that can be deployed to PAAS providers |
17 | | - and handles outgoing webhook requests from Zulip. |
18 | | - |
19 | | -* Embedded into the Zulip server (so that no hosting is required), |
20 | | - which would be done for high quality, reusable bots; we would have a |
21 | | - nice "bot store" sort of UI for browsing and activating them. |
22 | | - |
23 | | -* Run locally by our technically inclined users for bots that require |
24 | | - account specific authentication, for example: a gmail bot that lets |
25 | | - one send emails directly through Zulip. |
26 | | - |
27 | | -## Installing |
28 | | - |
29 | | -To install the bots and bots API, run: |
30 | | - |
31 | | - python setup.py install |
32 | | - |
33 | | -## Running bots |
34 | | - |
35 | | -Here is an example of running the "follow-up" bot: |
36 | | - |
37 | | - zulip-run-bot followup --config-file ~/.zuliprc-prod |
38 | | - |
39 | | -Once the bot code starts running, you will see a |
40 | | -message explaining how to use the bot, as well as |
41 | | -some log messages. You can use the `--quiet` option |
42 | | -to suppress these messages. |
43 | | - |
44 | | -The bot code will run continuously until you end the program with |
45 | | -control-C (or otherwise). |
46 | | - |
47 | | -### Zulip configuration |
48 | | - |
49 | | -For this document we assume you have some prior experience |
50 | | -with using the Zulip API, but here is a quick review of |
51 | | -what a `.zuliprc` files looks like. You can connect to the |
52 | | -API as your own human user, or you can go into the Zulip settings |
53 | | -page to create a user-owned bot. |
54 | | - |
55 | | - [api] |
56 | | - |
57 | | - key=<your api key> |
58 | | - site=https://zulip.somewhere.com |
59 | | - |
60 | | -When you run your bot, make sure to point it to the correct location |
61 | | -of your `.zuliprc`. |
62 | | - |
63 | | -### Third party configuration |
64 | | - |
65 | | -If your bot interacts with a non-Zulip service, you may |
66 | | -have to configure keys or usernames or URLs or similar |
67 | | -information to hit the other service. |
68 | | - |
69 | | -Do **NOT** put third party configuration information in your |
70 | | -`.zuliprc` file. Do not put third party configuration |
71 | | -information anywhere in your Zulip directory. Instead, |
72 | | -create a separate configuration file for the third party's |
73 | | -configuration in your home directory. |
74 | | - |
75 | | -Any bots that require this will have instructions on |
76 | | -exactly how to create or access this information. |
77 | | - |
78 | | -### Python dependencies |
79 | | - |
80 | | -If your module requires Python modules that are not either |
81 | | -part of the standard Python library or the Zulip API |
82 | | -distribution, we ask that you put a comment at the top |
83 | | -of your bot explaining how to install the dependencies/modules. |
84 | | - |
85 | | -Right now we don't support any kind of automatic build |
86 | | -environment for bots, so it's currently up to the users |
87 | | -of the bots to manage their dependencies. This may change |
88 | | -in the future. |
89 | | - |
90 | | -## Architecture |
91 | | - |
92 | | -In order to make bot development easy, we separate |
93 | | -out boilerplate code (loading up the Client API, etc.) |
94 | | -from bot-specific code (actions of the bot/what the bot does). |
95 | | - |
96 | | -All of the boilerplate code lives in `../run.py`. The |
97 | | -runner code does things like find where it can import |
98 | | -the Zulip API, instantiate a client with correct |
99 | | -credentials, set up the logging level, find the |
100 | | -library code for the specific bot, etc. |
101 | | - |
102 | | -Then, for bot-specific logic, you will find `.py` files |
103 | | -in the `lib` directory (i.e. the same directory as the |
104 | | -document you are reading now). |
105 | | - |
106 | | -Each bot library simply needs to do the following: |
107 | | - |
108 | | -- Define a class that supports the methods `usage` |
109 | | -and `handle_message`. |
110 | | -- Set `handler_class` to be the name of that class. |
111 | | - |
112 | | -(We make this a two-step process to reduce code repetition |
113 | | -and to add abstraction.) |
114 | | - |
115 | | -## Portability |
116 | | - |
117 | | -Creating a handler class for each bot allows your bot |
118 | | -code to be more portable. For example, if you want to |
119 | | -use your bot code in some other kind of bot platform, then |
120 | | -if all of your bots conform to the `handler_class` protocol, |
121 | | -you can write simple adapter code to use them elsewhere. |
122 | | - |
123 | | -Another future direction to consider is that Zulip will |
124 | | -eventually support running certain types of bots on |
125 | | -the server side, to essentially implement post-send |
126 | | -hooks and things of those nature. |
127 | | - |
128 | | -Conforming to the `handler_class` protocol will make |
129 | | -it easier for Zulip admins to integrate custom bots. |
130 | | - |
131 | | -In particular, `run.py` already passes in instances |
132 | | -of a restricted variant of the Client class to your |
133 | | -library code, which helps you ensure that your bot |
134 | | -does only things that would be acceptable for running |
135 | | -in a server-side environment. |
136 | | - |
137 | | -## Other approaches |
138 | | - |
139 | | -If you are not interested in running your bots on the |
140 | | -server, then you can still use the full Zulip API and run |
141 | | -them locally. The hope, though, is that this |
142 | | -architecture will make writing simple bots a quick/easy |
143 | | -process. |
| 1 | +# Zulip bots |
| 2 | + |
| 3 | +This directory contains the source code for the `zulip_bots` PyPI package. |
| 4 | + |
| 5 | +The Zulip documentation has guides on [using Zulip's bot system]( |
| 6 | +http://zulip.readthedocs.io/en/latest/running-bots-guide.html) |
| 7 | +and [writing your own bots]( |
| 8 | +http://zulip.readthedocs.io/en/latest/writing-bots-guide.html). |
| 9 | + |
| 10 | +## Directory structure |
| 11 | + |
| 12 | +```shell |
| 13 | +zulip_bots # This directory |
| 14 | +├───zulip_bots # `zulip_bots` package. |
| 15 | +│ ├───bots/ # Actively maintained and tested bots. |
| 16 | +│ ├───bots_unmaintained/ # Unmaintained, potentially broken bots. |
| 17 | +│ ├───lib.py # Backbone of run.py |
| 18 | +│ ├───provision.py # Creates a development environment. |
| 19 | +│ ├───run.py # Used to run bots. |
| 20 | +│ ├───test_lib.py # Backbone for bot unit tests. |
| 21 | +│ ├───test_run.py # Unit tests for run.py |
| 22 | +│ └───zulip_bot_output.py # Used to test bots in the command line. |
| 23 | +├───generate_manifest.py # Helper-script for packaging. |
| 24 | +└───setup.py # Script for packaging. |
| 25 | +``` |
0 commit comments