update documentation

doc/source/error.rst

@@ -5,6 +5,10 @@
 Errors -- exceptions and error handling
 =======================================
 
+.. autoclass:: uv.StatusCode
+    :members:
+
+
 .. autoclass:: uv.UVError
     :members:
 

doc/source/handles/async.rst

@@ -0,0 +1,11 @@
+.. _Async:
+
+.. currentmodule:: uv
+
+:class:`Async` -- async handle
+==============================
+
+.. autoclass:: uv.Async
+    :members:
+    :member-order: bysource
+

doc/source/handles/check.rst

@@ -0,0 +1,11 @@
+.. _Check:
+
+.. currentmodule:: uv
+
+:class:`Check` -- check handle
+==============================
+
+.. autoclass:: uv.Check
+    :members:
+    :member-order: bysource
+

doc/source/handle.rst → doc/source/handles/handle.rst

@@ -9,4 +9,3 @@ Handle -- handle base class
     :members:
     :member-order: bysource
 
-.. autofunction:: uv.close_all_handles

doc/source/handles/idle.rst

@@ -0,0 +1,11 @@
+.. _Idle:
+
+.. currentmodule:: uv
+
+:class:`Idle` -- idle handle
+============================
+
+.. autoclass:: uv.Idle
+    :members:
+    :member-order: bysource
+

doc/source/handles/poll.rst

@@ -0,0 +1,13 @@
+.. _Poll:
+
+.. currentmodule:: uv
+
+:class:`Poll` -- poll handle
+============================
+
+.. autoclass:: uv.Poll
+    :members:
+    :member-order: bysource
+
+.. autoclass:: uv.PollEvent
+    :members:

doc/source/index.rst

@@ -11,7 +11,13 @@ Contents:
     :titlesonly:
 
     error
-    handle
+
+    handles/handle
+
+    handles/async
+    handles/check
+    handles/idle
+    handles/poll
 
 
 Indices and tables

uv/__init__.py

@@ -22,18 +22,18 @@
 the libuv asynchronous IO library. It supports all handles as well as
 filesystem operations, dns utility functions and miscellaneous utilities.
 
-There are no plans to support the thread pool work scheduling or the
+There are no plans to support the thread pool work scheduling and the
 threading and synchronization utilities because Python already provides
 nice solutions for those things in the standard library.
 
 Based on Python's standard library's SSL module this package also provides
 support for asynchronous SSL sockets.
 
-As you may have noticed this package is not totally PEP-8 conform when
-it comes to the maximum line length of 79 characters – instead we are
-using a maximum line length of 90 characters. This allows us to use
-longer and more expressive variable names without ugly line breaking
-stunts and overall makes the code more readable.
+As you may have noticed this package is not totally PEP-8 conform when it
+comes to the maximum line length of 79 characters – instead we are using
+a maximum line length of 90 characters. This allows us to use longer and
+more expressive variable names without ugly line breaking stunts and
+overall makes the code more readable.
 """
 
 __version__ = '0.0.4.dev0'

uv/async.py

@@ -21,7 +21,6 @@
 
 from .error import UVError, HandleClosedError
 from .handle import HandleType, Handle
-from .loop import Loop
 
 __all__ = ['Async']
 
@@ -36,9 +35,16 @@ def uv_async_cb(uv_async):
 @HandleType.ASYNC
 class Async(Handle):
     """
+    Async handles will wake-up the event loop from an other thread and
+    run the given callback within the event loop's thread. They are the
+    only thread-safe handles.
+
+    :raises uv.UVError: error during the initialization of the handle
+
     :param loop: event loop which should be used for the handle
     :param callback: callback which should be called from within the event loop
-    :type loop: Loop
+
+    :type loop: uv.Loop
     :type callback: (uv.Async) -> None
     """
 
@@ -48,11 +54,26 @@ def __init__(self, loop=None, callback=None):
         self.uv_async = ffi.new('uv_async_t*')
         super(Async, self).__init__(self.uv_async, loop)
         self.callback = callback or dummy_callback
+        """
+        Callback which should be called from within the event loop.
+
+        .. function:: callback(Async-Handle)
+
+        :readonly: False
+        :type: (uv.Async) -> None
+        """
         code = lib.uv_async_init(self.loop.uv_loop, self.uv_async, uv_async_cb)
         if code < 0: raise UVError(code)
 
     def send(self, callback=None):
         """
