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

@@ -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
 ================
 

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."""

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)