You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by tv...@apache.org on 2014/02/21 18:56:13 UTC
[2/2] git commit: [#7173] improve auth docs;
expose auth and more artifact model docs
[#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/3b88949d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-allura/tree/3b88949d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-allura/diff/3b88949d
Branch: refs/heads/master
Commit: 3b88949d44f92ae0629c4d8b0f570741d00653d7
Parents: 8a6bf21
Author: Dave Brondsema <da...@brondsema.net>
Authored: Thu Feb 13 11:59:55 2014 -0500
Committer: Tim Van Steenburgh <tv...@gmail.com>
Committed: Fri Feb 21 17:55:47 2014 +0000
----------------------------------------------------------------------
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/3b88949d/Allura/allura/lib/security.py
----------------------------------------------------------------------
diff --git a/Allura/allura/lib/security.py b/Allura/allura/lib/security.py
index a328197..c966e34 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
@@ -364,24 +373,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'])
'''
@@ -430,7 +440,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/3b88949d/Allura/allura/model/auth.py
----------------------------------------------------------------------
diff --git a/Allura/allura/model/auth.py b/Allura/allura/model/auth.py
index f9e3a4c..357afe8 100644
--- a/Allura/allura/model/auth.py
+++ b/Allura/allura/model/auth.py
@@ -556,7 +556,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)
@@ -772,7 +772,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/3b88949d/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/3b88949d/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/3b88949d/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
==================