Docs: Make clear that a userid need not be a principal.

2 files changed, 9 insertions, 7 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 77d80f6d6..3a32fd938 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -194,10 +194,12 @@
       .. versionadded:: 1.5
 
       A property which returns the list of 'effective' :term:`principal`
-      identifiers for this request.  This will include the userid of the
-      currently authenticated user if a user is currently authenticated. If no
-      :term:`authentication policy` is in effect, this will return a sequence
-      containing only the :attr:`pyramid.security.Everyone` principal.
+      identifiers for this request.  This list typically includes the
+      :term:`userid` of the currently authenticated user if a user is
+      currently authenticated, but this depends on the
+      :term:`authentication policy` in effect.  If no :term:`authentication
+      policy` is in effect, this will return a sequence containing only the
+      :attr:`pyramid.security.Everyone` principal.
 
    .. method:: invoke_subrequest(request, use_tweens=False)
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 8db23a33b..57d7ac38f 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -611,9 +611,9 @@ that implements the following interface:
 
        def effective_principals(self, request):
            """ Return a sequence representing the effective principals
-           including the userid and any groups belonged to by the current
-           user, including 'system' groups such as
-           ``pyramid.security.Everyone`` and
+           typically including the userid and any groups belonged to
+           by the current user, always including 'system' groups such
+           as ``pyramid.security.Everyone`` and
            ``pyramid.security.Authenticated``. """
 
        def remember(self, request, principal, **kw):