diff --git a/README b/README index 1ceae1673..3d8ddd2f6 100644 --- a/README +++ b/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. diff --git a/RELNOTES b/RELNOTES index 4609f93ce..c5a4e1177 100644 --- a/RELNOTES +++ b/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 diff --git a/docs/GETTING_STARTED b/docs/GETTING_STARTED index 43522717c..7fcbbfd5f 100644 --- a/docs/GETTING_STARTED +++ b/docs/GETTING_STARTED @@ -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 ", replacing 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. diff --git a/docs/INTERFACES b/docs/INTERFACES index 039f72812..c69b75bff 100644 --- a/docs/INTERFACES +++ b/docs/INTERFACES @@ -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. diff --git a/docs/RELEASE-CHECKLIST b/docs/RELEASE-CHECKLIST index f1ea25552..aaa066532 100644 --- a/docs/RELEASE-CHECKLIST +++ b/docs/RELEASE-CHECKLIST @@ -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.