changeset 4791:1b84b35fbe91

Groups2009: Docstring refinements provided by ThomasWaldmann for the BackendManager, GroupManager and related tests.
author Dmitrijs Milajevs <dimazest@gmail.com>
date Sun, 07 Jun 2009 15:25:28 +0200
parents cb95dae6cbe0
children 7a826f946da3
files MoinMoin/groups/__init__.py MoinMoin/groups/_tests/test_backend_manager.py MoinMoin/groups/_tests/test_group_manager.py MoinMoin/groups/_tests/test_group_manager_acl.py
diffstat 4 files changed, 57 insertions(+), 95 deletions(-) [+]
line wrap: on
line diff
--- a/MoinMoin/groups/__init__.py	Sun Jun 07 15:25:23 2009 +0200
+++ b/MoinMoin/groups/__init__.py	Sun Jun 07 15:25:28 2009 +0200
@@ -1,9 +1,6 @@
 # -*- coding: iso-8859-1 -*-
-
 """
-MoinMoin - group definition access via various backends.
-
-TODO Group name mapping for the BackendManager.
+MoinMoin - group access via various backends.
 
 @copyright: 2009 DmitrijsMilajevs
 @license: GPL, see COPYING for details
@@ -12,31 +9,26 @@
 
 class BackendManager(object):
     """
-    BackendManager maps string to the Group object. String represents
-    group name. It provides access to groups of specific backend.
+    A BackendManager maps a group name to a Group object.
+    It provides access to groups of one specific backend.
     """
 
     def __init__(self, backend, mapper_to_backend=lambda x: x, mapper_from_backend=lambda x: x):
         """
-        Creates backend manager object.
+        Create backend manager object.
 
         XXX Decorators can be used for group name mapping.
 
         @param request: request object.
 
-        @type backend: group backend object.
-        @param backend: the backend which provides access to the group
-        definitions.
+        @param backend: the group backend which provides access to the
+                        group definitions.
 
-        @type mapper_to_backend: function which takes one string as an
-        argument and returns a string
-        @param mapper_to_backend: function which maps moin group
-        name to the backend group name
+        @param mapper_to_backend: a function mapping the moin group
+                                  name to the backend group name
 
-        @type mapper_from_backend: function which takes one string as an
-        argument and returns a string
-        @param mapper_from_backend: function which maps backend group
-        name to the moin group name
+        @param mapper_from_backend: a function mapping the backend
+                                    group name to the moin group name
         """
         self._backend = backend
         self.mapper_to_backend = mapper_to_backend
@@ -44,33 +36,32 @@
 
     def __getitem__(self, group_name):
         """
-        Selection of a group by its name.
+        Get a group by its name.
 
-        @type group_name: unicode string.
-        @param group_name: name of the group which object to select.
+        @param group_name: name of the group [unicode]
         """
         return self._backend[self.mapper_to_backend(group_name)]
 
     def __iter__(self):
         """
-        Iteration over group names.
+        Iterate over group names of the groups defined in this backend.
         """
         return (self.mapper_from_backend(group_name) for group_name in self._backend)
 
     def __contains__(self, group_name):
         """
-        Check if a group called group name is avaliable via this backend.
+        Check if a group called group_name is available in this backend.
 
-        @type group_name: unicode string.
-        @param group_name: name of the group which is checked for an containment.
+        @param group_name: name of the group [unicode]
         """
         return self.mapper_to_backend(group_name) in self._backend
 
     def membergroups(self, member):
         """
-        List all groups where member is a member of.
-        @rtype: list of unicode strings
-        @return: list of group names in which member takes part in
+        List all group names of the groups where <member> is a member of.
+
+        @param member: member name [unicode]
+        @return: list of group names [unicode]
         """
         return [group_name for group_name in self
                 if member in self[group_name]]
@@ -85,15 +76,16 @@
         """
         Create a group manager object.
 
-        @type backends: list of objects.
-        @param backend: group backends which are used to get access to the
-        group definitions.
+        @param backends: list of group backends which are used to get
+                         access to the group definitions.
         """
         self._backends = backends
 
     def __getitem__(self, group_name):
         """
