🔍 Code Extractor

A class representing a SharePoint DocumentSet, which is a specialized folder type that inherits from Folder and provides methods to create and retrieve document sets on a SharePoint server.

Purpose

DocumentSet extends the Folder class to provide specialized functionality for working with SharePoint DocumentSets. DocumentSets are containers that allow grouping related documents together with shared metadata and workflows. This class provides static factory methods to create new DocumentSets on the server and retrieve existing ones from folder objects. It handles the complex server-side operations including content type assignment, list data service communication, and proper URL construction for DocumentSet operations.

Source Code

class DocumentSet(Folder):
    @staticmethod
    def create(context, parent_folder, name, ct_id="0x0120D520"):
        """
        Creates a DocumentSet (section 3.1.5.3) object on the server.

        :type context: office365.sharepoint.client_context.ClientContext
        :param office365.sharepoint.folders.folder.Folder parent_folder: The folder inside which to create the new
            DocumentSet.
        :param str name: The name to give to the new DocumentSet
        :param office365.sharepoint.contenttypes.content_type_id.ContentTypeId ct_id: The identifier of the content
            type to give to the new document set.
        """

        return_type = DocumentSet(context)

        def _parent_folder_loaded():
            custom_props = parent_folder.get_property("Properties")
            list_id = custom_props.get("vti_x005f_listname")
            target_list = context.web.lists.get_by_id(list_id)
            target_list.ensure_property("Title", _create, target_list=target_list)

        def _create(target_list):
            # type: (List) -> None
            qry = ClientQuery(context, return_type=return_type)
            context.add_query(qry)
            folder_url = parent_folder.serverRelativeUrl + "/" + name
            return_type.set_property("ServerRelativeUrl", folder_url)

            def _construct_request(request):
                # type: (RequestOptions) -> None
                list_name = target_list.title.replace(" ", "")
                request.url = r"{0}/_vti_bin/listdata.svc/{1}".format(
                    context.base_url, list_name
                )
                request.set_header("Slug", "{0}|{1}".format(folder_url, ct_id))
                request.method = HttpMethod.Post

            context.before_execute(_construct_request)

        parent_folder.ensure_properties(
            ["UniqueId", "Properties", "ServerRelativeUrl"], _parent_folder_loaded
        )
        return return_type

    @staticmethod
    def get_document_set(context, folder):
        """Retrieves the document set object from a specified folder object.

        :type context: office365.sharepoint.client_context.ClientContext
        :param office365.sharepoint.folders.folder.Folder folder: the Folder object from which
            to get the document set
        """
        return_type = DocumentSet(context)
        return return_type

Parameters

Parameter Details

context: A ClientContext instance that provides the connection and authentication context to the SharePoint server. This is required for all server operations and maintains the session state.

parent_folder: A Folder object representing the parent location where the new DocumentSet will be created. Must be a valid folder within a SharePoint list or library.

name: The name string to assign to the new DocumentSet. This will be used as both the display name and part of the server-relative URL.

ct_id: The ContentTypeId string identifying the content type to assign to the DocumentSet. Defaults to '0x0120D520' which is the standard DocumentSet content type identifier in SharePoint.

folder: A Folder object from which to retrieve the associated DocumentSet. Used in the get_document_set method to convert a folder reference into a DocumentSet instance.

Return Value

The create method returns a DocumentSet instance that represents the newly created DocumentSet on the server. The get_document_set method returns a DocumentSet instance representing the document set associated with the provided folder. Both methods return DocumentSet objects that inherit all properties and methods from the Folder base class, with the ServerRelativeUrl property set appropriately.

Class Interface

Methods

Attributes

Dependencies

• office365-rest-python-client

Required Imports

from office365.runtime.http.http_method import HttpMethod
from office365.runtime.http.request_options import RequestOptions
from office365.runtime.queries.client_query import ClientQuery
from office365.sharepoint.folders.folder import Folder
from office365.sharepoint.lists.list import List

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.document_sets.document_set import DocumentSet
from office365.sharepoint.folders.folder import Folder

# Setup context with authentication
ctx = ClientContext('https://yourtenant.sharepoint.com/sites/yoursite')
ctx = ctx.with_credentials(UserCredential('username', 'password'))

# Get parent folder where DocumentSet will be created
parent_folder = ctx.web.get_folder_by_server_relative_url('/sites/yoursite/Shared Documents')

# Create a new DocumentSet
doc_set = DocumentSet.create(
    context=ctx,
    parent_folder=parent_folder,
    name='MyNewDocumentSet',
    ct_id='0x0120D520'
)
ctx.execute_query()

print(f'Created DocumentSet at: {doc_set.serverRelativeUrl}')

# Retrieve an existing DocumentSet from a folder
existing_folder = ctx.web.get_folder_by_server_relative_url('/sites/yoursite/Shared Documents/MyNewDocumentSet')
doc_set_retrieved = DocumentSet.get_document_set(ctx, existing_folder)
ctx.execute_query()

Best Practices

• Always call ctx.execute_query() after creating or retrieving a DocumentSet to ensure the server operations are executed and properties are loaded
• Ensure the parent folder is properly loaded with required properties (UniqueId, Properties, ServerRelativeUrl) before creating a DocumentSet
• Verify that the DocumentSet content type is enabled on the target list before attempting to create a DocumentSet
• Use the default ct_id '0x0120D520' unless you have a custom DocumentSet content type defined
• Handle authentication and permissions appropriately as DocumentSet creation requires elevated permissions
• The create method uses a complex callback chain (_parent_folder_loaded -> _create -> _construct_request) that executes asynchronously, so proper query execution is critical
• The get_document_set method is a lightweight wrapper that returns a DocumentSet instance but does not validate that the folder is actually a DocumentSet
• DocumentSet inherits from Folder, so all Folder methods and properties are available on DocumentSet instances

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class TermSet 64.1% similar

  Represents a hierarchical or flat set of Term objects in SharePoint taxonomy, providing access to localized names and child terms within a term set.

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

• class TermSetCollection 62.1% similar

  A collection class that manages and provides access to a set of TermSet objects within SharePoint's taxonomy/metadata management system.

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

• class DocumentSharingManager 60.6% similar

  A SharePoint document sharing manager class that provides static methods for managing document permissions, sharing settings, and shared views in SharePoint.

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

• class DocumentsSharedWithGroup 59.9% similar

  A class representing a SharePoint list that manages documents shared with a SharePoint Group on a user's personal site.

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

• class SharedDocumentInfo 59.1% similar

  A SharePoint entity class representing metadata and information about a shared document, including its activity and author details.

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