Skip to content
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

docs(iam): Update comments and terminology in IAM samples #13010

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+20 −33
Open

docs(iam): Update comments and terminology in IAM samples #13010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
36066a8
Update modify_policy_add_member.py comments
melaniedejong Dec 20, 2024
9a0e403
Update modify_policy_remove_member.py
melaniedejong Dec 20, 2024
0489a1a
Update quickstart.py comments
melaniedejong Dec 20, 2024
af9c528
Update iam_modify_policy_add_role.py
melaniedejong Dec 20, 2024
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
4 changes: 2 additions & 2 deletions iam/cloud-client/snippets/iam_modify_policy_add_role.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@


# [START iam_modify_policy_add_role]
def modify_policy_add_role(policy: dict, role: str, member: str) -> dict:
def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per the Google Python Style Guide, there should be two blank lines between top-level functions. Consider adding an extra blank line here.

Suggested change
def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:
def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:

"""Adds a new role binding to a policy."""

binding = {"role": role, "members": [member]}
binding = {"role": role, "members": [principal]}
policy["bindings"].append(binding)
print(policy)
return policy
Expand Down
17 changes: 5 additions & 12 deletions iam/cloud-client/snippets/modify_policy_add_member.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,13 @@ def modify_policy_add_member(
project_id: str, role: str, member: str
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider renaming the member parameter to principal for consistency with the updated terminology.

Suggested change
project_id: str, role: str, member: str
project_id: str, role: str, principal: str

) -> policy_pb2.Policy:
"""
Add a member to certain role in project policy.
Add a principal to certain role in project policy.

project_id: ID or number of the Google Cloud project you want to use.
role: role to which member need to be added.
member: The principals requesting access.

Possible format for member:
* user:{emailid}
* serviceAccount:{emailid}
* group:{emailid}
* deleted:user:{emailid}?uid={uniqueid}
* deleted:serviceAccount:{emailid}?uid={uniqueid}
* deleted:group:{emailid}?uid={uniqueid}
* domain:{domain}
role: role to which principal need to be added.
member: The principal requesting access.

For principal ID formats, see https://cloud.google.com/iam/docs/principal-identifiers
"""
policy = get_project_policy(project_id)

Expand Down
17 changes: 5 additions & 12 deletions iam/cloud-client/snippets/modify_policy_remove_member.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,13 @@ def modify_policy_remove_member(
project_id: str, role: str, member: str
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider renaming the member parameter to principal for consistency with the updated terminology.

Suggested change
project_id: str, role: str, member: str
project_id: str, role: str, principal: str

) -> policy_pb2.Policy:
"""
Remove a member from certain role in project policy.
Remove a principal from certain role in project policy.

project_id: ID or number of the Google Cloud project you want to use.
role: role to which member need to be added.
member: The principals requesting access.

Possible format for member:
* user:{emailid}
* serviceAccount:{emailid}
* group:{emailid}
* deleted:user:{emailid}?uid={uniqueid}
* deleted:serviceAccount:{emailid}?uid={uniqueid}
* deleted:group:{emailid}?uid={uniqueid}
* domain:{domain}
role: role to revoke.
member: The principal to revoke access from.

For principal ID formats, see https://cloud.google.com/iam/docs/principal-identifiers
"""
policy = get_project_policy(project_id)

Expand Down
15 changes: 8 additions & 7 deletions iam/cloud-client/snippets/quickstart.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,28 +19,28 @@


def quickstart(project_id: str, member: str) -> None:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a more descriptive docstring, summarizing the steps involved in the quickstart and the purpose of each parameter. For example:

"""Demonstrates basic IAM operations.

This quickstart shows how to get a project's IAM policy, add a principal to a role, list members of a role, and remove a principal from a role.

Args:
    project_id: The ID or number of the Google Cloud project.
    member: The principal ID.
"""
Suggested change
def quickstart(project_id: str, member: str) -> None:
def quickstart(project_id: str, member: str) -> None:
"""Demonstrates basic IAM operations.
This quickstart shows how to get a project's IAM policy, add a principal to a role, list members of a role, and remove a principal from a role.
Args:
project_id: The ID or number of the Google Cloud project.
member: The principal ID.
"""

"""Gets a policy, adds a member, prints their permissions, and removes the member.
"""Gets a policy, adds a principal, prints their permissions, and removes the principal.

project_id: ID or number of the Google Cloud project you want to use.
member: The principals requesting the access.
member: The principal requesting the access.
"""

# Role to be granted.
role = "roles/logging.logWriter"
crm_service = resourcemanager_v3.ProjectsClient()

# Grants your member the 'Log Writer' role for the project.
# Grants your principal the 'Log Writer' role for the project.
modify_policy_add_role(crm_service, project_id, role, member)

# Gets the project's policy and prints all members with the 'Log Writer' role.
# Gets the project's policy and prints all principals with the 'Log Writer' role.
policy = get_policy(crm_service, project_id)
binding = next(b for b in policy.bindings if b.role == role)
print(f"Role: {(binding.role)}")
print("Members: ")
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the Google Python Style Guide, prefer using f-strings for formatting. Change print("Members: ") to print(f"Members: ").

for m in binding.members:
print(f"[{m}]")

# Removes the member from the 'Log Writer' role.
# Removes the principal from the 'Log Writer' role.
modify_policy_remove_member(crm_service, project_id, role, member)


Expand Down Expand Up @@ -115,7 +115,8 @@ def modify_policy_remove_member(
if __name__ == "__main__":
# TODO: replace with your project ID
project_id = "your-project-id"
# TODO: Replace with the ID of your member in the form 'user:[email protected]'.
member = "your-member"
# TODO: Replace with the ID of your principal.
# For examples, see https://cloud.google.com/iam/docs/principal-identifiers
Comment on lines +118 to +119
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update the placeholder comment to reflect the change from "member" to "principal". Per Google Python Style Guide, use a complete sentence in your comment.

Suggested change
# TODO: Replace with the ID of your principal.
# For examples, see https://cloud.google.com/iam/docs/principal-identifiers
# TODO: Replace with the ID of your principal.

member = "your-principal"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update the variable name to principal for consistency.

quickstart(project_id, member)
# [END iam_quickstart]
Loading