From d8534850d9238e85ae0ea55bf2ac8583681fdb2b Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 23 Feb 2021 13:10:16 +0000 Subject: [PATCH] trivial: Tweak docstrings There's no functional changes here other than moving the initializer documentation for the 'DeprecatedRule' from the '__init__' docstring to the class' docstring. This allows us to remove '__init__' entirely since it was just calling the superclass. Change-Id: I7437cf00b2ba5c02926dc8c2435e237ef730f2b1 Signed-off-by: Stephen Finucane --- oslo_policy/policy.py | 152 +++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 75 deletions(-) diff --git a/oslo_policy/policy.py b/oslo_policy/policy.py index 51f9c328..913a28a1 100644 --- a/oslo_policy/policy.py +++ b/oslo_policy/policy.py @@ -391,8 +391,8 @@ def parse_file_contents(data): yaml or json format. Both can be parsed as yaml. :param data: A string containing the contents of a policy file. - :returns: A dict of the form {'policy_name1': 'policy1', - 'policy_name2': 'policy2,...} + :returns: A dict of the form ``{'policy_name1': 'policy1', + 'policy_name2': 'policy2,...}`` """ try: # NOTE(snikitin): jsonutils.loads() is much faster than @@ -438,7 +438,6 @@ class Rules(dict): .. warning:: This method is deprecated as of the 1.5.0 release in favor of :meth:`load` and may be removed in the 2.0 release. - """ warnings.warn( 'The load_json() method is deprecated as of the 1.5.0 release in ' @@ -502,24 +501,24 @@ class Enforcer(object): """Responsible for loading and enforcing rules. :param conf: A configuration object. - :param policy_file: Custom policy file to use, if none is - specified, ``conf.oslo_policy.policy_file`` will be - used. - :param rules: Default dictionary / Rules to use. It will be - considered just in the first instantiation. If - :meth:`load_rules` with ``force_reload=True``, - :meth:`clear` or :meth:`set_rules` with ``overwrite=True`` - is called this will be overwritten. - :param default_rule: Default rule to use, conf.default_rule will - be used if none is specified. + :param policy_file: Custom policy file to use, if none is specified, + ``conf.oslo_policy.policy_file`` will be used. + :param rules: Default dictionary / Rules to use. It will be considered just + in the first instantiation. If :meth:`load_rules` with + ``force_reload=True``, :meth:`clear` or :meth:`set_rules` with + ``overwrite=True`` is called this will be overwritten. + :param default_rule: Default rule to use, conf.default_rule will be used if + none is specified. :param use_conf: Whether to load rules from cache or config file. :param overwrite: Whether to overwrite existing rules when reload rules - from config file. + from config file. """ - def __init__(self, conf, policy_file=None, rules=None, - default_rule=None, use_conf=True, overwrite=True, - fallback_to_json_file=True): + def __init__( + self, conf, policy_file=None, rules=None, + default_rule=None, use_conf=True, overwrite=True, + fallback_to_json_file=True, + ): self.conf = conf opts._register(conf) @@ -552,9 +551,9 @@ class Enforcer(object): def set_rules(self, rules, overwrite=True, use_conf=False): """Create a new :class:`Rules` based on the provided dict of rules. - :param dict rules: New rules to use. + :param rules: New rules to use. :param overwrite: Whether to overwrite current rules or update them - with the new rules. + with the new rules. :param use_conf: Whether to reload rules from cache or config file. """ @@ -700,7 +699,7 @@ class Enforcer(object): """Handle cases where a policy rule has been deprecated. :param default: an instance of RuleDefault that contains an instance of - DeprecatedRule + DeprecatedRule """ deprecated_rule = default.deprecated_rule @@ -729,8 +728,10 @@ class Enforcer(object): # renamed to foo:create_bar then they need to be able to see that # before they roll out the next release. If the policy name is in # self.file_rules, we know that it's being overridden. - if deprecated_rule.name != default.name and ( - deprecated_rule.name in self.file_rules): + if ( + deprecated_rule.name != default.name and + deprecated_rule.name in self.file_rules + ): if not self.suppress_deprecation_warnings: warnings.warn(deprecated_msg) @@ -742,12 +743,13 @@ class Enforcer(object): # we set the deprecated rule name to reference the new rule. If we # see that the deprecated override rule is just the new rule, then # we shouldn't mess with it. - if (self.file_rules[deprecated_rule.name].check - != _parser.parse_rule(deprecated_rule.check_str) and - str(self.file_rules[deprecated_rule.name].check) - != 'rule:%s' % default.name): - if default.name not in self.file_rules.keys(): - return self.file_rules[deprecated_rule.name].check + file_rule = self.file_rules[deprecated_rule.name] + if ( + file_rule.check != deprecated_rule.check and + str(file_rule.check) != 'rule:%s' % default.name and + default.name not in self.file_rules.keys() + ): + return self.file_rules[deprecated_rule.name].check # In this case, the default check string is changing. We need to let # operators know that this is going to change. If they don't want to @@ -761,11 +763,15 @@ class Enforcer(object): # support the new policy. # If the enforce_new_defaults flag is True, do not add OrCheck to the # old check_str and enforce only the new defaults. - if (not self.conf.oslo_policy.enforce_new_defaults - and deprecated_rule.check_str != default.check_str - and default.name not in self.file_rules): - if not (self.suppress_deprecation_warnings - or self.suppress_default_change_warnings): + if ( + not self.conf.oslo_policy.enforce_new_defaults + and deprecated_rule.check_str != default.check_str + and default.name not in self.file_rules + ): + if not ( + self.suppress_deprecation_warnings + or self.suppress_default_change_warnings + ): warnings.warn(deprecated_msg) return OrCheck([default.check, deprecated_rule.check]) @@ -773,7 +779,7 @@ class Enforcer(object): return default.check def _undefined_check(self, check): - '''Check if a RuleCheck references an undefined rule.''' + """Check if a RuleCheck references an undefined rule.""" if isinstance(check, RuleCheck): if check.match not in self.rules: # Undefined rule @@ -789,12 +795,16 @@ class Enforcer(object): return False def _cycle_check(self, check, seen=None): - '''Check if RuleChecks cycle. + """Check if RuleChecks cycle. - Looking for something like: - "foo": "rule:bar" - "bar": "rule:foo" - ''' + Looking for something like:: + + "foo": "rule:bar" + "bar": "rule:foo" + + :param check: The check to search for. + :param seen: A set of previously seen rules, else None. + """ if seen is None: seen = set() @@ -884,11 +894,10 @@ class Enforcer(object): def _load_policy_file(self, path, force_reload, overwrite=True): """Load policy rules from the specified policy file. - :param str path: A path of the policy file to load rules from. - :param bool force_reload: Forcefully reload the policy file content. - :param bool overwrite: Replace policy rules instead of updating them. + :param path: A path of the policy file to load rules from. + :param force_reload: Forcefully reload the policy file content. + :param overwrite: Replace policy rules instead of updating them. :return: A bool indicating whether rules have been changed or not. - :rtype: bool """ rules_changed = False reloaded, data = _cache_handler.read_cached_file( @@ -906,14 +915,12 @@ class Enforcer(object): """Locate the policy YAML/JSON data file/path. :param path: It's value can be a full path or related path. When - full path specified, this function just returns the full - path. When related path specified, this function will - search configuration directories to find one that exists. + full path specified, this function just returns the full path. When + related path specified, this function will search configuration + directories to find one that exists. :returns: The policy path - - :raises: ConfigFilesNotFoundError if the file/path couldn't - be located. + :raises: ConfigFilesNotFoundError if the file/path couldn't be located. """ policy_path = self.conf.find_file(path) @@ -922,35 +929,30 @@ class Enforcer(object): raise cfg.ConfigFilesNotFoundError((path,)) - def enforce(self, rule, target, creds, do_raise=False, exc=None, - *args, **kwargs): + def enforce( + self, rule, target, creds, do_raise=False, exc=None, *args, **kwargs, + ): """Checks authorization of a rule against the target and credentials. - :param rule: The rule to evaluate. - :type rule: string or :class:`BaseCheck` - :param dict target: As much information about the object being - operated on as possible. The target - argument should be a dict instance or an - instance of a class that fully supports - the Mapping abstract base class. - :param dict creds: As much information about the user performing the - action as possible. This parameter can also be an - instance of ``oslo_context.context.RequestContext``. + :param rule: The rule to evaluate as a string or :class:`BaseCheck`. + :param target: As much information about the object being operated on + as possible. The target argument should be a dict instance or an + instance of a class that fully supports the Mapping abstract base + class. + :param creds: As much information about the user performing the action + as possible. This parameter can also be an instance of + ``oslo_context.context.RequestContext``. :param do_raise: Whether to raise an exception or not if check - fails. + fails. :param exc: Class of the exception to raise if the check fails. - Any remaining arguments passed to :meth:`enforce` (both - positional and keyword arguments) will be passed to - the exception class. If not specified, - :class:`PolicyNotAuthorized` will be used. - - :return: ``False`` if the policy does not allow the action and `exc` is - not provided; otherwise, returns a value that evaluates to - ``True``. Note: for rules using the "case" expression, this - ``True`` value will be the specified string from the - expression. + Any remaining arguments passed to :meth:`enforce` (both positional + and keyword arguments) will be passed to the exception class. If + not specified, :class:`PolicyNotAuthorized` will be used. + :return: ``False`` if the policy does not allow the action and ``exc`` + is not provided; otherwise, returns a value that evaluates to + ``True``. Note: for rules using the "case" expression, this + ``True`` value will be the specified string from the expression. """ - self.load_rules() if isinstance(creds, context.RequestContext): @@ -1131,8 +1133,8 @@ class Enforcer(object): """ if rule not in self.registered_rules: raise PolicyNotRegistered(rule) - return self.enforce(rule, target, creds, do_raise, exc, - *args, **kwargs) + return self.enforce( + rule, target, creds, do_raise, exc, *args, **kwargs) class _BaseRule: