xenofem/python-zulip-api
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

docs: improve docs for contrib_bots.

Browse source
This commit is contained in:
Vamshi Balanaga 2017-01-08 09:59:13 -05:00 committed by Tim Abbott
parent 0b765c0370
commit 87aa2c5b3b
1 changed files with 21 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
contrib_bots/lib/readme.md
View file

@ -1,4 +1,4 @@
# Overview # Contrib Bots:
This is the documentation for an experimental new system for writing This is the documentation for an experimental new system for writing
bots that react to messages. bots that react to messages.
@ -9,13 +9,12 @@ bots that react to messages sent by users.
This document explains how to run the code, and it also This document explains how to run the code, and it also
talks about the architecture for creating bots. talks about the architecture for creating bots.
## Design goals ## Design Goals
The goal is to have a common framework for hosting a bot that reacts The goal is to have a common framework for hosting a bot that reacts
to messages in any of the following settings: to messages in any of the following settings:
* Run as a long-running process using `call_on_each_event` * Run as a long-running process using `call_on_each_event`.
(implemented today).
* Run via a simple web service that can be deployed to PAAS providers * Run via a simple web service that can be deployed to PAAS providers
and handles outgoing webhook requests from Zulip. and handles outgoing webhook requests from Zulip.
@ -24,7 +23,11 @@ to messages in any of the following settings:
which would be done for high quality, reusable bots; we would have a which would be done for high quality, reusable bots; we would have a
nice "bot store" sort of UI for browsing and activating them. nice "bot store" sort of UI for browsing and activating them.
## Running bots * Run locally by our technically inclined users for bots that require
account specific authentication, for example: a gmail bot that lets
one send emails directly through Zulip.
## Running Bots
Here is an example of running the "follow-up" bot from Here is an example of running the "follow-up" bot from
inside a Zulip repo (and in your remote instance): inside a Zulip repo (and in your remote instance):
@ -53,6 +56,8 @@ page to create a user-owned bot.
key=<your api key> key=<your api key>
site=https://zulip.somewhere.com site=https://zulip.somewhere.com
When you run your bot, make sure to point it to the correct location
of your `.zuliprc`.
### Third Party Configuration ### Third Party Configuration
@ -66,7 +71,10 @@ information anywhere in your Zulip directory. Instead,
create a separate configuration file for the third party's create a separate configuration file for the third party's
configuration in your home directory. configuration in your home directory.
### Python dependencies Any bots that require this will have instructions on
exactly how to create or access this information.
### Python Dependencies
If your module requires Python modules that are not either If your module requires Python modules that are not either
part of the standard Python library or the Zulip API part of the standard Python library or the Zulip API
@ -100,13 +108,13 @@ Each bot library simply needs to do the following:
`triage_message`, and `handle_message`. `triage_message`, and `handle_message`.
- Set `handler_class` to be the name of that class. - Set `handler_class` to be the name of that class.
(We make this a two-step process, so that you can give (We make this a two-step process to reduce code repetition
a descriptive name to your handler class.) and to add abstraction.)
## Portability ## Portability
Creating a handler class for each bot allows your bot Creating a handler class for each bot allows your bot
code to be more portable. For example, if you want to code to be more portable. For example, if you want to
use your bot code in some other kind of bot platform, then use your bot code in some other kind of bot platform, then
if all of your bots conform to the `handler_class` protocol, if all of your bots conform to the `handler_class` protocol,
you can write simple adapter code to use them elsewhere. you can write simple adapter code to use them elsewhere.
@ -128,6 +136,7 @@ in a server-side environment.
## Other approaches ## Other approaches
If you are not interested in running your bots on the If you are not interested in running your bots on the
server, then you can still use the full Zulip API. The server, then you can still use the full Zulip API and run
hope, though, is that this architecture will make them locally. The hope, though, is that this
writing simple bots a quick/easy process. architecture will make writing simple bots a quick/easy
process.