<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[11892] CalendarServer/trunk/twext/who</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://trac.calendarserver.org//changeset/11892">11892</a></dd>
<dt>Author</dt> <dd>wsanchez@apple.com</dd>
<dt>Date</dt> <dd>2013-11-06 13:20:52 -0800 (Wed, 06 Nov 2013)</dd>
</dl>
<h3>Log Message</h3>
<pre>docs</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#CalendarServertrunktwextwhodirectorypy">CalendarServer/trunk/twext/who/directory.py</a></li>
<li><a href="#CalendarServertrunktwextwhoidirectorypy">CalendarServer/trunk/twext/who/idirectory.py</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="CalendarServertrunktwextwhodirectorypy"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/twext/who/directory.py (11891 => 11892)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/twext/who/directory.py 2013-11-06 20:11:38 UTC (rev 11891)
+++ CalendarServer/trunk/twext/who/directory.py 2013-11-06 21:20:52 UTC (rev 11892)
</span><span class="lines">@@ -26,7 +26,7 @@
</span><span class="cx">
</span><span class="cx"> from uuid import UUID
</span><span class="cx">
</span><del>-from zope.interface import implements
</del><ins>+from zope.interface import implementer
</ins><span class="cx">
</span><span class="cx"> from twisted.internet.defer import inlineCallbacks, returnValue
</span><span class="cx"> from twisted.internet.defer import succeed, fail
</span><span class="lines">@@ -40,19 +40,63 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><ins>+@implementer(IDirectoryService)
</ins><span class="cx"> class DirectoryService(object):
</span><del>- implements(IDirectoryService)
</del><ins>+ """
+ Generic implementation of L{IDirectoryService}.
</ins><span class="cx">
</span><ins>+ This is a complete implementation of L{IDirectoryService}, with support for
+ the query operands in L{Operand}.
+
+ The C{recordsWith*} methods are all implemented in terms of
+ L{recordsWithFieldValue}, which is in turn implemented in terms of
+ L{recordsFromExpression}.
+ L{recordsFromQuery} is also implemented in terms of
+ {recordsFromExpression}.
+
+ L{recordsFromExpression} (and therefore most uses of the other methods)
+ will always fail with a L{QueryNotSupportedError}.
+
+ A subclass should therefore override L{recordsFromExpression} with an
+ implementation that handles any queries that it can support and its
+ superclass' implementation with any query it cannot support.
+
+ A subclass may override L{recordsFromQuery} if it is to support additional
+ operands.
+
+ L{updateRecords} and L{removeRecords} will fail with L{NotAllowedError}
+ when asked to modify data.
+ A subclass should override these methods if is to allow editing of
+ directory information.
+
+ @cvar recordType: a L{Names} class or compatible object (eg.
+ L{ConstantsContainer}) which contains the L{NamedConstant}s denoting
+ the record types that are supported by this directory service.
+
+ @cvar fieldName: a L{Names} class or compatible object (eg.
+ L{ConstantsContainer}) which contains the L{NamedConstant}s denoting
+ the record field names that are supported by this directory service.
+
+ @cvar normalizedFields: a L{dict} mapping of (ie. L{NamedConstant}s
+ contained in the C{fieldName} class variable) to callables that take
+ a field value (a L{unicode}) and return a normalized field value (also
+ a L{unicode}).
+ """
+
</ins><span class="cx"> recordType = RecordType
</span><span class="cx"> fieldName = FieldName
</span><span class="cx">
</span><span class="cx"> normalizedFields = {
</span><span class="cx"> FieldName.guid: lambda g: UUID(g).hex,
</span><del>- FieldName.emailAddresses: lambda e: e.lower(),
</del><ins>+ FieldName.emailAddresses: lambda e: bytes(e).lower(),
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx">
</span><span class="cx"> def __init__(self, realmName):
</span><ins>+ """
+ @param realmName: a realm name
+ @type realmName: unicode
+ """
</ins><span class="cx"> self.realmName = realmName
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -70,11 +114,30 @@
</span><span class="cx"> def recordsFromExpression(self, expression, records=None):
</span><span class="cx"> """
</span><span class="cx"> Finds records matching a single expression.
</span><del>- @param expression: an expression
</del><ins>+
+ @note: The implementation in L{DirectoryService} always raises
+ L{QueryNotSupportedError}.
+
+ @note: This L{DirectoryService} adds a C{records} keyword argument to
+ the interface defined by L{IDirectoryService}.
+ This allows the implementation of
+ L{DirectoryService.recordsFromQuery} to narrow the scope of records
+ being searched as it applies expressions.
+ This is therefore relevant to subclasses, which need to support the
+ added parameter, but not to users of L{IDirectoryService}.
+
+ @param expression: an expression to apply
</ins><span class="cx"> @type expression: L{object}
</span><del>- @param records: a set of records to search within. C{None} if
</del><ins>+
+ @param records: a set of records to limit the search to. C{None} if
</ins><span class="cx"> the whole directory should be searched.
</span><span class="cx"> @type records: L{set} or L{frozenset}
</span><ins>+
+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
+
+ @raises: L{QueryNotSupportedError} if the expression is not
+ supported by this directory service.
</ins><span class="cx"> """
</span><span class="cx"> return fail(QueryNotSupportedError(
</span><span class="cx"> "Unknown expression: {0}".format(expression)
</span><span class="lines">@@ -158,17 +221,32 @@
</span><span class="cx"> def updateRecords(self, records, create=False):
</span><span class="cx"> for record in records:
</span><span class="cx"> return fail(NotAllowedError("Record updates not allowed."))
</span><ins>+ return succeed(None)
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx"> def removeRecords(self, uids):
</span><span class="cx"> for uid in uids:
</span><span class="cx"> return fail(NotAllowedError("Record removal not allowed."))
</span><ins>+ return succeed(None)
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><ins>+@implementer(IDirectoryRecord)
</ins><span class="cx"> class DirectoryRecord(object):
</span><del>- implements(IDirectoryRecord)
</del><ins>+ """
+ Generic implementation of L{IDirectoryService}.
</ins><span class="cx">
</span><ins>+ This is an incomplete implementation of L{IDirectoryRecord}.
+
+ L{groups} will always fail with L{NotImplementedError} and L{members} will
+ do so if this is a group record.
+ A subclass should override these methods to support group membership and
+ complete this implementation.
+
+ @cvar requiredFields: an iterable of field names that must be present in
+ all directory records.
+ """
+
</ins><span class="cx"> requiredFields = (
</span><span class="cx"> FieldName.uid,
</span><span class="cx"> FieldName.recordType,
</span></span></pre></div>
<a id="CalendarServertrunktwextwhoidirectorypy"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/twext/who/idirectory.py (11891 => 11892)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/twext/who/idirectory.py 2013-11-06 20:11:38 UTC (rev 11891)
+++ CalendarServer/trunk/twext/who/idirectory.py 2013-11-06 21:20:52 UTC (rev 11892)
</span><span class="lines">@@ -42,9 +42,9 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-##
</del><ins>+#
</ins><span class="cx"> # Exceptions
</span><del>-##
</del><ins>+#
</ins><span class="cx">
</span><span class="cx"> class DirectoryServiceError(Exception):
</span><span class="cx"> """
</span><span class="lines">@@ -55,7 +55,7 @@
</span><span class="cx">
</span><span class="cx"> class DirectoryConfigurationError(DirectoryServiceError):
</span><span class="cx"> """
</span><del>- Directory configurtion error.
</del><ins>+ Directory configuration error.
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -93,16 +93,19 @@
</span><span class="cx">
</span><span class="cx"> class NotAllowedError(DirectoryServiceError):
</span><span class="cx"> """
</span><del>- Apparently, you can't do that.
</del><ins>+ It seems you aren't permitted to do that.
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-##
</del><ins>+#
</ins><span class="cx"> # Data Types
</span><del>-##
</del><ins>+#
</ins><span class="cx">
</span><span class="cx"> class RecordType(Names):
</span><ins>+ """
+ Constants for common directory record types.
+ """
</ins><span class="cx"> user = NamedConstant()
</span><span class="cx"> group = NamedConstant()
</span><span class="cx">
</span><span class="lines">@@ -113,7 +116,31 @@
</span><span class="cx">
</span><span class="cx"> class FieldName(Names):
</span><span class="cx"> """
</span><del>- Constants for common field names.
</del><ins>+ Constants for common directory record field names.
+
+ Fields as assciated with either a single value or an iterable of values.
+
+ @cvar uid: The primary unique identifier for a directory record.
+ The associated value must be a L{unicode}.
+
+ @cvar guid: The globally unique identifier for a directory record.
+ The associated value must be a L{UUID} or C{None}.
+
+ @cvar recordType: The type of a directory record.
+ The associated value must be a L{NamedConstant}.
+
+ @cvar shortNames: The short names for a directory record.
+ The associated values must L{unicode}s and there must be at least
+ one associated value.
+
+ @cvar fullNames: The full names for a directory record.
+ The associated values must be L{unicode}s.
+
+ @cvar emailAddresses: The email addresses for a directory record.
+ The associated values must be L{unicodes}.
+
+ @cvar password: The clear text password for a directory record.
+ The associated value must be a L{unicode} or C{None}.
</ins><span class="cx"> """
</span><span class="cx"> uid = NamedConstant()
</span><span class="cx"> guid = NamedConstant()
</span><span class="lines">@@ -138,11 +165,20 @@
</span><span class="cx">
</span><span class="cx"> @staticmethod
</span><span class="cx"> def isMultiValue(name):
</span><ins>+ """
+ Check for whether a field is multi-value (as opposed to single-value).
+
+ @return: C{True} if the field is multi-value, C{False} otherwise.
+ @rtype: L{BOOL}
+ """
</ins><span class="cx"> return getattr(name, "multiValue", False)
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><span class="cx"> class Operand(Names):
</span><ins>+ """
+ Contants for common operands.
+ """
</ins><span class="cx"> OR = NamedConstant()
</span><span class="cx"> AND = NamedConstant()
</span><span class="cx">
</span><span class="lines">@@ -151,9 +187,9 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-##
</del><ins>+#
</ins><span class="cx"> # Interfaces
</span><del>-##
</del><ins>+#
</ins><span class="cx">
</span><span class="cx"> class IDirectoryService(Interface):
</span><span class="cx"> """
</span><span class="lines">@@ -169,7 +205,15 @@
</span><span class="cx">
</span><span class="cx"> A directory service may allow support the editing, removal and
</span><span class="cx"> addition of records.
</span><ins>+ Services are read-only should fail with L{NotAllowedError} in editing
+ methods.
+
+ The L{FieldName.uid} field, the L{FieldName.guid} field (if not C{None}),
+ and the combination of the L{FieldName.recordType} and
+ L{FieldName.shortName} fields must be unique to each directory record
+ vended by a directory service.
</ins><span class="cx"> """
</span><ins>+
</ins><span class="cx"> realmName = Attribute(
</span><span class="cx"> "The name of the authentication realm this service represents."
</span><span class="cx"> )
</span><span class="lines">@@ -177,8 +221,10 @@
</span><span class="cx">
</span><span class="cx"> def recordTypes():
</span><span class="cx"> """
</span><del>- @return: an iterable of L{NamedConstant}s denoting the record
- types that are kept in this directory.
</del><ins>+ Get the record types supported by this directory service.
+
+ @return: The record types that are supported by this directory service.
+ @rtype: iterable of L{NamedConstant}s
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -189,7 +235,8 @@
</span><span class="cx"> @param expression: an expression to apply
</span><span class="cx"> @type expression: L{object}
</span><span class="cx">
</span><del>- @return: a deferred iterable of matching L{IDirectoryRecord}s.
</del><ins>+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
</ins><span class="cx">
</span><span class="cx"> @raises: L{QueryNotSupportedError} if the expression is not
</span><span class="cx"> supported by this directory service.
</span><span class="lines">@@ -207,7 +254,8 @@
</span><span class="cx"> @param operand: an operand
</span><span class="cx"> @type operand: a L{NamedConstant}
</span><span class="cx">
</span><del>- @return: a deferred iterable of matching L{IDirectoryRecord}s.
</del><ins>+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
</ins><span class="cx">
</span><span class="cx"> @raises: L{QueryNotSupportedError} if the query is not
</span><span class="cx"> supported by this directory service.
</span><span class="lines">@@ -225,7 +273,8 @@
</span><span class="cx"> @param value: a value to match
</span><span class="cx"> @type value: L{bytes}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s.
</del><ins>+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -236,8 +285,8 @@
</span><span class="cx"> @param uid: a UID
</span><span class="cx"> @type uid: L{bytes}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s, or
- C{None} if there is no such record.
</del><ins>+ @return: The matching record or C{None} if there is no match.
+ @rtype: deferred L{IDirectoryRecord}s or C{None}
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -248,8 +297,8 @@
</span><span class="cx"> @param guid: a GUID
</span><span class="cx"> @type guid: L{bytes}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s, or
- C{None} if there is no such record.
</del><ins>+ @return: The matching record or C{None} if there is no match.
+ @rtype: deferred L{IDirectoryRecord}s or C{None}
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -260,7 +309,8 @@
</span><span class="cx"> @param recordType: a record type
</span><span class="cx"> @type recordType: L{NamedConstant}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s.
</del><ins>+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -274,8 +324,8 @@
</span><span class="cx"> @param shortName: a short name
</span><span class="cx"> @type shortName: L{bytes}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s, or
- C{None} if there is no such record.
</del><ins>+ @return: The matching record or C{None} if there is no match.
+ @rtype: deferred L{IDirectoryRecord}s or C{None}
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -286,8 +336,8 @@
</span><span class="cx"> @param emailAddress: an email address
</span><span class="cx"> @type emailAddress: L{bytes}
</span><span class="cx">
</span><del>- @return: a deferred iterable of L{IDirectoryRecord}s, or
- C{None} if there is no such record.
</del><ins>+ @return: The matching records.
+ @rtype: deferred iterable of L{IDirectoryRecord}s
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -300,6 +350,12 @@
</span><span class="cx">
</span><span class="cx"> @param create: if true, create records if necessary
</span><span class="cx"> @type create: boolean
</span><ins>+
+ @return: unspecifiied
+ @rtype: deferred object
+
+ @raises L{NotAllowedError}: if the update is not allowed by the
+ directory service.
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -309,6 +365,12 @@
</span><span class="cx">
</span><span class="cx"> @param uids: the UIDs of the records to remove
</span><span class="cx"> @type uids: iterable of L{bytes}
</span><ins>+
+ @return: unspecifiied
+ @rtype: deferred object
+
+ @raises L{NotAllowedError}: if the removal is not allowed by the
+ directory service.
</ins><span class="cx"> """
</span><span class="cx">
</span><span class="cx">
</span><span class="lines">@@ -349,6 +411,7 @@
</span><span class="cx"> """
</span><span class="cx"> Find the records that are members of this group. Only direct
</span><span class="cx"> members are included; members of members are not expanded.
</span><ins>+
</ins><span class="cx"> @return: a deferred iterable of L{IDirectoryRecord}s which are
</span><span class="cx"> direct members of this group.
</span><span class="cx"> """
</span><span class="lines">@@ -359,6 +422,7 @@
</span><span class="cx"> Find the group records that this record is a member of. Only
</span><span class="cx"> groups for which this record is a direct member is are
</span><span class="cx"> included; membership is not expanded.
</span><ins>+
</ins><span class="cx"> @return: a deferred iterable of L{IDirectoryRecord}s which are
</span><span class="cx"> groups that this record is a member of.
</span><span class="cx"> """
</span></span></pre>
</div>
</div>
</body>
</html>