404d/Bones-IRCBot — pull request #31 by 404d (2014-09-24 19:36:57+00:00)
Title: API rehaul and documentation

This is a WIP proposal/goal/spec. for the planned API rehaul. There is no promises that this will look like the final product.
## Event API
**Use classes instead of strings**
~~~~python
## Now:
@bones.event.handler(event="UserJoinEvent")

bones.event.fire("servertag", "UserJoinEvent", event)
bones.event.fire("servertag", "UserQuitEvent", event)
bones.event.fire("servertag", "irc_unknown", prefix, command, args)

## Goal:
@bones.event.handler(event=bones.event.UserJoinEvent)
bones.event.fire("servertag", event) # new syntax
bones.event.fire("servertag", "UserQuit", event) # old syntax, still working
bones.event.fire("servertag", "irc_unknown", prefix, command, args) # even older syntax, still working
~~~~

### Status
- [x] Class-style event handlers
- [x] Class-style event firing

## User and Channel API
**Goal 1: Reduce the amount of code needed for modules.**
Examples, now:
~~~~python
## Ex. 1
event.client.msg(event.channel, "Message")

## Ex. 2
event.client.kick(event.channel, event.user.nickname, "Reason")

## Ex. 3
event.client.leave(event.channel, reason="Reason")

## Ex. 4
# It is currently not possible to track users in a channel

## Ex. 5
# It is currently not possible to check for modes

## Ex. 6
event.client.notice(event.user.nickname, "Notice")
~~~~
What we want:
~~~~python
## Ex. 1
event.channel.msg("Message")

## Ex. 2
event.channel.kick(event.user, "Reason")

## Ex. 3
event.channel.part("Reason")

## Ex. 4
len(event.channel.users)
for user in event.channel.users:
user.notice("Ahuehue")

## Ex. 5
if "m" in event.channel.modes: pass

## Ex. 6
event.user.notice("Notice")
~~~~

### Status
**Channel Utility Class**
- [x] Kick Method
- [x] Message Method
- [ ] Mode Management
- [x] Notice Method
- [ ] User list

**User Utility Class**
- [x] Channel list
- [x] Kick Method
- [x] Message Method
- [x] Notice Method
- Tracking implementation
- [x] Nick changes
- Instantiation/removal on:
- [ ] Topic change
- [x] User join
- [x] User quit
- [x] User part
- [x] User message
- [ ] Mode changes
- [ ] User notice
- Support in events
- All points mentioned above plus:
- [ ] User action
- Other details
- [x] **Update hostname/username when changed** *Implemented in `get_user`, gets done if the query field contains a hostmask*

## Merge-time checklist1
- [ ] Update `bones.modules.funserv.QDB` and other `urllib`-based modules to use `self.factory`, rather than grabbing the factory from an event.
- [ ] Update `BonesBot.quit()` to use new-style (Event instance based) events.