documentation wheeee

Author: an-empty-string

doc/doc.rst

@@ -0,0 +1,261 @@
+Introduction to asyncirc
+========================
+
+Asyncirc is an IRC library based on Python's asyncio. It is designed to be easy
+to use, to provide a nice way of processing IRC events, and to provide a Good
+Enough(TM) abstraction of the IRC protocol. It is *not* designed to be a ready-
+made bot framework, or to be used without some knowledge of how IRC works.
+
+Installation
+------------
+You can install asyncirc from PyPI, using whatever method you prefer. The
+package name is ``asyncio-irc``.
+
+Signals
+-------
+Instead of using callback-style event handler registration, asyncirc uses
+*signals*. Signals are provided by the excellent
+`Blinker<https://pythonhosted.org/blinker/>`_ library. It would be advisable
+to read that page for more information on signals, but the tl;dr is::
+
+    # register a signal handler
+    signal("signal-name").connect(signal_handler_function)
+
+    # send a signal
+    signal("signal-name").send(sender, some="keyword", argu="ments")
+
+Asyncirc defines a lot of signals, which are covered in detail below.
+
+Usage
+=====
+
+Actually using asyncirc is pretty simple. First you need to import it::
+
+    from asyncirc import irc
+
+Then you need to create a connection::
+
+    conn = irc.connect("chat.freenode.net", 6697, use_ssl=True)
+
+You'll need to register with the server::
+
+    conn.register("nickname", "ident", "realname (can contain spaces)")
+
+Once you're registered and connected, you'll want to join some channels::
+
+    @conn.on("irc-001")
+    def autojoin_channels():
+        conn.join(["#channel1", "#channel2"])
+
+Maybe you want to connect some event handlers::
+
+    @conn.on("join")
+    def on_join(message, user, channel):
+        conn.say(channel, "Hi {}! You're connecting from {}.".format(user.nick, user.host))
+
+Once you're done with that, you need to run the event loop::
+
+    import asyncio
+    asyncio.get_event_loop().run_forever()
+
+Your shiny new IRC client should now connect and do what you told it to!
+Congratulations!
+
+Using plugins
+-------------
+Plugins let you do new stuff with your connection. To use them, you import them
+before you initially make the connection::
+
+    from asyncirc import irc
+    import asyncirc.plugins.addressed
+
+    conn = irc.connect(...)
+    ...
+
+Plugins usually send new signals, so you want to handle those::
+
+    @conn.on("addressed")
+    def on_addressed(message, user, target, text):
+        # triggers on "bot_nickname: " or similar
+        bot.say(target, "{}: You said {} to me!".format(user.nick, text))
+
+Fundamental types
+=================
+
+There are a few arguments to your handlers that are instances of specific
+classes. Here are those:
+
+``user`` is usually an instance of the ``User`` class, which has some important
+attributes:
+
+    ``User.nick`` contains the nickname of the user
+
+    ``User.user`` contains the ident of the user
+
+    ``User.host`` contains the host of the user
+
+    ``User.hostmask`` contains the full hostmask of the user
+
+Events you can handle
+=====================
+
+There are a lot of things that can happen on IRC. As such, there are a lot of
+signals that asyncirc generates. Here's a list of some useful ones, with event
+handler signatures::
+
+    @conn.on("private-message")
+    def on_private_message(message, user, target, text):
+        ...
+
+    @conn.on("public-message")
+    def on_public_message(message, user, target, text):
+        ...
+
+    @conn.on("message")
+    def on_any_message(message, user, target, text):
+        ...
+
+    @conn.on("private-notice")
+    def on_private_notice(message, user, target, text):
+        ...
+
+    @conn.on("public-notice")
+    def on_public_notice(message, user, target, text):
+        ...
+
+    @conn.on("notice")
+    def on_any_notice(message, user, target, text):
+        ...
+
+    @conn.on("join")
+    def on_join(message, user, channel):
+        ...
+
+    @conn.on("part")
+    def on_join(message, user, channel, reason):
+        # reason defaults to None if there is no reason
+        ...
+
+    @conn.on("quit")
+    def on_quit(message, user, reason):
+        ...
+
+    @conn.on("kick")
+    def on_kick(message, kicker, kickee, channel, reason):
+        # kicker is a User object
+        # kickee is just a nickname
+        ...
+
+    @conn.on("nick")
+    def on_nick_change(message, user, new_nick):
+        ...
+
+These signals are actually sent by the ``core`` plugin, so that's pretty neat.
+
+Just what is that ``message`` handler argument, anyway?
+-------------------------------------------------------
+
+``message`` is a special argument. It contains the parsed commands from the IRC
+server. It has a few useful attributes:
+
+    ``message.params`` has the arguments of the command
+
+    ``message.verb`` has the actual IRC verb
+
+    ``message.sender`` has the hostmask of the sender
+
+``message`` is especially useful when you want to take care of events that don't
+already have a signal attached to them. You can hook into the ``irc`` event, or
+the ``irc-verb`` event to handle specific verbs. Handlers for that will take a
+single argument ``message``.
+
+Plugins
+=======
+
+There are a few plugins packaged with asyncirc. These are documented here.
+
+``asyncirc.plugins.nickserv``
+-----------------------------
+Sends events when authentication to NickServ succeeds or fails. Automatically
+tries to regain your nickname when it is not available (usually doesn't work
+unless you've authenticated with SASL).
+
+Events::
+
+    @conn.on("nickserv-auth-success")
+    def auth_success(message_text):
+        # yay! you're authed to nickserv now.
+        ...
+
+    @conn.on("nickserv-auth-fail")
+    def auth_fail(message_text):
+        # oh no, you had the wrong password!
+        # try again or exit!
+        ...
+
+``asyncirc.plugins.sasl``
+-------------------------
+Handles IRCv3 SASL authentication. After importing, there's a single method call
+you need to worry about::
+
+    asyncirc.plugins.sasl.auth(account_name, password)
+
+And a single event::
+
+    @conn.on("sasl-auth-complete")
+    def sasl_auth_complete(message):
+        # yay, you've authenticated with SASL.
+        ...
+
+You probably don't even have to worry about the event. This plugin talks to the
+core plugin so that registration is delayed until SASL authentication is done.
+
+``asyncirc.plugins.cap``
+------------------------
+Handles IRCv3 capability negotiation. There's only one method you need to call
+to request a capability once you've imported this plugin::
+
+    asyncirc.plugins.cap.request_capability("extended-join") # or whatever
+
+The ``caps-acknowledged`` event will be fired when the server has acknowledged
+our request for capabilities. As soon as we know what set of capabilities the
+server supports, the ``caps-known`` event is fired.
+
+``asyncirc.plugins.tracking``
+-----------------------------
+Full state tracking. Some methods::
+
+    user = asyncirc.plugins.tracking.get_user(hostmask_or_nick)
+    chan = asyncirc.plugins.tracking.get_channel(channel_name)
+
+Based on that, here's some stuff you can do::
+
+    chan.users     # a list of nicknames in the channel
+    user.channels  # a list of channels that the user is in
+    user.account   # the user's services account name. works best if you've
+                   # requested the extended-join and account-notify capabilities
+    chan.mode      # return the channel's mode string
+    user.previous_nicks  # return the user's previous nicknames that we know of
+
+How it actually works is really complicated. Don't even ask.
+
+``asyncirc.plugins.addressed``
+------------------------------
+It has an event that fires when someone mentions your bot by name in IRC::
+
+    @conn.on("addressed")
+    def on_me_addressed(message, user, target, text):
+        # text contains the text without the "your_bot: " part
+        ...
+
+You can also register command characters that can be used instead of your bot's
+nickname::
+
+    asyncirc.plugins.addressed.register_command_character(";;")
+
+Questions? Issues? Just want to chat?
+=====================================
+
+I'm fwilson on freenode, if you have any questions. I hang out in
+``#watchtower`` along with the rest of the Watchtower dev team. Feel free to
+join us!