Wow. Why didn't I commit this in smaller parts?

Lots of changes. This started as a small change to split the classes in
ib3 into a few sub-modules. That led to fixing up the generated
documentation a bit. Then I just kept running in a circle of
refactoring, updating docs, and creating new sub-modules.

The neat thing though is that the library is looking pretty useful and
the example saslbot.py class does things that none of the live bots
I started extracting this from can do yet.

Author: bd808

README.rst

@@ -4,24 +4,34 @@ IRC Bot Behavior Bundle (IB3)
 
 IRC bot framework using mixins to provide commonly desired functionality.
 
-Mixins
-======
-* DisconnectOnError: Handle ERROR message by logging and disconnecting
-* FreenodePasswdAuth: Authenticate with NickServ before joining channels
-* Ping: Add checks for connection liveness using PING commands
-* RejoinOnBan: Handle ERR_BANNEDFROMCHAN by attempting to rejoin channel
-* RejoinOnKick: Handle KICK by attempting to rejoin channel
+About
+=====
+The `irc`_ python library's ``irc.bot.SingleServerIRCBot`` provides a nice
+base for making a new bot, but there are many common tasks needed by a robust
+bot that it does not handle out of the box. IB3 collects some commonly desired
+behaviors for a bot as `mixin`_ classes that can be used via `multiple
+inheritance`_::
+
+    from ib3 import Bot
+    from ib3.auth import SASL
+    from ib3.connections import SSL
+    from ib3.mixins import DisconnectOnError
+
+    class TestBot(SASL, SSL, DisconnectOnError, Bot):
+        pass
 
 License
 =======
-`GNU GPLv3+`_
+IB3 is licensed under the `GNU GPLv3+`_ license.
 
-Some code and much inspiration taken from:
-
-* `Adminbot`_
-* `Jouncebot`_
-* `Stashbot`_
+Credits
+=======
+Some code and much inspiration taken from Wikimedia irc bots `Adminbot`_,
+`Jouncebot`_, and `Stashbot`_.
 
+.. _irc: https://pypi.org/project/irc/
+.. _mixin: https://en.wikipedia.org/wiki/Mixin
+.. _multiple inheritance: https://docs.python.org/3/tutorial/classes.html#multiple-inheritance
 .. _GNU GPLv3+: https://www.gnu.org/copyleft/gpl.html
 .. _Adminbot: https://phabricator.wikimedia.org/diffusion/ODAC/
 .. _Jouncebot: https://phabricator.wikimedia.org/diffusion/GJOU/

doc/about.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst

doc/conf.py

@@ -15,11 +15,16 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
 ]
 
-# General information about the project.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'irc': ('https://python-irc.readthedocs.io/en/stable/', None),
+}
 
+# General information about the project.
 root = os.path.join(os.path.dirname(__file__), '..')
 setup_script = os.path.join(root, 'setup.py')
 fields = ['--name', '--version', '--author']

doc/ib3.rst

@@ -0,0 +1,52 @@
+ib3 package
+===========
+
+Module contents
+---------------
+
+.. automodule:: ib3
+    :members:
+    :special-members: __init__
+    :private-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+ib3.auth module
+---------------
+
+.. automodule:: ib3.auth
+    :members:
+    :special-members: __init__
+    :private-members:
+    :show-inheritance:
+
+ib3.connection module
+---------------------
+
+.. automodule:: ib3.connection
+    :members:
+    :special-members: __init__
+    :private-members:
+    :show-inheritance:
+
+
+ib3.mixins module
+---------------------
+
+.. automodule:: ib3.mixins
+    :members:
+    :special-members: __init__
+    :private-members:
+    :show-inheritance:
+
+
+ib3.nick module
+---------------------
+
+.. automodule:: ib3.nick
+    :members:
+    :special-members: __init__
+    :private-members:
+    :show-inheritance:

doc/index.rst

@@ -1,13 +1,8 @@
+IRC Bot Behavior Bundle (IB3) Documentation
+===========================================
+
 .. toctree::
    :maxdepth: 2
 
-.. include:: ../README.rst
-
-ib3 package
-===========
-
-.. automodule:: ib3
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :noindex:
+   about
+   ib3

examples/nickserv.py

@@ -20,11 +20,7 @@
 import logging
 
 from ib3 import Bot
-from ib3 import DisconnectOnError
-from ib3 import FreenodePasswdAuth
-from ib3 import Ping
-from ib3 import RejoinOnBan
-from ib3 import RejoinOnKick
+from ib3.auth import NickServ
 
 
 logging.basicConfig(
@@ -35,10 +31,7 @@
 logging.captureWarnings(True)
 
 
-class TestBot(
-    FreenodePasswdAuth, Ping, DisconnectOnError,
-    RejoinOnBan, RejoinOnKick, Bot
-):
+class TestBot(NickServ, Bot):
     pass
 
 

examples/saslbot.py

@@ -22,6 +22,9 @@
 import irc.strings
 
 import ib3
+import ib3.auth
+import ib3.connection
+import ib3.nick
 
 
 logging.basicConfig(
@@ -34,8 +37,8 @@
 logger = logging.getLogger('saslbot')
 
 
-class SaslBot(ib3.SASL, ib3.SSL, ib3.Bot):
-    """Example bot showing use of SASL auth and SSL encryption."""
+class SaslBot(ib3.auth.SASL, ib3.nick.Regain, ib3.connection.SSL, ib3.Bot):
+    """Example bot showing use of SASL auth, REGAIN, and SSL encryption."""
     def on_privmsg(self, conn, event):
         self.do_command(conn, event, event.arguments[0])