Merge branch 'asyncio'

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014, Shiz
+Copyright (c) 2014-2016, Shiz
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -3,20 +3,21 @@ pydle
 Python IRC library.
 -------------------
 
-pydle is a compact, flexible and standards-abiding IRC library for Python 3.
+pydle is a compact, flexible and standards-abiding IRC library for Python 3.4+.
 
 Features
 --------
-* Well-organized: Thanks to the modularized feature system, it's not hard to find what you're looking for in the well-organized source code.
+* Well-organized: Thanks to the modularized feature system, it's not hard to find what you're looking for in the well-organised source code.
 * Standards-abiding: Based on [RFC1459](https://tools.ietf.org/html/rfc1459.html) with some small extension tweaks, with full support of optional extension standards:
   - [TLS](http://tools.ietf.org/html/rfc5246)
   - [CTCP](http://www.irchelp.org/irchelp/rfc/ctcpspec.html)
   - (coming soon) [DCC](http://www.irchelp.org/irchelp/rfc/dccspec.html) and extensions
   - [ISUPPORT/PROTOCTL](http://tools.ietf.org/html/draft-hardy-irc-isupport-00)
-  - [IRCv3.1](http://ircv3.org/) (full)
-  - [IRCv3.2](http://ircv3.org) (base only, in progress)
-* Callback-based: IRC is an asynchronous protocol and so should a library that implements it be. Callbacks are used to process events from the server.
-* Modularised and extensible: Features on top of RFC1459 are implemented as seperate modules for a user to pick and choose, and write their own. Broad features are written to be as extensible as possible.
+  - [IRCv3.1](http://ircv3.net) (full)
+  - [IRCv3.2](http://ircv3.net) (base complete, most optional extensions)
+  - [IRCv3.3](http://ircv3.net) (base in progress)
+* Asynchronous: IRC is an asynchronous protocol and so should be a library that implements it. Coroutines are used to process events from the server asynchronously.
+* Modularised and extensible: Features on top of RFC1459 are implemented as separate modules for a user to pick and choose, and write their own. Broad features are written to be as extensible as possible.
 * Liberally licensed: The 3-clause BSD license ensures you can use it everywhere.
 
 Basic Usage
@@ -31,15 +32,14 @@ import pydle
 
 # Simple echo bot.
 class MyOwnBot(pydle.Client):
-    def on_connect(self):
-         self.join('#bottest')
+    async def on_connect(self):
+         await self.join('#bottest')
 
-    def on_message(self, source, target, message):
-         self.message(target, message)
+    async def on_message(self, target, source, message):
+         await self.message(target, message)
 
 client = MyOwnBot('MyBot', realname='My Bot')
-client.connect('irc.rizon.net', 6697, tls=True, tls_verify=False)
-client.handle_forever()
+client.run('irc.rizon.net', tls=True, tls_verify=False)
 ```
 
 *But wait, I want to handle multiple clients!*
@@ -55,6 +55,17 @@ for i in range(10):
 pool.handle_forever()
 ```
 
+Furthermore, since pydle is simply `asyncio`-based, you can run the client in your own event loop, like this:
+```python
+import asyncio
+
+client = MyOwnBot('MyBot')
+loop = asyncio.get_event_loop()
+asyncio.ensure_future(client.connect('irc.rizon.net', tls=True, tls_verify=False), loop=loop)
+loop.run_forever()
+```
+
+
 Customization
 -------------
 
@@ -69,10 +80,10 @@ To create your own features, just subclass from `pydle.BasicClient` and start ad
 ```python
 # Support custom ACME extension.
 class ACMESupport(pydle.BasicClient):
-    def on_raw_999(self, source, params):
+    async def on_raw_999(self, source, params):
         """ ACME's custom 999 numeric tells us to change our nickname. """
         nickname = params[0]
-        self.set_nickname(nickname)
+        await self.set_nickname(nickname)
 ```
 
 FAQ

docs/conf.py

@@ -35,8 +35,7 @@
 
 # Documentation links for projects we link to.
 intersphinx_mapping = {
-    'python': ('http://docs.python.org/3', None),
-    'tornado': ('http://www.tornadoweb.org/en/stable', None),
+    'python': ('http://docs.python.org/3', None)
 }
 
 

docs/features/index.rst

@@ -2,7 +2,7 @@
 Features
 ========
 
-pydle's main IRC functionality is divided into seperate modular components called "features".
+pydle's main IRC functionality is divided into separate modular components called "features".
 These features allow you to mix and match your client to fit exactly to your requirements,
 as well as provide an easy way to extend pydle yourself, without having to dive into the source code.
 

docs/features/overview.rst

@@ -134,7 +134,7 @@ Capability Negotiation Support
 
 Support for `capability negotiation` for IRC protocol extensions.
 
-This feature enables support for a generic framework for negotiationg IRC protocol extension support between the client and the
+This feature enables support for a generic framework for negotiating IRC protocol extension support between the client and the
 server. It was quickly found that `ISUPPORT` alone wasn't sufficient, as it only advertises support from the server side instead
 of allowing the server and client to negotiate. This is a generic base feature: enabling it on its own won't do much, instead
 other features like the IRCv3.1 support feature, or the SASL authentication feature will rely on it to work.
@@ -165,10 +165,12 @@ to the `pydle.Client` constructor:
  * ``sasl_username``: The SASL username.
  * ``sasl_password``: The SASL password.
  * ``sasl_identity``: The identity to use. Default, and most common, is ``''``.
+ * ``sasl_mechanism``: The SASL mechanism to force. Default involves auto-selection from server-supported mechanism, or a `PLAIN`` fallback.
 
 These arguments are also set as attributes.
 
-Currently, pydle's SASL support requires on the Python `pure-sasl`_ package and is limited to support for the `PLAIN` mechanism.
+Currently, pydle's SASL support requires on the Python `pure-sasl`_ package and is thus limited to the mechanisms it supports.
+The ``EXTERNAL`` mechanism is also supported without, however.
 
 .. _`SASL`: https://tools.ietf.org/html/rfc4422
 .. _`pure-sasl`: https://github.com/thobbs/pure-sasl

docs/index.rst

@@ -28,7 +28,7 @@ Features
   No half-assing functionality.
 - **Asynchronous**
 
-  IRC is an asychronous protocol; it only makes sense a clients that implements it is asynchronous as well. Built on top of the wonderful Tornado_ library, pydle relies on proven technologies to deliver proper high-performance asynchronous functionality and primitives.
+  IRC is an asychronous protocol; it only makes sense a clients that implements it is asynchronous as well. Built on top of the wonderful asyncio_ library, pydle relies on proven technologies to deliver proper high-performance asynchronous functionality and primitives.
   pydle allows using Futures to make asynchronous programming just as intuitive as doing regular blocking operations.
 
   No callback spaghetti.
@@ -45,7 +45,7 @@ Features
 .. _WHOX: https://hg.quakenet.org/snircd/file/tip/doc/readme.who
 .. _IRCv3.1: http://ircv3.org/
 .. _IRCv3.2: http://ircv3.org/
-.. _Tornado: http://tornadoweb.org
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
 
 Contents
 --------

docs/intro.rst

@@ -4,7 +4,7 @@ Introduction to pydle
 
 What is pydle?
 --------------
-pydle is an IRC library for Python 3.2 and up.
+pydle is an IRC library for Python 3.4 and up.
 
 Although old and dated on some fronts, IRC is still used by a variety of communities as the real-time communication method of choice,
 and the most popular IRC networks can still count on tens of thousands of users at any point during the day.
@@ -23,7 +23,6 @@ and APIs are prone to change or removal at least until version 1.0 has been reac
 Requirements
 ------------
 Most of pydle is written in pure, portable Python that only relies on the standard library.
-However, pydle relies on Tornado_ to do the heavy lifting on the asynchronous front.
 Optionally, if you plan to use pydle's SASL functionality for authentication, the excellent pure-sasl_ library is required.
 
 All dependencies can be installed using the standard package manager for Python, pip, and the included requirements file:
@@ -32,7 +31,6 @@ All dependencies can be installed using the standard package manager for Python,
 
   pip install -r requirements.txt
 
-.. _Tornado: http://www.tornadoweb.org/
 .. _pure-sasl: https://github.com/thobbs/pure-sasl
 
 Compatibility