-        Selection of a group by its name.
+        Get a group by its name. First match counts.
+
+        @param group_name: name of the group [unicode]
         """
         for backend in self._backends:
             if group_name in backend:
@@ -102,7 +94,7 @@
 
     def __iter__(self):
         """
-        Iteration over groups names.
+        Iterate over group names in all backends (filtering duplicates).
         """
         yielded_groups = set()
 
@@ -114,20 +106,24 @@
 
     def __contains__(self, group_name):
         """
-        Check if a group called group_name is defined.
+        Check if a group called group_name is available in any of the backends.
+
+        @param group_name: name of the group [unicode]
         """
         for backend in self._backends:
             if group_name in backend:
                 return True
+        return False
 
     def membergroups(self, member):
         """
-        List all groups where member is a member of.
-        @rtype: list of unicode strings
-        @return: list of group names in which member takes part in
+        List all group names of the groups where <member> is a member of.
+
+        @param member: member name [unicode]
+        @return: list of group names [unicode]
         """
         return [group_name for group_name in self
-                         if member in self[group_name]]
+                if member in self[group_name]]
 
     def update_cache(self):
         for backend in self._backends:
--- a/MoinMoin/groups/_tests/test_backend_manager.py	Sun Jun 07 15:25:23 2009 +0200
+++ b/MoinMoin/groups/_tests/test_backend_manager.py	Sun Jun 07 15:25:28 2009 +0200
@@ -12,10 +12,7 @@
 from MoinMoin.groups import BackendManager
 
 
-class TestBackendManagerAPI(object):
-    """
-    This tastcase test Backend manager API
-    """
+class TestBackendManager(object):
 
     def setup_method(self, method):
         self.admin_group = frozenset([u'Admin', u'JohnDoe'])
@@ -29,30 +26,18 @@
         self.group_backend = BackendManager(backend=groups)
 
     def test_getitem(self):
-        """
-        Test of the __getitem__ API method. It should return a group
-        object by the group name.
-        """
         assert self.admin_group == self.group_backend[u'AdminGroup']
         assert self.fruit_group == self.group_backend[u'FruitGroup']
 
         raises(KeyError, lambda: self.group_backend[u'not existing group'])
 
     def test_contains(self):
-        """
-        Test of the __contains__ API method. It checks if a group is
-        avaliable via this backend. Check is done by group's name.
-        """
         assert u'AdminGroup' in self.group_backend
         assert u'FruitGroup' in self.group_backend
 
         assert u'not existing group' not in self.group_backend
 
     def  test_membergroups(self):
-        """
-        Test of membergroups API method. It lists all groups where
-        member is a member of. It should  return a list of group names.
-        """
         apple_groups = self.group_backend.membergroups(u'Apple')
         assert 1 == len(apple_groups)
         assert u'FruitGroup' in apple_groups
@@ -67,28 +52,28 @@
 
 class TestManagerMapping(object):
     """
-    This class tests mapping of the group names from a backend to the
-    moin and from the moin to a backend.
+    Test group name mapping:
+        moin -> backend (e.g. "AdminGroup" -> "Admin")
+        backend -> moin (e.g. "Admin" -> "AdminGroup")
 
