X-Git-Url: https://git.distorted.org.uk/~mdw/mLib-python/blobdiff_plain/579d01693c86259110fe7a2c2a6f005f1bdbad5b..refs/heads/mdw/python3.cython:/mapping.pyx

diff --git a/mapping.pyx b/mapping.pyx
index aa5de85..d007a17 100644
--- a/mapping.pyx
+++ b/mapping.pyx
@@ -1,43 +1,39 @@
-# -*-pyrex-*-
-#
-# $Id$
-#
-# Common mapping stuff
-#
-# (c) 2005 Straylight/Edgeware
-#
+### -*-pyrex-*-
+###
+### Common mapping stuff
+###
+### (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.
-
-cdef class Mapping
+###----- 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 _MapIterator:
   cdef void *_next(me):
     return NULL
 
-cdef class Mapping:
+cdef class _Mapping:
 
-  ## Subclasses must implement these
+  ## Subclasses must implement these.
   cdef int _init(me) except -1:
-    raise TypeError, 'abstract class'
+    raise TypeError('abstract class')
   cdef void *_find(me, object key, unsigned *f) except NULL:
-    raise SystemError, 'unimplemented _find'
+    raise SystemError('unimplemented _find')
   cdef object _key(me, void *e):
     return None
   cdef object _value(me, void *e):
@@ -47,16 +43,16 @@ cdef class Mapping:
   cdef void _del(me, void *e):
     pass
   cdef _MapIterator _iter(me):
-    raise SystemError, 'unimplemented _iter'
+    raise SystemError('unimplemented _iter')
 
-  ## Initialization
-  def __new__(me, *hunoz, **hukairz):
-    me._init()
+  ## Initialization.
   def __init__(me, stuff = None, **kw):
-    me.update(stuff, kw)
+    me._init()
+    me.update(stuff, **kw)
 
-  ## Bulk update
+  ## Bulk update.
   def update(me, stuff = None, **kw):
+    """D.update([MAP], **KW): insert mappings from MAP and KW"""
     cdef unsigned f
     if stuff is None:
       pass
@@ -73,79 +69,81 @@ cdef class Mapping:
       me._setval(me._find(k, &f), v)
     return me
 
-  ## Item access
+  ## Item access.
   def __getitem__(me, key):
-    cdef void *e
-    e = me._find(key, NULL)
-    if not e:
-      raise KeyError, key
+    cdef void *e = me._find(key, NULL)
     return me._value(e)
   def __setitem__(me, key, value):
     cdef unsigned f
     me._setval(me._find(key, &f), value)
   def __delitem__(me, key):
-    cdef void *e
     cdef unsigned f
-    e = me._find(key, &f)
+    cdef void *e = me._find(key, &f)
     if not e:
-      raise KeyError, key
+      raise KeyError(key)
     me._del(e)
   def get(me, key, default = None):
-    cdef void *e
-    e = me._find(key, NULL)
+    """D.get(KEY, [default = None]) -> VALUE: value at KEY, or DEFAULT"""
+    cdef void *e = me._find(key, NULL)
     if not e:
       return default
     return me._value(e)
   def setdefault(me, key, default = None):
-    cdef void *e
+    """
+    D.setdefault(KEY, [default = None]) -> VALUE:
+      return value at key, or store DEFAULT at key and return that"""
     cdef unsigned f
-    e = me._find(key, &f)
+    cdef void *e = me._find(key, &f)
     if f:
       return me._value(e)
     else:
       me._setval(e, default)
       return default
   def pop(me, key, default = None):
-    cdef void *e
-    e = me._find(key, NULL)
+    """
+    D.pop(KEY, [default = None]) -> VALUE:
+      return value at key or DEFAULT, and remove KEY"""
+    cdef void *e = me._find(key, NULL)
     if not e:
       return default
     rc = me._value(e)
     me._del(e)
     return rc
   def popitem(me):
-    cdef _MapIterator i
-    cdef void *e
-    i = me._iter()
-    e = i._next()
+    """D.popitem() -> KEY, VALUE: return and remove an association pair"""
+    cdef _MapIterator i = me._iter()
+    cdef void *e = i._next()
     if not e:
-      raise ValueError, 'popitem(): table is empty'
+      raise ValueError('popitem(): table is empty')
     return me._key(e), me._value(e)
 
-  ## Lists of items
-  cdef object _list(me, object (*func)(Mapping m, void *e)):
-    cdef _MapIterator i
-    cdef void *e
-    i = me._iter()
-    l = []
-    while 1:
-      e = i._next()
-      if not e:
-        break
-      l.append(func(me, e))
-    return l
-    
-  def keys(me):
-    return me._list(_map_key)
-  def values(me):
-    return me._list(_map_value)
-  def items(me):
-    return me._list(_map_item)
+  ## Lists of items.
+  IF PYVERSION < (3,):
+    cdef object _list(me, object (*func)(_Mapping m, void *e)):
+      cdef _MapIterator i = me._iter()
+      cdef void *e
+      l = []
+      while 1:
+        e = i._next()
+        if not e:
+          break
+        l.append(func(me, e))
+      return l
+
+    def keys(me):
+      """D.keys() -> LIST: return a list of known keys"""
+      return me._list(_map_key)
+    def values(me):
+      """D.values() -> LIST: return a list of known values"""
+      return me._list(_map_value)
+    def items(me):
+      """D.items() -> LIST: return a list of known (KEY, VALUE) pairs"""
+      return me._list(_map_item)
 
   def clear(me):
-    cdef _MapIterator i
+    """D.clear(): remove all mappings"""
+    cdef _MapIterator i = me._iter()
     cdef void *e
-    i = me._iter()
     while 1:
       e = i._next()
       if not e:
@@ -153,49 +151,66 @@ cdef class Mapping:
       me._del(e)
     return me
 
-  ## Iteration
+  ## Iteration.
   def __iter__(me):
     return MapKeyIter(me)
-  def iterkeys(me):
-    return MapKeyIter(me)
-  def itervalues(me):
-    return MapValueIter(me)
-  def iteritems(me):
-    return MapItemIter(me)
-  
-cdef class MapIterBase:
-  cdef Mapping m
-  cdef object (*func)(Mapping m, void *e)
+  IF PYVERSION >= (3,):
+    def keys(me):
+      """D.keys() -> ITER: return iterator over keys"""
+      return MapKeyIter(me)
+    def values(me):
+      """D.values() -> ITER: return iterator over values"""
+      return MapValueIter(me)
+    def items(me):
+      """D.items() -> ITER: return iterator over (KEY, VALUE) pairs"""
+      return MapItemIter(me)
+  ELSE:
+    def iterkeys(me):
+      """D.iterkeys() -> ITER: return iterator over keys"""
+      return MapKeyIter(me)
+    def itervalues(me):
+      """D.itervalues() -> ITER: return iterator over values"""
+      return MapValueIter(me)
+    def iteritems(me):
+      """D.iteritems() -> ITER: return iterator over (KEY, VALUE) pairs"""
+      return MapItemIter(me)
+
+cdef class _MapIterBase:
+  cdef _Mapping m
+  cdef object (*func)(_Mapping m, void *e)
   cdef _MapIterator i
   cdef int _init(me) except -1:
-    raise TypeError, 'abstract class'
-  def __new__(me):
+    raise TypeError('abstract class')
+  def __init__(me, _Mapping m):
+    me.m = m
     me.i = m._iter()
     me._init()
+  def __iter__(me):
+    return me
   def __next__(me):
     cdef void *e
     e = me.i._next()
     if not e:
       raise StopIteration
     return me.func(me.m, e)
-cdef class MapKeyIter (MapIterBase):
+cdef class MapKeyIter (_MapIterBase):
   cdef int _init(me) except -1:
     me.func = _map_key
     return 0
-cdef class MapValueIter (MapIterBase):
+cdef class MapValueIter (_MapIterBase):
   cdef int _init(me) except -1:
     me.func = _map_value
     return 0
-cdef class MapItemIter (MapIterBase):
+cdef class MapItemIter (_MapIterBase):
   cdef int _init(me) except -1:
     me.func = _map_item
     return 0
 
-cdef object _map_key(Mapping m, void *e):
+cdef object _map_key(_Mapping m, void *e):
   return m._key(e)
-cdef object _map_value(Mapping m, void *e):
+cdef object _map_value(_Mapping m, void *e):
   return m._value(e)
-cdef object _map_item(Mapping m, void *e):
+cdef object _map_item(_Mapping m, void *e):
   return m._key(e), m._value(e)
 
-#----- That's all, folks ----------------------------------------------------
+###----- That's all, folks --------------------------------------------------