[CalendarServer-changes] [11962] CalendarServer/trunk/twext/who

[source_changes at macosforge.org]

Revision: 11962
          http://trac.calendarserver.org//changeset/11962
Author:   wsanchez at apple.com
Date:     2013-11-18 11:24:16 -0800 (Mon, 18 Nov 2013)
Log Message:
-----------
docs

Modified Paths:
--------------
    CalendarServer/trunk/twext/who/directory.py
    CalendarServer/trunk/twext/who/index.py

Modified: CalendarServer/trunk/twext/who/directory.py
===================================================================
--- CalendarServer/trunk/twext/who/directory.py	2013-11-18 18:17:18 UTC (rev 11961)
+++ CalendarServer/trunk/twext/who/directory.py	2013-11-18 19:24:16 UTC (rev 11962)
@@ -41,7 +41,7 @@
 @implementer(IDirectoryService)
 class DirectoryService(object):
     """
-    Generic implementation of L{IDirectoryService}.
+    Generic (and abstract) implementation of L{IDirectoryService}.
 
     Most of the C{recordsWith*} methods call L{recordsWithFieldValue}, which in
     turn calls L{recordsFromExpression} with a corresponding

Modified: CalendarServer/trunk/twext/who/index.py
===================================================================
--- CalendarServer/trunk/twext/who/index.py	2013-11-18 18:17:18 UTC (rev 11961)
+++ CalendarServer/trunk/twext/who/index.py	2013-11-18 19:24:16 UTC (rev 11962)
@@ -55,7 +55,91 @@
 
 class DirectoryService(BaseDirectoryService):
     """
-    XML directory service.
+    Generic (and abstract) in-memory-indexed directory service.
+
+    This class implements the record access API in L{BaseDirectoryService} by
+    caching all records in an in-memory dictionary.
+
+    Each indexed field has a top-level key in the index and in turn contains
+    a dictionary in which keys are field values, and values are directory
+    records which have a matching field value for the cooresponding key:
+
+        {
+            <FieldName1>: {
+                <value1a>: set([<record1a1>, ...]),
+                ...
+            },
+            ...
+        }
+
+    Here is an example index for a service with a three user records and one
+    group record:
+
+        {
+            <FieldName=uid>: {
+                u'__calendar-dev__': set([
+                    <DirectoryRecord (group)calendar-dev>
+                ]),
+                u'__dre__': set([
+                    <DirectoryRecord (user)dre>
+                ]),
+                u'__sagen__': set([
+                    <DirectoryRecord (user)sagen>
+                ]),
+                u'__wsanchez__': set([
+                    <DirectoryRecord (user)wsanchez>
+                ])
+            },
+            <FieldName=recordType>: {
+                <RecordType=group>: set([
+                    <DirectoryRecord (group)calendar-dev>,
+                ]),
+                <RecordType=user>: set([
+                    <DirectoryRecord (user)sagen>,
+                    <DirectoryRecord (user)wsanchez>
+                ])
+            },
+            <FieldName=shortNames>: {
+                u'calendar-dev': set([<DirectoryRecord (group)calendar-dev>]),
+                u'dre': set([<DirectoryRecord (user)dre>]),
+                u'sagen': set([<DirectoryRecord (user)sagen>]),
+                u'wilfredo_sanchez': set([<DirectoryRecord (user)wsanchez>]),
+                u'wsanchez': set([<DirectoryRecord (user)wsanchez>])
+            },
+            <FieldName=emailAddresses>: {
+                'dev at bitbucket.calendarserver.org': set([
+                    <DirectoryRecord (group)calendar-dev>
+                ]),
+                'dre at bitbucket.calendarserver.org': set([
+                    <DirectoryRecord (user)dre>
+                ]),
+                'sagen at bitbucket.calendarserver.org': set([
+                    <DirectoryRecord (user)sagen>
+                ]),
+                'shared at example.com': set([
+                    <DirectoryRecord (user)sagen>,
+                    <DirectoryRecord (user)dre>
+                ]),
+                'wsanchez at bitbucket.calendarserver.org': set([
+                    <DirectoryRecord (user)wsanchez>
+                ]),
+                'wsanchez at devnull.twistedmatrix.com': set([
+                    <DirectoryRecord (user)wsanchez>
+                ])
+            },
+            <FieldName=memberUIDs>: {
+                u'__sagen__': set([<DirectoryRecord (group)calendar-dev>]),
+                u'__wsanchez__': set([<DirectoryRecord (group)calendar-dev>])
+            },
+        }
+
+    The field names that are indexed are determined by the C{indexedFields}
+    attribute of the service.
+
+    A subclass must override L{loadRecords}, which populates the index.
+
+    @cvar indexedFields: an iterable of field names (C{NamedConstant})
+        which are indexed.
     """
 
     fieldName = ConstantsContainer(chain(
@@ -82,7 +166,7 @@
     @property
     def index(self):
         """
-        Call L{loadRecords}C{()} and return the index.
+        Call L{loadRecords} and return the index.
         """
         self.loadRecords()
         return self._index
@@ -101,7 +185,9 @@
 
     def loadRecords(self):
         """
-        Load records.
+        Load records.  This must be implemented by subclasses.
+
+        The implementation should set the index with current data.
         """
         raise NotImplementedError("Subclasses must implement loadRecords().")
 
@@ -223,6 +309,10 @@
 
 
     def recordsFromNonCompoundExpression(self, expression, records=None):
+        """
+        This implementation can handle L{MatchExpression} expressions; other
+        expressions are passed up to the superclass.
+        """
         if isinstance(expression, MatchExpression):
             if expression.fieldName in self.indexedFields:
                 return self.indexedRecordsFromMatchExpression(
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20140312/57bc8d6d/attachment.html>