-    Here the simplest situation is considered. Moin expect groups to
-    be named as *Group, but backend stores group names without this prefix.
-
-    When group names are passed or retrieved from the backend they
-    should be mapped.
+    Moin expects group names to match the page_group_regex (e.g. "AdminGroup"),
+    but a backend might want to use different group names (e.g. just "Admin").
     """
 
     def setup_class(self):
         self.admin_group = frozenset([u'Admin', u'JohnDoe'])
         self.editor_group = frozenset([u'MainEditor', u'JohnDoe'])
 
-        # Group names here do not follow moin convention: they do not
-        # have group prefix.
+        # These backend group names do not follow moin convention:
         groups = {u'Admin': self.admin_group,
                   u'Editor': self.editor_group}
 
-        # Simply drop last five letters, what is length of word "Group"
+        # Simply drop the "Group" postfix for group names given to a backend.
+        # Note: in the real world, this would not work good enough:
         mapper_to_backend = lambda group_name: group_name[:-5]
-        # Add "Group" postfix for every group name received from a backend
+
+        # Add "Group" postfix for group names received from a backend.
+        # Note: in the real world, this would not work good enough:
         mapper_from_backend = lambda group_name: "%sGroup" % group_name
 
         self.group_backend = BackendManager(backend=groups,
--- a/MoinMoin/groups/_tests/test_group_manager.py	Sun Jun 07 15:25:23 2009 +0200
+++ b/MoinMoin/groups/_tests/test_group_manager.py	Sun Jun 07 15:25:28 2009 +0200
@@ -13,10 +13,7 @@
 from MoinMoin.groups import BackendManager, GroupManager
 
 
-class TestGroupManagerAPI(object):
-    """
-    Performs test of the API of GroupManager.
-    """
+class TestGroupManager(object):
 
     from MoinMoin._tests import wikiconfig
     class Config(wikiconfig.Config):
@@ -30,8 +27,8 @@
 
         user_group = frozenset([u'JohnDoe', u'Bob', u'Joe'])
         city_group = frozenset([u'Bolzano', u'Riga', u'London'])
-        # Suppose, someone hacked second backend
-        # and added himself to AdminGroup
+
+        # Suppose, someone hacked second backend and added himself to AdminGroup
         second_admin_group = frozenset([u'TheHacker'])
 
         second_backend_groups = {u'UserGroup': user_group,
@@ -48,33 +45,25 @@
         self.groups = self.request.groups
 
     def test_getitem(self):
-        """
-        Tests __getitem__ API method. It should return a group by its name.
-        """
         assert self.request.cfg.fruit_group == self.groups[u'FruitGroup']
         raises(KeyError, lambda: self.groups[u'not existing group'])
 
     def test_clashed_getitem(self):
         """
-        This test check situation when groups with a same name are
-        defined in several backends. In this case, the only one
-        backend must be taken in consideration, that backend which is
-        defined first in the backends list.
+        Check the case when groups of the same name are defined in multiple
+        backends. __getitem__ should return the first match (backends are
+        considered in the order they are given in the backends list).
         """
         admin_group = self.groups[u'AdminGroup']
 
         assert self.request.cfg.admin_group == admin_group
 
-        # Nevertheless, TheHacker added himself to the second backend,
-        # it must not be taken into consideration, because AdminGroup is defined
-        # in first backend
+        # TheHacker added himself to the second backend, but that must not be
+        # taken into consideration, because AdminGroup is defined in first
+        # backend and we only use the first match.
         assert u'TheHacker' not in admin_group
 
     def test_iter(self):
-        """
-        Tests __iter__ API method. It should iterate over all groups
-        available via backends. It should avoid group name clashes.
-        """
         all_group_names = [group_name for group_name in self.groups]
 
         assert 5 == len(all_group_names)
@@ -82,19 +71,10 @@
         assert len(set(all_group_names)) == len(all_group_names)
 
     def test_contains(self):
-        """
-        Tests __contains__ API method. It should check if a group
-        called group_name is available via some backend.
-        """
         assert u'UserGroup' in self.groups
         assert u'not existing group' not in self.groups
 
     def test_membergroups(self):
-        """
-        Tests membergroups API method. It should lists all groups
-        where member is a member of. It should return a list of group
-        names.
-        """
         apple_groups = self.groups.membergroups(u'Apple')
         assert 1 == len(apple_groups)
         assert u'FruitGroup' in apple_groups
--- a/MoinMoin/groups/_tests/test_group_manager_acl.py	Sun Jun 07 15:25:23 2009 +0200
+++ b/MoinMoin/groups/_tests/test_group_manager_acl.py	Sun Jun 07 15:25:28 2009 +0200
@@ -13,7 +13,7 @@
 
 class TestGroupManagerACL:
     """
-    Test how GroupManager works with acl code.
+    Test how GroupManager works with the acl code.
     """
 
     from MoinMoin._tests import wikiconfig
@@ -42,3 +42,4 @@
 
 
 coverage_modules = ['MoinMoin.groups']
+