🔍 Code Extractor

A data transfer object (DTO) class that encapsulates properties required for creating a file in a SharePoint FileCollection, including URL, overwrite flag, and content.

Purpose

This class serves as a parameter object for the FileCollection.Add method in SharePoint operations. It bundles together all necessary information for file creation: the target URL (relative or absolute), whether to overwrite existing files, the file content (as string or bytes), and an optional XorHash for integrity verification. It inherits from ClientValue, making it serializable for transmission to SharePoint services.

Source Code

class FileCreationInformation(ClientValue):
    """Represents properties that can be set when creating a file by using the FileCollection.Add method."""

    def __init__(self, url=None, overwrite=False, content=None):
        """
        :param str url: Specifies the URL of the file to be added. It MUST NOT be NULL. It MUST be a URL of relative
            or absolute form. Its length MUST be equal to or greater than 1.
        :param bool overwrite: Specifies whether to overwrite an existing file with the same name and in the same
            location as the one being added.
        :param str or bytes content: Specifies the binary content of the file to be added.
        """
        super(FileCreationInformation, self).__init__()
        self.Url = url
        self.Overwrite = overwrite
        self.Content = content
        self.XorHash = None

    def to_json(self, json_format=None):
        return {"overwrite": self.Overwrite, "url": self.Url}

    @property
    def entity_type_name(self):
        return None

Parameters

Parameter Details

url: The URL where the file will be created. Can be relative or absolute. Must be non-null and have length >= 1. This specifies the destination path for the new file within the SharePoint site or document library.

overwrite: Boolean flag indicating whether to replace an existing file at the same URL. If True, any existing file will be overwritten; if False, the operation may fail if a file already exists at the target location. Defaults to False.

content: The actual file content to be uploaded. Can be provided as either a string (for text files) or bytes (for binary files). This is the data that will be written to the created file.

Return Value

Instantiation returns a FileCreationInformation object with the specified properties set. The to_json() method returns a dictionary containing 'overwrite' and 'url' keys for serialization. The entity_type_name property returns None, indicating this is a value object rather than an entity.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.runtime.client_value import ClientValue

Usage Example

from office365.runtime.client_value import ClientValue
from office365.sharepoint.files.file_creation_information import FileCreationInformation

# Create file info for a text file
file_info = FileCreationInformation(
    url='Documents/example.txt',
    overwrite=True,
    content=b'Hello, World!'
)

# Access properties
print(file_info.Url)  # 'Documents/example.txt'
print(file_info.Overwrite)  # True

# Serialize to JSON for API call
json_data = file_info.to_json()
print(json_data)  # {'overwrite': True, 'url': 'Documents/example.txt'}

# Typically used with FileCollection.Add:
# folder.files.add(file_info).execute_query()

Best Practices

• Always provide a valid URL with length >= 1 when instantiating this class
• Use bytes for binary file content and string for text content to ensure proper encoding
• Set overwrite=True only when you intentionally want to replace existing files
• This is an immutable-style DTO - set all properties during instantiation rather than modifying after creation
• The XorHash attribute is optional and typically set by the system for integrity verification
• This object is meant to be passed to FileCollection.Add() method, not used standalone
• The to_json() method only serializes url and overwrite; content is handled separately in the upload process

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class ContentTypeCreationInformation 78.3% similar

  A data transfer object that encapsulates properties required to create a new SharePoint content type, inheriting from ClientValue for serialization support.

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

• class AttachmentCreationInformation 78.1% similar

  A data class that encapsulates the properties required to create a file attachment in SharePoint, including filename and binary content.

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

• class GroupCreationInformation 75.1% similar

  A data transfer object (DTO) class that encapsulates information required to create a cross-site SharePoint group.

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

• class ListItemCreationInformation 74.5% similar

  A data class that encapsulates the properties required to create a new list item in SharePoint, including file/folder specification, name, and location.

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

• class WebCreationInformation 73.0% similar

  A data transfer object (DTO) class that encapsulates metadata required for creating a new SharePoint site (web).

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