🔍 Code Extractor

Represents an association between a principal (user or group) and a role definition in SharePoint, managing permissions and role assignments.

Purpose

This class models a SharePoint role assignment entity that links users or groups (principals) to specific role definitions. It provides access to the principal's identifier, the member object, and the collection of role definitions associated with this assignment. The class extends Entity and integrates with SharePoint's permission system to manage access control and role-based security.

Source Code

class RoleAssignment(Entity):
    """An association between a principal or a site group and a role definition."""

    @property
    def principal_id(self):
        """Specifies the identifier of the user or group corresponding to the role assignment."""
        return self.properties.get("PrincipalId", None)

    @property
    def member(self):
        """Specifies the user or group corresponding to the role assignment."""
        return self.properties.get(
            "Member",
            Principal(self.context, ResourcePath("Member", self.resource_path)),
        )

    @property
    def role_definition_bindings(self):
        """Specifies a collection of role definitions for this role assignment."""
        return self.properties.get(
            "RoleDefinitionBindings",
            RoleDefinitionCollection(
                self.context, ResourcePath("RoleDefinitionBindings", self.resource_path)
            ),
        )

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "RoleDefinitionBindings": self.role_definition_bindings,
            }
            default_value = property_mapping.get(name, None)
        return super(RoleAssignment, self).get_property(name, default_value)

    def set_property(self, name, value, persist_changes=True):
        super(RoleAssignment, self).set_property(name, value, persist_changes)
        if self._resource_path is None:
            if name == "PrincipalId":
                self._resource_path = self.parent_collection.get_by_principal_id(
                    value
                ).resource_path
        return self

Parameters

Parameter Details

context: The client context object used for SharePoint operations and API communication

resource_path: The ResourcePath object representing the location of this role assignment in the SharePoint resource hierarchy

properties: Optional dictionary containing initial property values for the role assignment entity

Return Value

Instantiation returns a RoleAssignment object that represents a SharePoint role assignment. The set_property method returns self for method chaining. Properties return their respective types: principal_id returns an integer or None, member returns a Principal object, and role_definition_bindings returns a RoleDefinitionCollection object.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.runtime.paths.resource_path import ResourcePath
from office365.sharepoint.entity import Entity
from office365.sharepoint.permissions.roles.definitions.collection import RoleDefinitionCollection
from office365.sharepoint.principal.principal import Principal

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.permissions.roleAssignment import RoleAssignment

# Authenticate and get context
ctx = ClientContext(site_url).with_credentials(credentials)

# Get role assignments for a web or list
web = ctx.web
role_assignments = web.role_assignments
ctx.load(role_assignments)
ctx.execute_query()

# Access a specific role assignment
for assignment in role_assignments:
    principal_id = assignment.principal_id
    member = assignment.member
    ctx.load(member)
    ctx.execute_query()
    print(f"Principal ID: {principal_id}, Member: {member.properties}")
    
    # Get role definitions
    role_defs = assignment.role_definition_bindings
    ctx.load(role_defs)
    ctx.execute_query()
    for role_def in role_defs:
        print(f"Role: {role_def.name}")

# Set property with method chaining
assignment.set_property('PrincipalId', 123, persist_changes=False)

Best Practices

• Always load the context after accessing properties that return complex objects (member, role_definition_bindings) before accessing their properties
• Use the context's execute_query() method to fetch data from SharePoint after loading entities
• When setting PrincipalId property, the resource_path is automatically resolved from the parent collection if not already set
• The set_property method supports method chaining by returning self, allowing fluent API usage
• Properties use lazy loading - they return default objects if not yet loaded from SharePoint
• Ensure proper authentication and permissions are configured in the context before accessing role assignments
• The persist_changes parameter in set_property controls whether changes are immediately persisted to SharePoint

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class UserRoleAssignment 76.6% similar

  A data class representing the assignment of a role to a user in SharePoint, inheriting from ClientValue for serialization support.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/sharing/user_role_assignment.py

• class UnifiedRoleAssignment 73.8% similar

  Represents a role assignment in Microsoft Graph API that grants access to resources by associating a role definition with a principal (user or group) at a specific scope.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/unified_role_assignment.py

• class AppRoleAssignment 72.6% similar

  Represents an app role assignment in Microsoft Graph API, recording when a user, group, or service principal is assigned an app role for an application.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/roles/assignment.py

• class AppRoleAssignmentCollection 68.7% similar

  A collection class that manages and provides access to AppRoleAssignment entities, inheriting from EntityCollection to handle groups of application role assignments.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/roles/assignment_collection.py

• class RoleDefinitionCreationInformation 67.6% similar

  A data class that encapsulates properties used to initialize a SharePoint role definition, including name, description, permissions, and display order.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/permissions/roles/definitions/creation_information.py