From 08215c5353605d012cedac574ce4a29045b54785 Mon Sep 17 00:00:00 2001
From: Ihar Hrachyshka <ihrachys@redhat.com>
Date: Thu, 23 Apr 2015 11:55:23 +0200
Subject: [PATCH] Expose base check classes as part of public API

Those classes are used in neutron to implement custom attribute
and sub-attribute checks (get_network:attr:subattr syntax).
Those checks do not belong to oslo.policy since they would be
backwards incompatible with existing behaviour, introducing new
semantics and potentially breaking other projects, like nova.

So the alternative is to expose those symbols as part of public
API for the oslo library and allow other projects to reuse them.

More details on neutron issues consuming the library can be
found at:

http://lists.openstack.org/pipermail/openstack-dev/2015-April/061783.html

Related-Bug: #1426082
Change-Id: I6ee9f8f7fcea3ddb2c52b5d58dfce3dd328c9131
---
 doc/source/api.rst               |  5 +++++
 oslo_policy/policy.py            | 12 ++++++++++++
 oslo_policy/tests/test_policy.py | 20 ++++++++++++++++++++
 3 files changed, 37 insertions(+)

diff --git a/doc/source/api.rst b/doc/source/api.rst
index 35d9338e..33593579 100644
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@@ -8,6 +8,11 @@ oslo_policy.policy
 .. automodule:: oslo_policy.policy
    :members:
 
+.. autoclass:: oslo_policy.policy.AndCheck
+.. autoclass:: oslo_policy.policy.NotCheck
+.. autoclass:: oslo_policy.policy.OrCheck
+.. autoclass:: oslo_policy.policy.RuleCheck
+
 oslo_policy.opts
 ================
 
diff --git a/oslo_policy/policy.py b/oslo_policy/policy.py
index 27ccbf29..b6967782 100644
--- a/oslo_policy/policy.py
+++ b/oslo_policy/policy.py
@@ -129,6 +129,13 @@ Registering New Special Checks
 It is also possible for additional special check types to be registered
 using the :func:`~oslo_policy.policy.register` function.
 
+The following classes can be used as parents for custom special check types:
+
+    * :class:`~oslo_policy.policy.AndCheck`
+    * :class:`~oslo_policy.policy.NotCheck`
+    * :class:`~oslo_policy.policy.OrCheck`
+    * :class:`~oslo_policy.policy.RuleCheck`
+
 Policy Rule Expressions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -222,6 +229,11 @@ LOG = logging.getLogger(__name__)
 register = _checks.register
 Check = _checks.Check
 
+AndCheck = _checks.AndCheck
+NotCheck = _checks.NotCheck
+OrCheck = _checks.OrCheck
+RuleCheck = _checks.RuleCheck
+
 
 class PolicyNotAuthorized(Exception):
     """Default exception raised for policy enforcement failure."""
diff --git a/oslo_policy/tests/test_policy.py b/oslo_policy/tests/test_policy.py
index 85cbfc9c..741a00e1 100644
--- a/oslo_policy/tests/test_policy.py
+++ b/oslo_policy/tests/test_policy.py
@@ -491,3 +491,23 @@ class RegisterCheckTestCase(base.PolicyBaseTestCase):
         policy.register('spam', TestCheck)
 
         self.assertEqual(dict(spam=TestCheck), _checks.registered_checks)
+
+
+class BaseCheckTypesTestCase(base.PolicyBaseTestCase):
+
+    @mock.patch.object(_checks, 'registered_checks', {})
+    def test_base_check_types_are_public(self):
+        '''Check that those check types are part of public API.
+
+           They are blessed to be used by library consumers.
+        '''
+        for check_type in (policy.AndCheck, policy.NotCheck,
+                           policy.OrCheck, policy.RuleCheck):
+            class TestCheck(check_type):
+                pass
+
+            check_str = str(check_type)
+            policy.register(check_str, TestCheck)
+            self.assertEqual(
+                TestCheck, _checks.registered_checks[check_str],
+                message='%s check type is not public.' % check_str)