+        Wake-up the event loop and execute the callback afterwards. Multiple calls
+        to this method are coalesced if they happen before the callback has been
+        called. This means not every call will yield a execution of the callback.
+
+        :raises uv.UVError: error while trying to wake-up event loop
+        :raises uv.HandleClosedError: handle has already been closed or is closing
+
         :param callback: callback which should be called from within the event loop
         :type callback: (uv.Async) -> None
         """

uv/check.py

@@ -19,7 +19,7 @@
 
 from .library import ffi, lib, detach, dummy_callback
 
-from .error import UVError
+from .error import UVError, HandleClosedError
 from .handle import HandleType, Handle
 
 __all__ = ['Check']
@@ -34,22 +34,63 @@ def uv_check_cb(uv_check):
 
 @HandleType.CHECK
 class Check(Handle):
+    """
+    Check handles will run the given callback once per loop iteration,
+    right after polling for IO.
+
+    :raises uv.UVError: error during the initialization of the handle
+
+    :param loop: event loop which should be used for the handle
+    :param callback: callback which should be called right after polling for IO
+
+    :type loop: Loop
+    :type callback: (uv.Async) -> None
+    """
+
     __slots__ = ['uv_check', 'callback']
 
     def __init__(self, loop=None, callback=None):
         self.uv_check = ffi.new('uv_check_t*')
         super(Check, self).__init__(self.uv_check, loop)
         self.callback = callback or dummy_callback
+        """
+        Callback which should be called after polling for IO.
+
+        .. function:: callback(Check-Handle)
+
+        :readonly: False
+        :type: (uv.Check) -> None
+        """
         code = lib.uv_check_init(self.loop.uv_loop, self.uv_check)
         if code < 0: raise UVError(code)
 
     def start(self, callback=None):
+        """
+        Starts the handle.
+
+        :raises uv.UVError: error while starting the handle
+        :raises uv.HandleClosedError: handle has already been closed or is closing
+
+        :param callback: callback which should be called after polling for IO
+        :type callback: (uv.Check) -> None
+        """
+        if self.closing: raise HandleClosedError()
         self.callback = callback or self.callback
         code = lib.uv_check_start(self.uv_check, uv_check_cb)
         if code < 0: raise UVError(code)
 
     def stop(self):
+        """
+        Stops the handle, the callback will no longer be called.
+
+        :raises uv.UVError: error while stopping the handle
+        """
+        if self.closing: return
         code = lib.uv_check_stop(self.uv_check)
         if code < 0: raise UVError(code)
 
+    def destroy(self):
+        self.uv_check = None
+        super(Check, self).destroy()
+
     __call__ = start

uv/error.py

@@ -26,6 +26,9 @@
 
 class StatusCode(enum.IntEnum):
     SUCCESS = 0
+    """
+    Success.
+    """
 
     E2BIG = lib.UV_E2BIG
     EACCES = lib.UV_EACCES

uv/fs.py

@@ -21,7 +21,7 @@
 
 from collections import namedtuple
 
-from .library import ffi, lib, detach, detach_loop, dummy_callback
+from .library import ffi, lib, detach, dummy_callback
 
 from .error import UVError, StatusCode, get_status_code
 from .handle import HandleType
@@ -139,11 +139,7 @@ def post_close(request):
     return [status]
 
 
-@FSType.OPEN
-def post_open(request):
-    if request.result < 0: status, fd = get_status_code(request.result), None
-    else: status, fd = StatusCode.SUCCESS, request.result
-    return [status, fd]
+
 
 
 @FSType.STAT
@@ -168,7 +164,29 @@ def close(fd, callback=None, loop=None):
     return request
 
 
+@FSType.OPEN
+def post_open(request):
+    if request.result < 0: status, fd = get_status_code(request.result), None
+    else: status, fd = StatusCode.SUCCESS, request.result
+    return [status, fd]
+
+
 def open(path, flags, mode=0o777, callback=None, loop=None):
+    """
+
+    :param path:
+    :param flags:
+    :param mode:
+    :param callback: callback signature: `(request, status, fd)`
+    :param loop:
+
+    :type path: str
+    :type flags: int
+    :type mode: int
+    :type callback: (FSRequest, int, int) -> None
+
+    :return:
+    """
     request = FSRequest(None, callback, loop)
     uv_fs = request.uv_fs
     c_path = path.encode()
@@ -185,5 +203,5 @@ def stat(path, callback=None, loop=None):
 
 
 @HandleType.FILE
-class File:
+class File(object):
     pass

uv/fs_event.py

@@ -24,7 +24,7 @@
 from .error import UVError
 from .handle import HandleType, Handle
 
-__all__ = ['EventFlags', 'Event', 'FSEvent']
+__all__ = ['FSEvent', 'EventFlags', 'Event']
 
 
 class EventFlags(enum.IntEnum):

uv/handle.py

@@ -65,11 +65,14 @@ def uv_close_cb(uv_handle):
 class Handle(object):
     """
     Handles represent long-lived objects capable of performing certain
-    operations while active. This is the base class of all handles.
+    operations while active. This is the base class of all handles except
+    the file and SSL handle, which are pure Python.
 
     :raises uv.LoopClosedError: loop has already been closed
+
     :param loop: loop where the handle should run on
-    :param uv_handle: allocated c struct for this handle (used internally)
+    :param uv_handle: allocated c struct for this handle
+
     :type loop: Loop
     :type uv_handle: ffi.CData
     """