Thanks to visit codestin.com
Credit goes to github.com

Skip to content

API Core: add usage example for 'google.api_core.iam.Polcy'. #6855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 10, 2018
Merged

API Core: add usage example for 'google.api_core.iam.Polcy'. #6855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 67 additions & 39 deletions api_core/google/api_core/iam.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,22 @@

For allowed roles / permissions, see:
https://cloud.google.com/iam/docs/understanding-roles

Example usage:

.. code-block:: python

# ``get_iam_policy`` returns a :class:'~google.api_core.iam.Policy`.
policy = resource.get_iam_policy()

phred = policy.user("[email protected]")
admin_group = policy.group("[email protected]")
account = policy.service_account("[email protected]")
policy["roles/owner"] = [phred, admin_group, account]
policy["roles/editor"] = policy.authenticated_users()
policy["roles/viewer"] = policy.all_users()

resource.set_iam_policy(policy)
"""

import collections
Expand Down Expand Up @@ -45,11 +61,9 @@ class Policy(collections_abc.MutableMapping):
See
https://cloud.google.com/iam/reference/rest/v1/Policy

:type etag: str
:param etag: ETag used to identify a unique of the policy

:type version: int
:param version: unique version of the policy
Args:
etag (Optional[str]): ETag used to identify a unique of the policy
version (Optional[int]): unique version of the policy
"""

_OWNER_ROLES = (OWNER_ROLE,)
Expand Down Expand Up @@ -83,7 +97,9 @@ def __delitem__(self, key):

@property
def owners(self):
"""Legacy access to owner role."""
"""Legacy access to owner role.

DEPRECATED: use ``policy["roles/owners"]`` instead."""
result = set()
for role in self._OWNER_ROLES:
for member in self._bindings.get(role, ()):
Expand All @@ -92,15 +108,19 @@ def owners(self):

@owners.setter
def owners(self, value):
"""Update owners."""
"""Update owners.

DEPRECATED: use ``policy["roles/owners"] = value`` instead."""
warnings.warn(
_ASSIGNMENT_DEPRECATED_MSG.format("owners", OWNER_ROLE), DeprecationWarning
)
self[OWNER_ROLE] = value

@property
def editors(self):
"""Legacy access to editor role."""
"""Legacy access to editor role.

DEPRECATED: use ``policy["roles/editors"]`` instead."""
result = set()
for role in self._EDITOR_ROLES:
for member in self._bindings.get(role, ()):
Expand All @@ -109,7 +129,9 @@ def editors(self):

@editors.setter
def editors(self, value):
"""Update editors."""
"""Update editors.

DEPRECATED: use ``policy["roles/editors"] = value`` instead."""
warnings.warn(
_ASSIGNMENT_DEPRECATED_MSG.format("editors", EDITOR_ROLE),
DeprecationWarning,
Expand All @@ -118,7 +140,10 @@ def editors(self, value):

@property
def viewers(self):
"""Legacy access to viewer role."""
"""Legacy access to viewer role.

DEPRECATED: use ``policy["roles/viewers"]`` instead
"""
result = set()
for role in self._VIEWER_ROLES:
for member in self._bindings.get(role, ()):
Expand All @@ -127,7 +152,10 @@ def viewers(self):

@viewers.setter
def viewers(self, value):
"""Update viewers."""
"""Update viewers.

DEPRECATED: use ``policy["roles/viewers"] = value`` instead.
"""
warnings.warn(
_ASSIGNMENT_DEPRECATED_MSG.format("viewers", VIEWER_ROLE),
DeprecationWarning,
Expand All @@ -138,77 +166,77 @@ def viewers(self, value):
def user(email):
"""Factory method for a user member.

:type email: str
:param email: E-mail for this particular user.
Args:
email (str): E-mail for this particular user.

:rtype: str
:returns: A member string corresponding to the given user.
Returns:
str: A member string corresponding to the given user.
"""
return "user:%s" % (email,)

@staticmethod
def service_account(email):
"""Factory method for a service account member.

:type email: str
:param email: E-mail for this particular service account.
Args:
email (str): E-mail for this particular service account.

:rtype: str
:returns: A member string corresponding to the given service account.
Returns:
str: A member string corresponding to the given service account.
"""
return "serviceAccount:%s" % (email,)

@staticmethod
def group(email):
"""Factory method for a group member.

:type email: str
:param email: An id or e-mail for this particular group.
Args:
email (str): An id or e-mail for this particular group.

:rtype: str
:returns: A member string corresponding to the given group.
Returns:
str: A member string corresponding to the given group.
"""
return "group:%s" % (email,)

@staticmethod
def domain(domain):
"""Factory method for a domain member.

:type domain: str
:param domain: The domain for this member.
Args:
domain (str): The domain for this member.

:rtype: str
:returns: A member string corresponding to the given domain.
Returns:
str: A member string corresponding to the given domain.
"""
return "domain:%s" % (domain,)

@staticmethod
def all_users():
"""Factory method for a member representing all users.

:rtype: str
:returns: A member string representing all users.
Returns:
str: A member string representing all users.
"""
return "allUsers"

@staticmethod
def authenticated_users():
"""Factory method for a member representing all authenticated users.

:rtype: str
:returns: A member string representing all authenticated users.
Returns:
str: A member string representing all authenticated users.
"""
return "allAuthenticatedUsers"

@classmethod
def from_api_repr(cls, resource):
"""Create a policy from the resource returned from the API.
"""Factory: create a policy from a JSON resource.

:type resource: dict
:param resource: resource returned from the ``getIamPolicy`` API.
Args:
resource (dict): policy resource returned by ``getIamPolicy`` API.

:rtype: :class:`Policy`
:returns: the parsed policy
Returns:
:class:`Policy`: the parsed policy
"""
version = resource.get("version")
etag = resource.get("etag")
Expand All @@ -220,10 +248,10 @@ def from_api_repr(cls, resource):
return policy

def to_api_repr(self):
"""Construct a Policy resource.
"""Render a JSON policy resource.

:rtype: dict
:returns: a resource to be passed to the ``setIamPolicy`` API.
Returns:
dict: a resource to be passed to the ``setIamPolicy`` API.
"""
resource = {}

Expand Down
1 change: 1 addition & 0 deletions docs/core/iam.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ Identity and Access Management
.. automodule:: google.api_core.iam
:members:
:show-inheritance:
:member-order: bysource