chiark / gitweb /
debian/control: Add Build-Depends for `dh-python'.
[mLib-python] / bres.pyx
index 162ff02..8097855 100644 (file)
--- a/bres.pyx
+++ b/bres.pyx
@@ -1,41 +1,46 @@
-# -*-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
   cdef _failed
   def __init__(me, *hunoz, **hukairz):
     raise TypeError, 'abstract class'
+  def __dealloc__(me):
+    if me._activep:
+      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()
@@ -45,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):
@@ -54,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):
@@ -61,30 +69,48 @@ 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):
-    bres_byname(&me.r, name, _resfunc, <void *>me)
     me._resolved = _checkcallable(resolvedproc, 'resolved proc')
     me._failed = _checkcallable(failedproc, 'failed proc')
     me._activep = 1
+    bres_byname(&me.r, name, _resfunc, <void *>me)
   def __init__(me, name, resolvedproc = None, failedproc = None):
     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):
       raise TypeError, 'bad IP address'
-    bres_byaddr(&me.r, ia, _resfunc, <void *>me)
     me._resolved = _checkcallable(resolvedproc, 'resolved proc')
     me._failed = _checkcallable(failedproc, 'failed proc')
     me._activep = 1
+    bres_byaddr(&me.r, ia, _resfunc, <void *>me)
   def __init__(me, addr, resolvedproc = None, failedproc = None):
     pass
 
@@ -94,7 +120,7 @@ cdef void _resfunc(hostent *h, void *arg):
   r = <SelResolve>arg
   r._dead()
   if h is NULL:
-    r.failed(r)
+    r.failed()
   else:
     alias = []
     addr = []
@@ -111,4 +137,4 @@ cdef void _resfunc(hostent *h, void *arg):
 bres_exec(NULL)
 bres_init(&_sel)
 
-#----- That's all, folks ----------------------------------------------------
+###----- That's all, folks --------------------------------------------------