incubator-allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From brond...@apache.org
Subject [1/2] git commit: [#7173] improve auth docs; expose auth and more artifact model docs
Date Thu, 13 Feb 2014 19:24:02 GMT
Updated Branches:
  refs/heads/db/7173 [created] e10553225


[#7173] improve auth docs; expose auth and more artifact model docs


Project: http://git-wip-us.apache.org/repos/asf/incubator-allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-allura/commit/f29392e8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/f29392e8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/f29392e8

Branch: refs/heads/db/7173
Commit: f29392e8300c6b02e5a848a791e15dd089a2fc7c
Parents: cab6cfa
Author: Dave Brondsema <dave@brondsema.net>
Authored: Thu Feb 13 11:59:55 2014 -0500
Committer: Dave Brondsema <dave@brondsema.net>
Committed: Thu Feb 13 11:59:55 2014 -0500

----------------------------------------------------------------------
 Allura/allura/lib/security.py    | 28 +++++++++++++++++++---------
 Allura/allura/model/auth.py      |  4 ++--
 Allura/docs/api/lib/security.rst | 28 ++++++++++++++++++++++++++++
 Allura/docs/api/model.rst        | 31 +++++++++++++++++++++++++++++++
 Allura/docs/index.rst            | 30 +++++++++++++++---------------
 5 files changed, 95 insertions(+), 26 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/f29392e8/Allura/allura/lib/security.py
----------------------------------------------------------------------
diff --git a/Allura/allura/lib/security.py b/Allura/allura/lib/security.py
index a0d6c1e..c460c21 100644
--- a/Allura/allura/lib/security.py
+++ b/Allura/allura/lib/security.py
@@ -43,13 +43,15 @@ class Credentials(object):
 
     @property
     def project_role(self):
+        # bypass Ming model validation and use pymongo directly
+        # for improved performance
         from allura import model as M
         db = M.session.main_doc_session.db
         return db[M.ProjectRole.__mongometa__.name]
 
     @classmethod
     def get(cls):
-        'get the global Credentials instance'
+        'get the global :class:`Credentials` instance'
         import allura
         return allura.credentials
 
@@ -113,7 +115,7 @@ class Credentials(object):
 
     def project_roles(self, project_id):
         '''
-        :returns: a RoleCache of ProjectRoles for project_id
+        :returns: a :class:`RoleCache` of :class:`ProjectRoles <allura.model.auth.ProjectRole>`
for project_id
         '''
         roles = self.projects.get(project_id)
         if roles is None:
@@ -123,7 +125,7 @@ class Credentials(object):
 
     def user_roles(self, user_id, project_id=None):
         '''
-        :returns: a RoleCache of ProjectRoles for given user_id and project_id, *anonymous
and *authenticated checked as appropriate
+        :returns: a :class:`RoleCache` of :class:`ProjectRoles <allura.model.auth.ProjectRole>`
for given user_id and optional project_id, ``*anonymous`` and ``*authenticated`` checked as
appropriate
         '''
         roles = self.users.get((user_id, project_id))
         if roles is None:
@@ -154,8 +156,15 @@ class Credentials(object):
 
 
 class RoleCache(object):
+    '''
+    An iterable collection of :class:`ProjectRoles <allura.model.auth.ProjectRole>`
that is cached after first use
+    '''
 
     def __init__(self, cred, q):
+        '''
+        :param `Credentials` cred: :class:`Credentials`
+        :param iterable q: An iterable (e.g a query) of :class:`ProjectRoles <allura.model.auth.ProjectRole>`
+        '''
         self.cred = cred
         self.q = q
 
@@ -361,24 +370,25 @@ def all_allowed(obj, user_or_role=None, project=None):
     '''
     List all the permission names that a given user or named role
     is allowed for a given object.  This list reflects the permissions
-    for which has_access() would return True for the user (or a user
+    for which ``has_access()`` would return True for the user (or a user
     in the given named role, e.g. Developer).
 
     Example:
 
-        Given a tracker with the following ACL (pseudo-code):
+        Given a tracker with the following ACL (pseudo-code)::
+
             [
                 ACE.allow(ProjectRole.by_name('Developer'), 'create'),
                 ACE.allow(ProjectRole.by_name('Member'), 'post'),
                 ACE.allow(ProjectRole.by_name('*anonymous'), 'read'),
             ]
 
-        And user1 is in the Member group, then all_allowed(tracker, user1)
-        will return:
+        And user1 is in the Member group, then ``all_allowed(tracker, user1)``
+        will return::
 
             set(['post', 'read'])
 
-        And all_allowed(tracker, ProjectRole.by_name('Developer')) will return:
+        And ``all_allowed(tracker, ProjectRole.by_name('Developer'))`` will return::
 
             set(['create', 'post', 'read'])
     '''
@@ -427,7 +437,7 @@ def all_allowed(obj, user_or_role=None, project=None):
 
 def require(predicate, message=None):
     '''
-    Example: require(has_access(c.app, 'read'))
+    Example: ``require(has_access(c.app, 'read'))``
 
     :param callable predicate: truth function to call
     :param str message: message to show upon failure

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/f29392e8/Allura/allura/model/auth.py
----------------------------------------------------------------------
diff --git a/Allura/allura/model/auth.py b/Allura/allura/model/auth.py
index dfbfc32..3c227f2 100644
--- a/Allura/allura/model/auth.py
+++ b/Allura/allura/model/auth.py
@@ -590,7 +590,7 @@ class User(MappedClass, ActivityNode, ActivityObject):
     def url(self):
         '''
         Return the URL (relative to root domain) for this user's user-project.
-        This includes any special handling via the Auth Provider to determine the proper
user-project name
+        This includes any special handling via the :class:`~allura.lib.plugin.AuthenticationProvider`
to determine the proper user-project name
         '''
         return '/%s/' % plugin.AuthenticationProvider.get(request).user_project_shortname(self)
 
@@ -815,7 +815,7 @@ class ProjectRole(MappedClass):
     :var user_id: used if this role is for a single user
     :var project_id:
     :var name:
-    :var roles: a list of other ProjectRole objectids
+    :var roles: a list of other :class:`ProjectRole` ``ObjectId`` values.  These roles are
delegated through the current role.
     """
 
     class __mongometa__:

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/f29392e8/Allura/docs/api/lib/security.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/lib/security.rst b/Allura/docs/api/lib/security.rst
new file mode 100644
index 0000000..eb8ead3
--- /dev/null
+++ b/Allura/docs/api/lib/security.rst
@@ -0,0 +1,28 @@
+..     Licensed to the Apache Software Foundation (ASF) under one
+       or more contributor license agreements.  See the NOTICE file
+       distributed with this work for additional information
+       regarding copyright ownership.  The ASF licenses this file
+       to you under the Apache License, Version 2.0 (the
+       "License"); you may not use this file except in compliance
+       with the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing,
+       software distributed under the License is distributed on an
+       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+       KIND, either express or implied.  See the License for the
+       specific language governing permissions and limitations
+       under the License.
+
+.. _spam_module:
+
+:mod:`allura.lib.security`
+-------------------------------------
+
+.. automodule:: allura.lib.security
+    :members:
+
+    .. autoclass:: RoleCache
+        :members:
+        :special-members: __init__

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/f29392e8/Allura/docs/api/model.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/model.rst b/Allura/docs/api/model.rst
index 2d30d1d..363b85e 100644
--- a/Allura/docs/api/model.rst
+++ b/Allura/docs/api/model.rst
@@ -26,3 +26,34 @@
 
     .. autoclass:: Artifact
         :members:
+        :special-members: __json__
+
+    .. autoclass:: Snapshot
+        :members:
+
+    .. autoclass:: VersionedArtifact
+        :members:
+
+    .. autoclass:: Message
+        :members:
+
+    .. autoclass:: Feed
+        :members:
+
+    .. autoclass:: VotableArtifact
+        :members:
+
+    .. autoclass:: MovedArtifact
+        :members:
+
+  .. automodule:: allura.model.auth
+
+    .. autoclass:: User
+        :members:
+
+    .. autoclass:: ProjectRole
+        :members:
+
+    .. autoclass:: AuditLog
+        :members:
+

http://git-wip-us.apache.org/repos/asf/incubator-allura/blob/f29392e8/Allura/docs/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/index.rst b/Allura/docs/index.rst
index 98fc5cb..14c121b 100644
--- a/Allura/docs/index.rst
+++ b/Allura/docs/index.rst
@@ -47,21 +47,6 @@ Using Allura
 
    using
 
-Developing Allura
-=====================================================================
-
-.. toctree::
-   :maxdepth: 3
-
-   contributing
-   platform
-   platform_tour
-   guides/message_bus
-   guides/email
-   guides/permissions
-   tutorials/testing
-
-
 Extending Allura
 =====================================================================
 
@@ -77,6 +62,21 @@ Extending Allura
     * `Adding a Sidebar Menu <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/12/adding-a-sidebar-menu/>`_
     * `Adding Custom CSS <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/12/part-5-adding-custom-css/>`_
 
+Developing Allura
+=====================================================================
+
+.. toctree::
+   :maxdepth: 3
+
+   contributing
+   platform
+   platform_tour
+   guides/message_bus
+   guides/email
+   guides/permissions
+   tutorials/testing
+
+
 API Documentation
 ==================
 


Mime
View raw message