🔍 Code Extractor

Base class for SharePoint entities that provides common operations like create, read, update, and delete (CRUD) functionality for SharePoint objects.

Purpose

Entity serves as the base class for all SharePoint-specific objects in the Office365 Python SDK. It extends ClientObject to provide SharePoint-specific functionality including credential management, entity deletion, updates, and metadata handling. This class is designed to be inherited by concrete SharePoint entity types (like List, File, Folder, etc.) and provides the foundational methods for interacting with SharePoint REST API endpoints.

Source Code

class Entity(ClientObject):
    """SharePoint specific entity"""

    def with_credentials(self, credentials):
        """
        :type self: T
        :type credentials:  UserCredential or ClientCredential
        """
        self.context.with_credentials(credentials)
        return self

    def delete_object(self):
        """The recommended way to delete a SharePoint entity"""
        qry = DeleteEntityQuery(self)
        self.context.add_query(qry)
        self.remove_from_parent_collection()
        return self

    def update(self, *args):
        """The recommended way to update a SharePoint entity"""
        qry = UpdateEntityQuery(self)
        self.context.add_query(qry)
        return self

    @property
    def context(self):
        # type: () -> ClientContext
        return self._context

    @property
    def entity_type_name(self):
        if self._entity_type_name is None:
            self._entity_type_name = ".".join(["SP", type(self).__name__])
        return self._entity_type_name

    @property
    def property_ref_name(self):
        return "Id"

Parameters

Parameter Details

__init__: Inherits constructor from ClientObject base class. The constructor typically accepts a ClientContext instance that manages the connection to SharePoint and tracks entity state.

Return Value

Instantiation returns an Entity object representing a SharePoint entity. Methods like with_credentials(), delete_object(), and update() return self to enable method chaining. The context property returns a ClientContext instance, entity_type_name returns a string with the SharePoint type name (e.g., 'SP.List'), and property_ref_name returns the string 'Id'.

Class Interface

Methods

Attributes

Dependencies

• office365-runtime
• typing

Required Imports

from office365.runtime.client_object import ClientObject
from office365.runtime.queries.delete_entity import DeleteEntityQuery
from office365.runtime.queries.update_entity import UpdateEntityQuery
from office365.sharepoint.client_context import ClientContext

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.runtime.auth.user_credential import UserCredential
from office365.sharepoint.lists.list import List

# Create context and authenticate
ctx = ClientContext('https://tenant.sharepoint.com/sites/site')
credentials = UserCredential('user@tenant.com', 'password')

# Get a list entity
list_entity = ctx.web.lists.get_by_title('Documents')

# Set credentials and update
list_entity.with_credentials(credentials).update()
ctx.execute_query()

# Delete the entity
list_entity.delete_object()
ctx.execute_query()

# Access entity metadata
print(list_entity.entity_type_name)  # 'SP.List'
print(list_entity.property_ref_name)  # 'Id'

Best Practices

• Always call ctx.execute_query() after delete_object() or update() to commit changes to SharePoint
• Use method chaining with with_credentials() for cleaner code
• Ensure a valid ClientContext is associated before performing operations
• The Entity class is meant to be inherited, not instantiated directly
• Call update() after modifying entity properties to persist changes
• Use delete_object() instead of manually removing entities to ensure proper cleanup
• The entity_type_name property is lazily initialized and cached
• Credentials set via with_credentials() affect the entire context, not just the entity

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Utility_v1 71.7% similar

  A SharePoint utility class that extends Entity to provide access to SharePoint utility operations and services.

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

• class BaseCustomProperty 70.8% similar

  BaseCustomProperty is a SharePoint entity class representing a base custom property in the SharePoint Publishing REST API.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/publishing/customproperties/base.py

• class Authentication 68.0% similar

  A class representing authentication methods in SharePoint, inheriting from Entity to expose relationships for authentication.

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

• class EntityCollection 67.7% similar

  EntityCollection is a generic collection class for managing SharePoint entity sets, extending ClientObjectCollection with SharePoint-specific functionality.

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

• class SecurableObjectExtensions 67.4% similar

  A SharePoint entity class that provides extension methods for securable objects, enabling security-related operations on SharePoint items.

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