-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.txt
211 lines (165 loc) · 6.88 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
========
Yardbird
========
------------------------------
A Django-based Chat Bot System
------------------------------
::
,__, (Anthropology!)
,' `. /
/`-, @ `__
| `-, ,'\
| `-,
| / `-,
\ | / `,
`._ `-' ,'
`-....-'
/
(__
What It Is
==========
Yardbird is a Python package that allows you to write IRC chat bots using
Django. Internally it uses Twisted Python to provide a sort of "IRC client
runserver" that dispatches incoming messages to your Django apps. This
saves you from having to ever see or touch Twisted code, and lets you use
Django models and templates in your bot.
How to Get It
=============
* The latest source tarballs can be downloaded from
https://launchpad.net/yardbird/+download
* Packages for Ubuntu (the repository works with Hardy or later) are
available from https://launchpad.net/~spacehobo/+archive/ppa
where you can install the ``python-django-yardbird`` and
``python-yardbird-iotower`` packages.
How to Develop It
-----------------
Development of both the Yardbird chatbot system and the IOTower example app
is done from a single bazaar_ tree. To get access to the development tree,
simply run::
bzr branch lp:yardbird
...and you will have a complete source tree with the ``yardbird`` and
``iotower`` packages as well as an example Django IRC Bot setup.
.. _bazaar: http://bazaar-vcs.org/
How to Install
==============
If you are using the PPA or other provided packages, you're all set!
Otherwise, you can either use the provided ``setup.py`` to install the
``yardbird/`` package into your ``PYTHONPATH``, or copy/link the yardbird/
tree directly into your project as an application, like so::
example/
|-- __init__.py
|-- manage.py
|-- settings.py
|-- testapp
| |-- __init__.py
| |-- models.py
| `-- views.py
|-- urls.py
`-- yardbird
|-- __init__.py
...
Now you're ready to write some IRC dispatchers and views!
How to Run
==========
The ``yardbird`` app inculdes a ``runircbot`` management command, so that
you can simply::
./manage.py runircbot
and it will connect according to the ``IRC_CHANNELS`` variable from
``settings.py``. ``IRC_CHANNELS`` is a sequence of ``irc://`` or
``ircs://`` urls, like the following::
IRC_CHANNELS = (
'ircs://nerdbird:[email protected]:6697/privileged/#yardbird',
'ircs://irc.slashnet.org:6697/#birdland',
u'ircs://irc.slashnet.org:6697/#\u2615', # unicode teacup
'ircs://[email protected]:6697/#yardbird?cert=/home/example/keys/yardbird.cert&key=/home/example/keys/yardbird.key',
)
The above will connect to Slashnet_ via SSL, with nickname ``nerdbird``
and server password ``password``. Since Slashnet_ passes the server
password through to NickServ, this avoids the need for a special
NickServ application. The first line also joins ``#yardbird`` and notes
that it is *privileged*, meaning that the operators in that channel may
use restricted commands.
The next two channels (``#birdland`` and ``#☕``) are part of the same
connection, so they use the same settings that #yardbird did.
The last entry is an SSL connection to OFTC_ with the nickname
``examplebot``. OFTC `uses SSL user certificates`_ to authenticate to
NickServ, so the query string specifies where the certificate and key
files are to be found.
In addition to ``IRC_CHANNELS``, you must set ``ROOT_MSGCONF`` to the
module that contains ``privmsg`` and any other IRC events that you want
your bot to handle. Typically it mimics ``ROOT_URLCONF`` like so::
ROOT_URLCONF = 'example.urls'
ROOT_MSGCONF = 'example'
.. _Slashnet: http://www.slashnet.org/
.. _OFTC: http://www.oftc.net/
.. _uses SSL user certificates: http://www.oftc.net/oftc/NickServ/CertFP
How to Code for Yardbird
========================
Writing apps for Yardbird, or hooking existing Web apps into Yardbird, is
similar to writing ordinary Django apps. The key differences are as
follows:
1. There are multiple message types, so in place of `urls.py`, you
will have a number of dispatchers: one for each message type you
wish to handle.
2. Since IRC is not HTTP, the request and response objects are
different, and new shortcuts are provided.
3. A different set of signals exists for the IRC request
start/finish events. Model signals, however, remain the same.
Dispatchers
-----------
The key dispatchable events are as follows:
:privmsg: Normal messages sent either privately or in a
channel
:action: "Emotes" sent using the /me command
:topic: Changes to a channel's topic
:nick: Changes in a user's nickname
Typical bots are only interested in the ``privmsg`` and possibly ``action``
events. As an example, a bot that wished to treat them both the same would
create a ``privmsg.py`` in the directory specified by
``settings.ROOT_MSGCONF`` with a standard Django ``urlpatterns`` structure,
and would then symlink ``actions.py`` to the privmsg dispatcher.
It is recommended that you keep IRC-specific views in a separate package.
The Yardbird maintainers use ``ircviews.py``, but anything will do.
Request and Response Objects
----------------------------
The ``IRCRequest`` and ``IRCResponse`` objects in the ``yardbird.irc``
module are notably simpler than their HTTP counterparts. They effectively
behave as simple structs, with only a little initialization logic.
While HTTP Django assumes that any successful response will be an HTTP 200
code, IRC responses must specify which mechanism the reply will use.
Currently the options are:
:PRIVMSG: To reply as IRC 'speech' either privately or in a
channel
:ACTION: To reply with the description of an action, as with
the /me command in most clients.
:NOTICE: To reply with a CTCP NOTICE that is clearly the
result of an automated system.
:TOPIC: To change the topic of a channel.
:QUIET: To silently discard the ``IRCResponse`` data.
:RESET: To trigger a reimport of all loaded apps.
Shortcuts
---------
The ``yardbird.shortcuts`` module has a few handy shortcuts to simplify the
crafting of IRCResponse objects:
:render_to_response: Renders a *template* using a supplied
*dictionary*, and sends the result to a
specified *recipient* by an optional
*method* (defaults to ``PRIVMSG``)
:render_to_reply: Renders a *template* using a supplied
*dictionary* as a reply to the user in the
supplied *request* object.
:render_quick_reply: Renders a *template* using the supplied
*request* object's ``__dict__`` as context,
and sends as a reply to the original
recipient.
:render_silence: Returns an IRCResponse which uses the
``QUIET`` method.
:render_error: Returns an error *message* to the specified
*recipient* with the ``NOTICE`` method.
Signals
-------
The ``yardbird.signals`` package implements two new signals:
:request_started: Fired off before an IRCRequest is
dispatched to yardbird views.
:request_finished: Fired off after an IRCRequest is dispatched
to yardbird views.