🔍 Code Extractor

Represents a SharePoint site collection's properties and provides methods to query and update site-level settings such as sharing capabilities, lock state, and customization permissions.

Purpose

SiteProperties is a data entity class that encapsulates information about a SharePoint site collection. It provides access to site metadata (URL, owner, time zone, compatibility level) and administrative settings (sharing capabilities, lock state, customization permissions). The class supports both reading properties and updating site configurations through the SharePoint REST API. It inherits from Entity and integrates with the Office365 client context for executing queries against SharePoint Online tenant administration APIs.

Source Code

class SiteProperties(Entity):
    """Contains a property bag of information about a site."""

    def __repr__(self):
        return self.url or self.entity_type_name

    @staticmethod
    def clear_sharing_lock_down(context, site_url):
        # type: (ClientContext, str) -> SiteProperties
        payload = {"siteUrl": site_url}
        binding_type = SiteProperties(context)
        qry = ServiceOperationQuery(
            binding_type, "ClearSharingLockDown", None, payload, None, None, True
        )
        context.add_query(qry)
        return binding_type

    def update(self):
        """Updates the site collection properties with the new properties specified in the SiteProperties object."""

        def _update():
            super(SiteProperties, self).update()

        self._ensure_site_path(_update)
        return self

    def update_ex(self):
        """Updates the site collection properties with the new properties specified in the SiteProperties object."""
        return_type = SpoOperation(self.context)

        def _update_ex():
            qry = ServiceOperationQuery(
                self, "Update", parameters_type=self, return_type=return_type
            )
            self.context.add_query(qry)

        self._ensure_site_path(_update_ex)
        return return_type

    @property
    def deny_add_and_customize_pages(self):
        # type: () -> Optional[int]
        """Represents the status of the [DenyAddAndCustomizePages] feature on a site collection."""
        return self.properties.get(
            "DenyAddAndCustomizePages", DenyAddAndCustomizePagesStatus.Unknown
        )

    @deny_add_and_customize_pages.setter
    def deny_add_and_customize_pages(self, value):
        # type: (int) -> None
        """Sets the status of the [DenyAddAndCustomizePages] feature on a site collection."""
        self.set_property("DenyAddAndCustomizePages", value)

    @property
    def owner_login_name(self):
        # type: () -> Optional[str]
        return self.properties.get("OwnerLoginName", None)

    @property
    def webs_count(self):
        # type: () -> Optional[str]
        """Gets the number of Web objects in the site."""
        return self.properties.get("WebsCount", None)

    @property
    def url(self):
        # type: () -> Optional[str]
        """Gets the URL of the site."""
        return self.properties.get("Url", None)

    @property
    def compatibility_level(self):
        # type: () -> Optional[str]
        """Gets the compatibility level of the site."""
        return self.properties.get("CompatibilityLevel", None)

    @property
    def lock_state(self):
        # type: () -> Optional[str]
        """Gets or sets the lock state of the site."""
        return self.properties.get("LockState", None)

    @property
    def sharing_capability(self):
        # type: () -> Optional[int]
        """
        Determines what level of sharing is available for the site.

        The valid values are:
            - ExternalUserAndGuestSharing (default) - External user sharing (share by email) and guest link sharing
                 are both enabled.
            - Disabled - External user sharing (share by email) and guest link sharing are both disabled.
            - ExternalUserSharingOnly - External user sharing (share by email) is enabled, but guest link sharing
                 is disabled.
            - ExistingExternalUserSharingOnly - Only guests already in your organization's directory.
        :rtype: int
        """
        return self.properties.get("SharingCapability", None)

    @sharing_capability.setter
    def sharing_capability(self, value):
        # type: (int) -> None
        """Sets the level of sharing for the site."""
        self.set_property("SharingCapability", value)

    @property
    def time_zone_id(self):
        # type: () -> Optional[str]
        """Gets the time zone ID of the site."""
        return self.properties.get("TimeZoneId", None)

    @property
    def entity_type_name(self):
        # type: () -> str
        return "Microsoft.Online.SharePoint.TenantAdministration.SiteProperties"

    def set_property(self, name, value, persist_changes=True):
        super(SiteProperties, self).set_property(name, value, persist_changes)
        # fallback: create a new resource path
        if name == "Url" and self._resource_path is None:
            self._resource_path = StaticOperationPath(
                self.entity_type_name, {"Url": value}
            )
        return self

    def _ensure_site_path(self, action):
        if isinstance(self.resource_path, ServiceOperationPath):

            def _loaded(return_type):
                # type: (ListItem) -> None
                site_id = return_type.get_property("SiteId")
                self._resource_path = EntityPath(
                    site_id, self.parent_collection.resource_path
                )
                action()

            self.context.tenant.get_site(self.url).after_execute(_loaded)
        else:
            action()

