mirror of https://github.com/Mikaela/Limnoria.git
Updated a whole lot of documentation.
This commit is contained in:
Jeremy Fincher
parent
b9abf8427a
commit
1130baa68d
40
README
40
README
|
|
@ -5,29 +5,16 @@ Read LICENSE. It's a 2-clause BSD license, but you should read it anyway.
|
|||
|
||||
USERS:
|
||||
------
|
||||
First, you gotta have Python 2.3 for this. That's alright, though,
|
||||
because Python 2.3 rocks, and you should have it anyway :)
|
||||
|
||||
Assuming "python" is in your path and points to Python 2.3 or newer,
|
||||
then you need to run this:
|
||||
|
||||
python setup.py install
|
||||
|
||||
from the untarred directory to install the source files. Then just
|
||||
run supybot-wizard (it's been installed in your path somewhere) to
|
||||
create a script that will run your bot as you answered the questions
|
||||
in the wizard.
|
||||
Read docs/GETTING_STARTED for an introduction to the bot. Read
|
||||
docs/CAPABILITIES to see how to use capabilities more to your
|
||||
benefit.
|
||||
|
||||
If you have any trouble, feel free to swing by #supybot on
|
||||
irc.freenode.net or irc.oftc.net (we have a supybot there relaying, so
|
||||
either network works) and ask questions. We'll be happy to help
|
||||
irc.freenode.net or irc.oftc.net (we have a Supybot there relaying,
|
||||
so either network works) and ask questions. We'll be happy to help
|
||||
wherever we can. And by all means, if you find anything hard to
|
||||
understand or think you know of a better way to do something, *please*
|
||||
post it on Sourceforge.net so we can improve the bot!
|
||||
|
||||
If you want, try out the included default botscripts. Just be sure to
|
||||
actually add an owner user for yourself with supybot-adduser. (An
|
||||
"owner user" is simply one with the owner capability).
|
||||
understand or think you know of a better way to do something,
|
||||
*please* post it on Sourceforge.net so we can improve the bot!
|
||||
|
||||
WINDOWS USERS:
|
||||
--------------
|
||||
|
|
@ -39,14 +26,17 @@ this: C:\Python23\python C:\Python23\Scripts\supybot-wizard
|
|||
|
||||
DEVELOPERS:
|
||||
-----------
|
||||
Read OVERVIEW to see what the modules are used for. Read EXAMPLE to see some
|
||||
examples of callbacks and command written for the bot. Read STYLE if you ever
|
||||
wish to contribute.
|
||||
Read OVERVIEW to see what the modules are used for. Read EXAMPLE to
|
||||
see some examples of callbacks and commands written for the bot.
|
||||
Read INTEFACES to see what kinds of objects you'll be dealing with.
|
||||
Read STYLE if you wish to contribute; all contributed code must meet
|
||||
the guidelines set forth there..
|
||||
|
||||
Use PyLint. It's even better than PyChecker. A sample .pylintrc file
|
||||
is included as tools/pylintrc. Copy this to ~/.pylintrc and you'll be
|
||||
able to check your code with the same stringent guidelines I've found
|
||||
useful to check my code. (deja vu? :))
|
||||
|
||||
If you run the tests on Windows (or on a modem connection), be sure to
|
||||
exclude (test\test.py -e) test\test_Debian.py.
|
||||
Be sure to run "test/test.py --help" to see what options are available
|
||||
to you when testing. Windows users in particular should be sure to
|
||||
exclude test_Debian.py and test_Unix.py.
|
||||
|
|
|
|||
9
RELNOTES
9
RELNOTES
|
|
@ -1,3 +1,12 @@
|
|||
Version 0.77.0
|
||||
|
||||
Configuration has been *entirely* redone. Read the new
|
||||
GETTING_STARTED document to see how to work with configuration
|
||||
variables now. Your old botscripts from earlier versions *will not*
|
||||
work with the new configuration method. We'd appreciate it if you'd
|
||||
rerun the wizard in order for us to find any bugs that remain in it
|
||||
before we officially declare ourselves Beta.
|
||||
|
||||
Version 0.76.1
|
||||
|
||||
Almost entirely bugfixes, just some minor (and some less minor) bugs
|
||||
|
|
|
|||
|
|
@ -12,22 +12,111 @@ Python developers and we like banana splits.
|
|||
So what do you do? First thing you'll want to do is run (with
|
||||
root/admin privileges) "python setup.py install". This will install
|
||||
Supybot globally. If you need to install locally for whatever
|
||||
reason, see the addendum near the end of this document.
|
||||
reason, see the addendum near the end of this document. You'll then
|
||||
have several new programs installed where Python scripts are normally
|
||||
installed on your system (/usr/bin or /usr/local/bin are common on
|
||||
UNIX systems; C:\Python23\Scripts is a common place on Windows; and
|
||||
(watch out, this is a long one :))
|
||||
/System/Library/Frameworks/Python.framework/Versions/2.3/bin is a
|
||||
common place on MacOS X.). The
|
||||
two that might be of particular interest to you, the new user, are
|
||||
"supybot" and "supybot-wizard". The former ("supybot") is the script
|
||||
to run an actual bot; the latter ("supybot-wizard") is an in-depth
|
||||
wizard that provides a nice user interface for creating configuration
|
||||
files for your bot. We'd prefer you to the use supybot-wizard, but
|
||||
if you're in a hurry or don't feel like being asked many questions,
|
||||
just run supybot with no arguments and it'll ask you only the
|
||||
questions necessary to run a bot.
|
||||
|
||||
So after running either of those two programs, you've got a nice
|
||||
registry file handy. If you're not satisfied with your answers to
|
||||
any of the questions you were asked, feel free to run the program
|
||||
again until you're satisfied with all your answers. Once you're
|
||||
satisfied, though, run the "supybot" program with the registry file
|
||||
you created as an argument. This will start the bot; unless you
|
||||
turned off logging to stdout, you'll see some nice log messages
|
||||
describing what the bot is doing at any particular moment; it may
|
||||
pause for a significant amount of time after saying "Reconnecting to
|
||||
..." while the server tries to check its ident.
|
||||
|
||||
Ok, so let's assume your bot connected to the server fine and joined
|
||||
the channels you told it to join. For now we'll assume you named
|
||||
your bot "supybot" (you probably didn't, but it'll make it much
|
||||
clearer in the examples that follow to assume that you did). We'll
|
||||
also assume that you told it to join #channel (a nice generic name
|
||||
for a channel, isn't it? :)) So what do you do with this bot that
|
||||
you just made to join your channel? Try this in the channel:
|
||||
|
||||
supybot: list
|
||||
|
||||
Replacing "supybot" with the actual name you picked for your bot, of
|
||||
course. Your bot should reply with a list of the plugins he
|
||||
currently has loaded. At least Admin, Channel, Config, Misc, Owner,
|
||||
and User should be there; if you used supybot-wizard to create your
|
||||
configuration file you may have many more plugins loaded. The list
|
||||
command can also be used to list the commands in a given plugin:
|
||||
|
||||
supybot: list Misc
|
||||
|
||||
Will list all the commands in the Misc plugin. If you want to see
|
||||
the help for any command, just use the help command:
|
||||
|
||||
supybot: help help
|
||||
supybot: help list
|
||||
supybot: help load
|
||||
|
||||
Speaking of the load command, that's the command you'll use to load
|
||||
other plugins. If you didn't use supybot-wizard, though, you might
|
||||
do well to try it before playing around with loading plugins
|
||||
yourself: each plugin has its own configure function that the wizard
|
||||
uses to setup the appropriate registry entries if the plugin requires
|
||||
any. ### TODO: Make a command to list loadable plugins?
|
||||
|
||||
Now, if you do want to play around with loading plugins, you're going
|
||||
to need to have the owner capability.
|
||||
# TODO: wizard or supybot-adduser.
|
||||
Now, in order for the bot to recognize you as your owner user, you'll
|
||||
have to identify with the bot. Open up a query window in your irc
|
||||
client (/query should do it; if not, just know that you can't
|
||||
identify in a channel because it requires sending your password to
|
||||
the bot). Then type this:
|
||||
|
||||
help identify
|
||||
|
||||
And follow the instructions; the command you send will probably look
|
||||
like this, with your owner user and password replaced:
|
||||
|
||||
identify myowneruser myuserpassword
|
||||
|
||||
The bot will tell you that "The operation succeeded" if you got the
|
||||
right name and password. Now that you're identified, you can do
|
||||
anything that requires any privilege: that includes all the commands
|
||||
in the Owner and Admin plugins, which you may want to take a look at
|
||||
(using the list and help commands, of course). One command in
|
||||
particular that you might want to use (it's from the User plugin) is
|
||||
the addhostmask command: it lets you add a hostmask to your user
|
||||
record so the bot recognizes you by your hostmask instead of
|
||||
requiring you to always identify with it before it recognizes you.
|
||||
Use the help command to see how this command works. Here's how I
|
||||
often use it:
|
||||
|
||||
addhostmask myuser [hostmask] mypassword
|
||||
|
||||
You may not have seen that "[hostmask]" syntax before. Supybot
|
||||
allows nested commands, which means that any command's output can be
|
||||
nested as an argument to another command. The hostmask command from
|
||||
the Misc plugin returns the hostmask of a given nick, but if given no
|
||||
arguments, it returns the hostmask of the person giving the command.
|
||||
So the command above adds the hostmask I'm currently using to my
|
||||
user's list of recognized hostmasks. I'm only required to give
|
||||
mypassword if I'm not already identified with the bot.
|
||||
|
||||
# TODO: Explain the Config plugin.
|
||||
|
||||
|
||||
### TODO: Local installs.
|
||||
### TODO: Explain how to run tests?
|
||||
|
||||
After that, you'll want to run supybot-wizard and generate yourself a
|
||||
configuration file. To run this configuration file, you'll want to type
|
||||
"supybot <config file>", replacing <config file> with the name of the
|
||||
configuration file you just generated with the supybot-wizard. The supybot
|
||||
program accepts several command-line parameters which you can see by simply
|
||||
running "supybot --help"
|
||||
|
||||
After that, you should have a bot up and running in the
|
||||
|
||||
# TODO: Identification, owner, etc.
|
||||
|
||||
# Common problems
|
||||
# import error in http (relies on python-xml)
|
||||
# import error in database-based plugins.
|
||||
# Can't find the wizard. Full path on Windows and MacOS X.
|
||||
|
|
|
|||
|
|
@ -80,7 +80,11 @@ ircmsgs.IrcMsg:
|
|||
|
||||
irclib.Irc:
|
||||
This is the object to handle everything about IRC except the
|
||||
actual connection to the server itself.
|
||||
actual connection to the server itself. (*NOTE* that the
|
||||
object actually received by commands in subclasses of
|
||||
callbacks.Privmsg is an IrcObjectProxy, which is described
|
||||
later. It augments the following interface with several
|
||||
methods of its own to help plugin authors.)
|
||||
|
||||
Interesting Methods:
|
||||
The two following messages (queueMsg and
|
||||
|
|
@ -207,3 +211,48 @@ irclib.IrcCallback:
|
|||
basically, they're given the first chances
|
||||
on the way in and the last chances on the
|
||||
way out.
|
||||
|
||||
|
||||
callbacks.IrcObjectProxy:
|
||||
IrcObjectProxy is a proxy for an irclib.Irc instance that
|
||||
serves to provide a much fuller interface for handling
|
||||
replies and errors as well as to handle the nesting of
|
||||
commands. This is what you'll be dealing with almost all the
|
||||
time when writing commands; when writing doCommand methods
|
||||
(the kind you read about in the interface description of
|
||||
irclib.IrcCallback) you'll be dealing with plain old
|
||||
irclib.Irc objects.
|
||||
|
||||
Interesting methods:
|
||||
reply: Called to reply to the current message
|
||||
with a string that is to be the reply.
|
||||
|
||||
replySuccess, replyError: These reply with the
|
||||
configured responses for success and generic
|
||||
error, respectively. If an additional argument
|
||||
is given, it's (intelligently) appended to the
|
||||
generic message to be more specific.
|
||||
|
||||
error: Called to send an error reply to the
|
||||
current message; not only does the response
|
||||
indicate an error, but commands that error out
|
||||
break the nested-command chain, which is
|
||||
generally useful for not confusing the user :)
|
||||
|
||||
errorNoCapability: Like error, except it accepts
|
||||
the capability that's missing and integrates it
|
||||
into the configured error message for such
|
||||
things. Also accepts an additional string for a
|
||||
more descriptive message, if that's what you
|
||||
want.
|
||||
|
||||
errorPossibleBug, errorNotRegistered,
|
||||
errorNoUser, errorRequiresPrivacy: These methods
|
||||
reply with the appropriate configured error
|
||||
message for the conditions in their names; they
|
||||
all take an additional arguments to be more
|
||||
specific about the conditions they indicate, but
|
||||
this argument is very rarely necessary.
|
||||
|
||||
getRealIrc: Returns the actual Irc object being
|
||||
proxied for.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@ These are things not to be forgotten when making a Supybot release:
|
|||
|
||||
Update the version in conf.py.
|
||||
Update the version in setup.py.
|
||||
Make a release-MAJOR_MINOR_PATCHLEVEL tag. (cvs tag ...)
|
||||
Make a release-MAJOR_MINOR_PATCHLEVEL-branch branch tag. (cvs tag -b ...)
|
||||
Remove CVS directories from the tarball.
|
||||
Create .tar.gz, .tar.bz2, and .zip archives.
|
||||
Add the release to the supybot package in SF.net.
|
||||
|
|
@ -10,8 +12,8 @@ Announce the release in a News item on SF.net.
|
|||
Announce the release on Freshmeat.net.
|
||||
Announce the release on PyPI via "python setup.py register".
|
||||
Announce the release on the forums.
|
||||
Announce the release on comp.lang.python and comp.lang.python.announce.
|
||||
Add a topic to #supybot announcing the release.
|
||||
Make a release-MAJOR_MINOR_PATCHLEVEL tag. (cvs tag ...)
|
||||
Make a release-MAJOR_MINOR_PATCHLEVEL-branch branch tag. (cvs tag -b ...)
|
||||
Send a GPG-signed tar.gz to vomjom for packing in Debian.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue