X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib-python/blobdiff_plain/d8d81d1b049836f7d4fae7b0077a8ce9e2fc43ac..HEAD:/bres.pyx

diff --git a/bres.pyx b/bres.pyx
index 0ddfb11..8097855 100644
--- a/bres.pyx
+++ b/bres.pyx
@@ -1,31 +1,30 @@
-# -*-pyrex-*-
-#
-# $Id$
-#
-# Background name resolution
-#
-# (c) 2005 Straylight/Edgeware
-#
+### -*-pyrex-*-
+###
+### Background name resolution
+###
+### (c) 2005 Straylight/Edgeware
+###
 
-#----- Licensing notice -----------------------------------------------------
-#
-# This file is part of the Python interface to mLib.
-#
-# mLib/Python is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# mLib/Python is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with mLib/Python; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+###----- Licensing notice ---------------------------------------------------
+###
+### This file is part of the Python interface to mLib.
+###
+### mLib/Python is free software; you can redistribute it and/or modify
+### it under the terms of the GNU General Public License as published by
+### the Free Software Foundation; either version 2 of the License, or
+### (at your option) any later version.
+###
+### mLib/Python is distributed in the hope that it will be useful,
+### but WITHOUT ANY WARRANTY; without even the implied warranty of
+### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+### GNU General Public License for more details.
+###
+### You should have received a copy of the GNU General Public License
+### along with mLib/Python; if not, write to the Free Software Foundation,
+### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
 cdef class SelResolve:
+  """Abstract superclass for background name resolution."""
   cdef bres_client r
   cdef int _activep
   cdef _resolved
@@ -37,9 +36,11 @@ cdef class SelResolve:
       me._dead()
       bres_abort(&me.r)
   property activep:
+    """BR.activep: is lookup still waiting?"""
     def __get__(me):
       return _tobool(me._activep)
   def kill(me):
+    """BR.kill(): cancel in-progress lookup"""
     if not me._activep:
       raise ValueError, 'already dead'
     me._dead()
@@ -49,8 +50,10 @@ cdef class SelResolve:
     me._activep = 0
     me.dead()
   def dead(me):
+    """BR.dead(): called when lookup completes or is cancelled"""
     pass
   property resolvedproc:
+    """BR.resolvedproc -> FUNC: call FUNC(NAME, ALIASES, ADDRS) when ok"""
     def __get__(me):
       return me._resolved
     def __set__(me, proc):
@@ -58,6 +61,7 @@ cdef class SelResolve:
     def __del__(me):
       me._resolved = None
   property failedproc:
+    """BR.failedproc -> FUNC: call FUNC() when lookup fails"""
     def __get__(me):
       return me._failed
     def __set__(me, proc):
@@ -65,12 +69,22 @@ cdef class SelResolve:
     def __del__(me):
       me._failed = None
   def resolved(me, name, aliases, addrs):
+    """BR.resolved(NAME, ALIASES, ADDRS): called when lookup completes"""
     return _maybecall(me._resolved, (name, aliases, addrs))
   def failed(me):
+    """BR.failed(): called when lookup fails"""
     return _maybecall(me._failed, ())
 
 cdef class SelResolveByName (SelResolve):
-  def __new__(me, char *name, resolvedproc = None, failedproc = None,
+  """
+  Resolve a hostname to an IP address, asynchronously.
+
+  SelResolveByName(NAME, [resolvedproc = None], [failedproc = None])
+
+  Calls RESOLVEDPROC(NAME, ALIASES, ADDRS) on success, or FAILEDPROC() on
+  failure.
+  """
+  def __cinit__(me, char *name, resolvedproc = None, failedproc = None,
               *hunoz, **hukairz):
     me._resolved = _checkcallable(resolvedproc, 'resolved proc')
     me._failed = _checkcallable(failedproc, 'failed proc')
@@ -80,7 +94,15 @@ cdef class SelResolveByName (SelResolve):
     pass
 
 cdef class SelResolveByAddr (SelResolve):
-  def __new__(me, char *addr, resolvedproc = None, failedproc = None,
+  """
+  Resolve an IPv4 address to a hostname, asynchronously.
+
+  SelResolveByAddr(ADDR, [resolvedproc = None], [failedproc = None])
+
+  Calls RESOLVEDPROC(NAME, ALIASES, ADDRS) on success, or FAILEDPROC() on
+  failure.
+  """
+  def __cinit__(me, char *addr, resolvedproc = None, failedproc = None,
               *hunoz, **hukairz):
     cdef in_addr ia
     if not inet_aton(addr, &ia):
@@ -115,4 +137,4 @@ cdef void _resfunc(hostent *h, void *arg):
 bres_exec(NULL)
 bres_init(&_sel)
 
-#----- That's all, folks ----------------------------------------------------
+###----- That's all, folks --------------------------------------------------