Parameters

Name	Type	Default	Kind
bases	Entity	-

Parameter Details

context: ClientContext instance that provides the connection to SharePoint and manages query execution. Required for all operations that interact with SharePoint services.

bases: Inherits from Entity class which provides base functionality for SharePoint entities including property management, query execution, and resource path handling.

Return Value

Instantiation returns a SiteProperties object that represents a SharePoint site collection. Methods typically return 'self' for method chaining (update), SiteProperties instances (clear_sharing_lock_down), or SpoOperation objects (update_ex) for tracking long-running operations. Properties return Optional types with specific data (strings for URL/owner, integers for sharing capabilities, etc.) or None if not loaded.

Class Interface

Methods

Attributes

Name	Type	Description	Scope
properties	dict	Dictionary containing all loaded property values from SharePoint (inherited from Entity base class)	instance
context	ClientContext	The ClientContext instance used for executing queries against SharePoint (inherited from Entity base class)	instance
_resource_path	ResourcePath	Internal resource path used for constructing REST API URLs (inherited from Entity base class)	instance
parent_collection	EntityCollection	Reference to the parent collection if this entity is part of a collection (inherited from Entity base class)	instance

Dependencies

• office365
• typing

Required Imports

from office365.sharepoint.tenant.administration.site_properties import SiteProperties
from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.tenant.administration.deny_add_and_customize_pages_status import DenyAddAndCustomizePagesStatus

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.tenant.administration.site_properties import SiteProperties
from office365.sharepoint.tenant.administration.deny_add_and_customize_pages_status import DenyAddAndCustomizePagesStatus

# Initialize context with tenant admin credentials
admin_url = 'https://contoso-admin.sharepoint.com'
ctx = ClientContext(admin_url).with_credentials(user_credentials)

# Get site properties
tenant = ctx.tenant
site_props = tenant.get_site_properties_by_url('https://contoso.sharepoint.com/sites/teamsite')
ctx.load(site_props)
ctx.execute_query()

print(f'Site URL: {site_props.url}')
print(f'Owner: {site_props.owner_login_name}')
print(f'Webs Count: {site_props.webs_count}')

# Update site properties
site_props.sharing_capability = 1  # Disabled
site_props.deny_add_and_customize_pages = DenyAddAndCustomizePagesStatus.Enabled
site_props.update()
ctx.execute_query()

# Clear sharing lock down (static method)
SiteProperties.clear_sharing_lock_down(ctx, 'https://contoso.sharepoint.com/sites/teamsite')
ctx.execute_query()

Best Practices

• Always load the SiteProperties object using ctx.load() and ctx.execute_query() before accessing properties to ensure data is retrieved from SharePoint
• Use update() for simple property updates and update_ex() when you need to track the operation status through SpoOperation
• Ensure the ClientContext has tenant administrator permissions before attempting to modify site properties
• When setting sharing_capability, use valid integer values: 0 (ExternalUserAndGuestSharing), 1 (Disabled), 2 (ExternalUserSharingOnly), 3 (ExistingExternalUserSharingOnly)
• The _ensure_site_path method handles resource path resolution internally; don't call it directly
• Properties are lazily loaded; check for None values before using them
• Use clear_sharing_lock_down as a static method with proper context and site URL parameters
• Method chaining is supported for update operations (e.g., site_props.set_property().update())
• The entity_type_name property returns the SharePoint REST API type identifier and should not be modified

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class SitePropertiesCollection 86.6% similar

  A collection class for managing SiteProperties resources in SharePoint, providing methods to query and retrieve site information by site ID.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/tenant/administration/sites/properties_collection.py

• class SiteCreationProperties 81.9% similar

  A data class that encapsulates the properties required to create a new SharePoint site, including URL, owner, title, and template information.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/tenant/administration/sites/creation_properties.py

• class SiteStateProperties 81.2% similar

  A data class representing SharePoint site state properties for tenant administration operations.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/tenant/administration/sites/state_properties.py

• class HubSiteProperties 79.1% similar

  Represents the properties of a SharePoint Hub Site in the tenant administration context, providing access to hub site metadata such as permissions and site identifier.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/tenant/administration/hubsites/properties.py

