add docs on dict access

Author: jkwlui

api_core/google/api_core/iam.py

@@ -90,13 +90,23 @@ class InvalidOperationException(Exception):
 class Policy(collections_abc.MutableMapping):
     """IAM Policy
 
-    See
-    https://cloud.google.com/iam/reference/rest/v1/Policy
-
     Args:
         etag (Optional[str]): ETag used to identify a unique of the policy
         version (Optional[int]): The syntax schema version of the policy.
 
+    Note:
+        Using conditions in bindings requires the policy's version to be set
+        to `3` or greater, depending on the versions that are currently supported.
+
+        Accessing the policy using dict operations will raise InvalidOperationException
+        when the policy's version is set to 3.
+
+        Use the policy.bindings getter/setter to retrieve and modify the policy's bindings.
+
+    See:
+        IAM Policy https://cloud.google.com/iam/reference/rest/v1/Policy
+        Policy versions https://cloud.google.com/iam/docs/policies#versions
+        Conditions overview https://cloud.google.com/iam/docs/conditions-overview.
     """
 
     _OWNER_ROLES = (OWNER_ROLE,)
@@ -146,7 +156,7 @@ def __delitem__(self, key):
         raise KeyError(key)
 
     def __check_version__(self):
-        """Raise InvalidOperationException if version is greater than 1."""
+        """Raise InvalidOperationException if version is greater than 1 or policy contains conditions."""
         raise_version = self.version is not None and self.version > 1
 
         if raise_version or self._contains_conditions():
@@ -171,15 +181,6 @@ def bindings(self):
             description (:obj:str, optional): Description of the condition.
             expression: A CEL expression.
 
-        Note:
-            Using conditions in bindings requires the policy's version to be set
-            to `3` or greater, depending on the versions that are currently supported.
-
-            Accessing the policy using dict operations will raise InvalidOperationException
-            when the policy's version is set to 3.
-
-            Use the policy.bindings getter/setter to retrieve and modify the policy's bindings.
-
         See:
             Policy versions https://cloud.google.com/iam/docs/policies#versions
             Conditions overview https://cloud.google.com/iam/docs/conditions-overview.
@@ -216,6 +217,8 @@ def bindings(self, bindings):
     def owners(self):
         """Legacy access to owner role.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to access bindings instead.
         """
         result = set()
@@ -228,6 +231,8 @@ def owners(self):
     def owners(self, value):
         """Update owners.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to access bindings instead.
         """
         warnings.warn(
@@ -239,6 +244,8 @@ def owners(self, value):
     def editors(self):
         """Legacy access to editor role.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to access bindings instead.
         """
         result = set()
@@ -251,6 +258,8 @@ def editors(self):
     def editors(self, value):
         """Update editors.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to modify bindings instead.
         """
         warnings.warn(
@@ -263,6 +272,8 @@ def editors(self, value):
     def viewers(self):
         """Legacy access to viewer role.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to modify bindings instead.
         """
         result = set()
@@ -275,6 +286,8 @@ def viewers(self):
     def viewers(self, value):
         """Update viewers.
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         DEPRECATED:  use `policy.bindings` to modify bindings instead.
         """
         warnings.warn(

bigtable/google/cloud/bigtable/policy.py

@@ -74,6 +74,20 @@ class Policy(BasePolicy):
                  existing policy is overwritten blindly.
     :type version: int
     :param version: The syntax schema version of the policy.
+
+    Note:
+        Using conditions in bindings requires the policy's version to be set
+        to `3` or greater, depending on the versions that are currently supported.
+
+        Accessing the policy using dict operations will raise InvalidOperationException
+        when the policy's version is set to 3.
+
+        Use the policy.bindings getter/setter to retrieve and modify the policy's bindings.
+
+    See:
+        IAM Policy https://cloud.google.com/iam/reference/rest/v1/Policy
+        Policy versions https://cloud.google.com/iam/docs/policies#versions
+        Conditions overview https://cloud.google.com/iam/docs/conditions-overview.
     """
 
     def __init__(self, etag=None, version=None):
@@ -85,6 +99,8 @@ def __init__(self, etag=None, version=None):
     def bigtable_admins(self):
         """Access to bigtable.admin role memebers
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         For example:
 
         .. literalinclude:: snippets.py
@@ -100,6 +116,8 @@ def bigtable_admins(self):
     def bigtable_readers(self):
         """Access to bigtable.reader role memebers
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         For example:
 
         .. literalinclude:: snippets.py
@@ -115,6 +133,8 @@ def bigtable_readers(self):
     def bigtable_users(self):
         """Access to bigtable.user role memebers
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         For example:
 
         .. literalinclude:: snippets.py
@@ -130,6 +150,8 @@ def bigtable_users(self):
     def bigtable_viewers(self):
         """Access to bigtable.viewer role memebers
 
+        Raise InvalidOperationException if version is greater than 1 or policy contains conditions.
+
         For example:
 
         .. literalinclude:: snippets.py