Add docstrings for requirements_authority module
This patchset adds docstrings for the requirements_authority
module. Also corrects some docstring syntax issues (and deprecated
docstring references) in rbac_rule_validation.
Change-Id: I071cbf53e2c0e819e56e485d2434a30de6793077
diff --git a/patrole_tempest_plugin/policy_authority.py b/patrole_tempest_plugin/policy_authority.py
index 99348b9..a22e00a 100644
--- a/patrole_tempest_plugin/policy_authority.py
+++ b/patrole_tempest_plugin/policy_authority.py
@@ -156,9 +156,9 @@
def allowed(self, rule_name, role):
"""Checks if a given rule in a policy is allowed with given role.
- :param string rule_name: Rule to be checked using ``oslo.policy``.
- :param bool is_admin: Whether admin context is used.
- :raises RbacParsingException: If `rule_name`` does not exist in the
+ :param string rule_name: Policy name to pass to``oslo.policy``.
+ :param string role: Role to validate for authorization.
+ :raises RbacParsingException: If ``rule_name`` does not exist in the
cloud (in policy file or among registered in-code policy defaults).
"""
is_admin_context = self._is_admin_context(role)
diff --git a/patrole_tempest_plugin/requirements_authority.py b/patrole_tempest_plugin/requirements_authority.py
index 2db12db..6dd75eb 100644
--- a/patrole_tempest_plugin/requirements_authority.py
+++ b/patrole_tempest_plugin/requirements_authority.py
@@ -16,14 +16,17 @@
from oslo_log import log as logging
+from tempest import config
from tempest.lib import exceptions
from patrole_tempest_plugin.rbac_utils import RbacAuthority
+CONF = config.CONF
LOG = logging.getLogger(__name__)
class RequirementsParser(object):
+ """A class that parses a custom requirements file."""
_inner = None
class Inner(object):
@@ -40,6 +43,27 @@
@staticmethod
def parse(component):
+ """Parses a requirements file with the following format:
+
+ .. code-block:: yaml
+
+ <service_foo>:
+ <api_action_a>:
+ - <allowed_role_1>
+ - <allowed_role_2>
+ - <allowed_role_3>
+ <api_action_b>:
+ - <allowed_role_2>
+ - <allowed_role_4>
+ <service_bar>:
+ <api_action_c>:
+ - <allowed_role_3>
+
+ :param str component: Name of the OpenStack service to be validated.
+ :returns: The dictionary that maps each policy action to the list
+ of allowed roles, for the given ``component``.
+ :rtype: dict
+ """
try:
for section in RequirementsParser.Inner._rbac_map:
if component in section:
@@ -51,13 +75,39 @@
class RequirementsAuthority(RbacAuthority):
+ """A class that uses a custom requirements file to validate RBAC."""
+
def __init__(self, filepath=None, component=None):
- if filepath is not None and component is not None:
+ """This class can be used to achieve a requirements-driven approach to
+ validating an OpenStack cloud's RBAC implementation. Using this
+ approach, Patrole computes expected test results by performing lookups
+ against a custom requirements file which precisely defines the cloud's
+ RBAC requirements.
+
+ :param str filepath: Path where the custom requirements file lives.
+ Defaults to ``[patrole].custom_requirements_file``.
+ :param str component: Name of the OpenStack service to be validated.
+ """
+ filepath = filepath or CONF.patrole.custom_requirements_file
+
+ if component is not None:
self.roles_dict = RequirementsParser(filepath).parse(component)
else:
self.roles_dict = None
def allowed(self, rule_name, role):
+ """Checks if a given rule in a policy is allowed with given role.
+
+ :param string rule_name: Rule to be checked using provided requirements
+ file specified by ``[patrole].custom_requirements_file``. Must be
+ a key present in this file, under the appropriate component.
+ :param string role: Role to validate against custom requirements file.
+ :returns: True if ``role`` is allowed to perform ``rule_name``, else
+ False.
+ :rtype: bool
+ :raises KeyError: If ``rule_name`` does not exist among the keyed
+ policy names in the custom requirements file.
+ """
if self.roles_dict is None:
raise exceptions.InvalidConfiguration(
"Roles dictionary parsed from requirements YAML file is "