• class ThemeProperties 73.4% similar

  ThemeProperties is a SharePoint entity class that represents theme properties for SharePoint Online tenant management.

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

class SiteProperties(Entity):
    """Contains a property bag of information about a site."""

    def __repr__(self):
        return self.url or self.entity_type_name

    @staticmethod
    def clear_sharing_lock_down(context, site_url):
        # type: (ClientContext, str) -> SiteProperties
        payload = {"siteUrl": site_url}
        binding_type = SiteProperties(context)
        qry = ServiceOperationQuery(
            binding_type, "ClearSharingLockDown", None, payload, None, None, True
        )
        context.add_query(qry)
        return binding_type

    def update(self):
        """Updates the site collection properties with the new properties specified in the SiteProperties object."""

        def _update():
            super(SiteProperties, self).update()

        self._ensure_site_path(_update)
        return self

    def update_ex(self):
        """Updates the site collection properties with the new properties specified in the SiteProperties object."""
        return_type = SpoOperation(self.context)

        def _update_ex():
            qry = ServiceOperationQuery(
                self, "Update", parameters_type=self, return_type=return_type
            )
            self.context.add_query(qry)

        self._ensure_site_path(_update_ex)
        return return_type

    @property
    def deny_add_and_customize_pages(self):
        # type: () -> Optional[int]
        """Represents the status of the [DenyAddAndCustomizePages] feature on a site collection."""
        return self.properties.get(
            "DenyAddAndCustomizePages", DenyAddAndCustomizePagesStatus.Unknown
        )

    @deny_add_and_customize_pages.setter
    def deny_add_and_customize_pages(self, value):
        # type: (int) -> None
        """Sets the status of the [DenyAddAndCustomizePages] feature on a site collection."""
        self.set_property("DenyAddAndCustomizePages", value)

    @property
    def owner_login_name(self):
        # type: () -> Optional[str]
        return self.properties.get("OwnerLoginName", None)

    @property
    def webs_count(self):
        # type: () -> Optional[str]
        """Gets the number of Web objects in the site."""
        return self.properties.get("WebsCount", None)

    @property
    def url(self):
        # type: () -> Optional[str]
        """Gets the URL of the site."""
        return self.properties.get("Url", None)

    @property
    def compatibility_level(self):
        # type: () -> Optional[str]
        """Gets the compatibility level of the site."""
        return self.properties.get("CompatibilityLevel", None)

    @property
    def lock_state(self):
        # type: () -> Optional[str]
        """Gets or sets the lock state of the site."""
        return self.properties.get("LockState", None)

    @property
    def sharing_capability(self):
        # type: () -> Optional[int]
        """
        Determines what level of sharing is available for the site.

        The valid values are:
            - ExternalUserAndGuestSharing (default) - External user sharing (share by email) and guest link sharing
                 are both enabled.
            - Disabled - External user sharing (share by email) and guest link sharing are both disabled.
            - ExternalUserSharingOnly - External user sharing (share by email) is enabled, but guest link sharing
                 is disabled.
            - ExistingExternalUserSharingOnly - Only guests already in your organization's directory.
        :rtype: int
        """
        return self.properties.get("SharingCapability", None)

    @sharing_capability.setter
    def sharing_capability(self, value):
        # type: (int) -> None
        """Sets the level of sharing for the site."""
        self.set_property("SharingCapability", value)

    @property
    def time_zone_id(self):
        # type: () -> Optional[str]
        """Gets the time zone ID of the site."""
        return self.properties.get("TimeZoneId", None)

    @property
    def entity_type_name(self):
        # type: () -> str
        return "Microsoft.Online.SharePoint.TenantAdministration.SiteProperties"

    def set_property(self, name, value, persist_changes=True):
        super(SiteProperties, self).set_property(name, value, persist_changes)
        # fallback: create a new resource path
        if name == "Url" and self._resource_path is None:
            self._resource_path = StaticOperationPath(
                self.entity_type_name, {"Url": value}
            )
        return self

    def _ensure_site_path(self, action):
        if isinstance(self.resource_path, ServiceOperationPath):

            def _loaded(return_type):
                # type: (ListItem) -> None
                site_id = return_type.get_property("SiteId")
                self._resource_path = EntityPath(
                    site_id, self.parent_collection.resource_path
                )
                action()

            self.context.tenant.get_site(self.url).after_execute(_loaded)
        else:
            action()