tessl/pypi-office365-rest-python-client
Microsoft 365 & Microsoft Graph Library for Python
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
sharepoint-sites.mddocs/
SharePoint Sites
Comprehensive SharePoint functionality including sites, lists, libraries, files, folders, and content management through SharePoint REST API. Provides complete document and content management capabilities for SharePoint Online environments.
Capabilities
Site and Web Management
SharePoint site collection and web management with comprehensive configuration, navigation, and content organization capabilities.
class Site:
"""SharePoint site collection with comprehensive management capabilities."""
# Core Properties
id: str
url: str
web_url: str
display_name: str
name: str
description: str
created: str
last_modified: str
server_relative_url: str
def get(self) -> 'Site':
"""
Retrieve site information and metadata.
Returns:
Site: Updated site object
"""
def update(self) -> 'Site':
"""
Update site properties.
Returns:
Site: Updated site object
"""
def get_changes(self, query: Dict[str, Any]) -> List[Dict[str, Any]]:
"""
Get site changes based on change query.
Args:
query (Dict): Change query parameters
Returns:
List[Dict]: Site changes matching query
"""
# Navigation Properties
@property
def root_web(self) -> 'Web':
"""Root web of the site collection."""
@property
def lists(self) -> 'ListCollection':
"""Lists in the site."""
@property
def webs(self) -> 'WebCollection':
"""Subwebs in the site."""
class Web:
"""SharePoint web with comprehensive content and configuration management."""
# Core Properties
id: str
title: str
description: str
url: str
server_relative_url: str
web_template: str
language: int
created: str
last_item_modified_date: str
last_item_user_modified_date: str
ui_version: int
def get(self) -> 'Web':
"""
Retrieve web information and properties.
Returns:
Web: Updated web object
"""
def update(self) -> 'Web':
"""
Update web properties and settings.
Returns:
Web: Updated web object
"""
def delete(self) -> None:
"""Delete web and all its content."""
def apply_web_template(self, web_template: str) -> None:
"""
Apply web template to web.
Args:
web_template (str): Web template name
"""
def get_file_by_server_relative_url(self, server_relative_url: str) -> 'File':
"""
Get file by server-relative URL.
Args:
server_relative_url (str): Server-relative URL of file
Returns:
File: File object at specified URL
"""
def get_folder_by_server_relative_url(self, server_relative_url: str) -> 'Folder':
"""
Get folder by server-relative URL.
Args:
server_relative_url (str): Server-relative URL of folder
Returns:
Folder: Folder object at specified URL
"""
# Navigation Properties
@property
def lists(self) -> 'ListCollection':
"""Lists in the web."""
@property
def folders(self) -> 'FolderCollection':
"""Folders in the web."""
@property
def files(self) -> 'FileCollection':
"""Files in the web."""
@property
def webs(self) -> 'WebCollection':
"""Subwebs of this web."""
@property
def site_users(self) -> 'UserCollection':
"""Users with access to the web."""
@property
def site_groups(self) -> 'GroupCollection':
"""SharePoint groups in the web."""
@property
def role_definitions(self) -> 'RoleDefinitionCollection':
"""Permission levels defined in the web."""
class WebCollection:
"""Collection of SharePoint webs with management capabilities."""
def get(self) -> 'WebCollection':
"""Retrieve collection of webs."""
def add(self, web_creation_info: Dict[str, Any]) -> Web:
"""
Create new subweb.
Args:
web_creation_info (Dict): Web creation parameters
Returns:
Web: Created web object
"""
def get_by_id(self, web_id: str) -> Web:
"""
Get web by ID.
Args:
web_id (str): Web unique identifier
Returns:
Web: Web object
"""List and Library Management
SharePoint list and document library operations with comprehensive item management, content types, and field customization.
class List:
"""SharePoint list with comprehensive item and configuration management."""
# Core Properties
id: str
title: str
description: str
base_template: int
base_type: int # 0=GenericList, 1=DocumentLibrary
created: str
last_item_modified_date: str
last_item_user_modified_date: str
item_count: int
hidden: bool
def get(self) -> 'List':
"""
Retrieve list information and properties.
Returns:
List: Updated list object
"""
def update(self) -> 'List':
"""
Update list properties and settings.
Returns:
List: Updated list object
"""
def delete(self) -> None:
"""Delete list and all its content."""
def get_items(self, caml_query: str = None) -> 'ListItemCollection':
"""
Get list items with optional CAML query.
Args:
caml_query (str, optional): CAML query to filter items
Returns:
ListItemCollection: Collection of list items
"""
def add_item(self, item_properties: Dict[str, Any]) -> 'ListItem':
"""
Add new item to list.
Args:
item_properties (Dict): Item field values
Returns:
ListItem: Created list item
"""
def get_item_by_id(self, item_id: int) -> 'ListItem':
"""
Get list item by ID.
Args:
item_id (int): Item ID
Returns:
ListItem: List item object
"""
def break_role_inheritance(self, copy_role_assignments: bool = True, clear_subscopes: bool = True) -> None:
"""
Break permission inheritance from parent.
Args:
copy_role_assignments (bool): Copy existing permissions
clear_subscopes (bool): Clear permissions on child objects
"""
def reset_role_inheritance(self) -> None:
"""Reset permission inheritance to parent."""
# Navigation Properties
@property
def items(self) -> 'ListItemCollection':
"""Items in the list."""
@property
def fields(self) -> 'FieldCollection':
"""Fields (columns) in the list."""
@property
def views(self) -> 'ViewCollection':
"""Views defined for the list."""
@property
def content_types(self) -> 'ContentTypeCollection':
"""Content types enabled for the list."""
@property
def root_folder(self) -> 'Folder':
"""Root folder of the list."""
@property
def role_assignments(self) -> 'RoleAssignmentCollection':
"""Permission assignments for the list."""
class ListCollection:
"""Collection of SharePoint lists with management capabilities."""
def get(self) -> 'ListCollection':
"""Retrieve collection of lists."""
def filter(self, expression: str) -> 'ListCollection':
"""
Filter lists by OData expression.
Args:
expression (str): OData filter expression
Returns:
ListCollection: Filtered collection
"""
def get_by_title(self, title: str) -> List:
"""
Get list by title.
Args:
title (str): List title
Returns:
List: List object
"""
def get_by_id(self, list_id: str) -> List:
"""
Get list by ID.
Args:
list_id (str): List unique identifier
Returns:
List: List object
"""
def add(self, list_creation_info: Dict[str, Any]) -> List:
"""
Create new list.
Args:
list_creation_info (Dict): List creation parameters
Returns:
List: Created list object
"""
class ListItem:
"""SharePoint list item with comprehensive field and permission management."""
# Core Properties
id: int
title: str
created: str
modified: str
author_id: int
editor_id: int
file_system_object_type: int # 0=File, 1=Folder
def get(self) -> 'ListItem':
"""
Retrieve list item and field values.
Returns:
ListItem: Updated list item object
"""
def update(self) -> 'ListItem':
"""
Update list item field values.
Returns:
ListItem: Updated list item object
"""
def delete(self) -> None:
"""Delete list item."""
def recycle(self) -> str:
"""
Move item to recycle bin.
Returns:
str: Recycle bin item ID
"""
def get_field_value(self, field_name: str) -> Any:
"""
Get field value by field name.
Args:
field_name (str): Internal field name
Returns:
Any: Field value
"""
def set_field_value(self, field_name: str, field_value: Any) -> None:
"""
Set field value by field name.
Args:
field_name (str): Internal field name
field_value (Any): Field value to set
"""
def validate_update_list_item(self, form_values: List[Dict[str, str]], new_document_update: bool = False) -> List[Dict[str, Any]]:
"""
Validate and update list item using form values.
Args:
form_values (List[Dict]): Field values to validate and update
new_document_update (bool): Whether this is a new document update
Returns:
List[Dict]: Validation results
"""
# Navigation Properties
@property
def properties(self) -> Dict[str, Any]:
"""All field values as dictionary."""
@property
def file(self) -> 'File':
"""Associated file (for document libraries)."""
@property
def folder(self) -> 'Folder':
"""Associated folder (for folder items)."""
@property
def attachment_files(self) -> 'AttachmentCollection':
"""File attachments for the item."""
@property
def role_assignments(self) -> 'RoleAssignmentCollection':
"""Permission assignments for the item."""
class ListItemCollection:
"""Collection of SharePoint list items with query capabilities."""
def get(self) -> 'ListItemCollection':
"""Retrieve collection of list items."""
def filter(self, expression: str) -> 'ListItemCollection':
"""
Filter items by OData expression.
Args:
expression (str): OData filter expression
Returns:
ListItemCollection: Filtered collection
"""
def select(self, properties: List[str]) -> 'ListItemCollection':
"""
Select specific fields to retrieve.
Args:
properties (List[str]): Field names to select
Returns:
ListItemCollection: Collection with selected fields
"""
def top(self, count: int) -> 'ListItemCollection':
"""
Limit results to top N items.
Args:
count (int): Maximum number of items
Returns:
ListItemCollection: Limited collection
"""
def get_by_id(self, item_id: int) -> ListItem:
"""
Get item by ID.
Args:
item_id (int): Item ID
Returns:
ListItem: List item object
"""
def add(self, item_creation_info: Dict[str, Any]) -> ListItem:
"""
Add new item to collection.
Args:
item_creation_info (Dict): Item properties
Returns:
ListItem: Created list item
"""File and Folder Operations
Comprehensive file system operations with version control, check-in/check-out, and metadata management for SharePoint document libraries.
class File:
"""SharePoint file with comprehensive content and version management."""
# Core Properties
name: str
server_relative_url: str
time_created: str
time_last_modified: str
title: str
ui_version: int
ui_version_label: str
unique_id: str
length: int
major_version: int
minor_version: int
check_out_type: int
checkout_user_id: int
def get(self) -> 'File':
"""
Retrieve file information and metadata.
Returns:
File: Updated file object
"""
def delete(self) -> None:
"""Delete file."""
def recycle(self) -> str:
"""
Move file to recycle bin.
Returns:
str: Recycle bin item ID
"""
def checkout(self) -> None:
"""Check out file for editing."""
def checkin(self, comment: str = None, check_in_type: int = 1) -> None:
"""
Check in file after editing.
Args:
comment (str, optional): Check-in comment
check_in_type (int): Check-in type (0=MinorCheckIn, 1=MajorCheckIn, 2=OverwriteCheckIn)
"""
def undo_checkout(self) -> None:
"""Undo file checkout."""
def publish(self, comment: str = None) -> None:
"""
Publish major version of file.
Args:
comment (str, optional): Publishing comment
"""
def unpublish(self, comment: str = None) -> None:
"""
Unpublish file.
Args:
comment (str, optional): Unpublishing comment
"""
def approve(self, comment: str = None) -> None:
"""
Approve file for publication.
Args:
comment (str, optional): Approval comment
"""
def deny(self, comment: str = None) -> None:
"""
Deny file approval.
Args:
comment (str, optional): Denial comment
"""
def get_content(self) -> bytes:
"""
Download file content.
Returns:
bytes: File content as bytes
"""
def save_binary(self, content: bytes) -> None:
"""
Upload file content.
Args:
content (bytes): File content to upload
"""
def copy_to(self, new_url: str, overwrite: bool = False) -> None:
"""
Copy file to new location.
Args:
new_url (str): Destination URL
overwrite (bool): Overwrite existing file
"""
def move_to(self, new_url: str, overwrite: bool = False) -> None:
"""
Move file to new location.
Args:
new_url (str): Destination URL
overwrite (bool): Overwrite existing file
"""
# Navigation Properties
@property
def list_item_all_fields(self) -> ListItem:
"""Associated list item with all fields."""
@property
def versions(self) -> 'FileVersionCollection':
"""File version history."""
@property
def properties(self) -> Dict[str, Any]:
"""File properties and metadata."""
class FileCollection:
"""Collection of SharePoint files with management capabilities."""
def get(self) -> 'FileCollection':
"""Retrieve collection of files."""
def add(self, url: str, content: bytes, overwrite: bool = False) -> File:
"""
Add new file to collection.
Args:
url (str): File URL
content (bytes): File content
overwrite (bool): Overwrite existing file
Returns:
File: Added file object
"""
def add_template_file(self, url_of_file: str, template_file_type: int) -> File:
"""
Add file from template.
Args:
url_of_file (str): File URL
template_file_type (int): Template type
Returns:
File: Created file from template
"""
def get_by_url(self, url: str) -> File:
"""
Get file by URL.
Args:
url (str): File URL
Returns:
File: File object
"""
class Folder:
"""SharePoint folder with comprehensive content and permission management."""
# Core Properties
name: str
server_relative_url: str
time_created: str
time_last_modified: str
unique_id: str
item_count: int
def get(self) -> 'Folder':
"""
Retrieve folder information.
Returns:
Folder: Updated folder object
"""
def delete(self) -> None:
"""Delete folder and all contents."""
def recycle(self) -> str:
"""
Move folder to recycle bin.
Returns:
str: Recycle bin item ID
"""
def copy_to(self, new_url: str) -> None:
"""
Copy folder to new location.
Args:
new_url (str): Destination URL
"""
def move_to(self, new_url: str) -> None:
"""
Move folder to new location.
Args:
new_url (str): Destination URL
"""
def upload_file(self, name: str, content: bytes) -> File:
"""
Upload file to folder.
Args:
name (str): File name
content (bytes): File content
Returns:
File: Uploaded file object
"""
def add_sub_folder(self, name: str) -> 'Folder':
"""
Create subfolder.
Args:
name (str): Folder name
Returns:
Folder: Created subfolder
"""
# Navigation Properties
@property
def files(self) -> FileCollection:
"""Files in the folder."""
@property
def folders(self) -> 'FolderCollection':
"""Subfolders in the folder."""
@property
def list_item_all_fields(self) -> ListItem:
"""Associated list item."""
@property
def properties(self) -> Dict[str, Any]:
"""Folder properties and metadata."""
class FolderCollection:
"""Collection of SharePoint folders with management capabilities."""
def get(self) -> 'FolderCollection':
"""Retrieve collection of folders."""
def add(self, url: str) -> Folder:
"""
Add new folder to collection.
Args:
url (str): Folder URL
Returns:
Folder: Created folder object
"""
def get_by_url(self, url: str) -> Folder:
"""
Get folder by URL.
Args:
url (str): Folder URL
Returns:
Folder: Folder object
"""Usage Examples
Site and Web Operations
from office365.sharepoint.client_context import ClientContext
ctx = ClientContext("https://tenant.sharepoint.com/sites/sitename").with_client_credentials(
client_id="your-client-id",
client_secret="your-client-secret"
)
# Get site information
site = ctx.site.get().execute_query()
print(f"Site: {site.url}")
# Get web information
web = ctx.web.get().execute_query()
print(f"Web title: {web.title}, URL: {web.url}")
# Create subweb
subweb_info = {
"Title": "Project Site",
"Url": "project",
"Description": "Project collaboration site",
"WebTemplate": "STS#3", # Team Site template
"Language": 1033, # English
"UseSamePermissionsAsParentSite": True
}
new_web = web.webs.add(subweb_info).execute_query()
print(f"Created subweb: {new_web.title}")List and Item Operations
# Get document library
docs_lib = web.lists.get_by_title("Documents").get().execute_query()
print(f"Library: {docs_lib.title}, Item count: {docs_lib.item_count}")
# Create custom list
list_info = {
"Title": "Project Tasks",
"Description": "Tasks for the project",
"BaseTemplate": 100 # Generic List
}
new_list = web.lists.add(list_info).execute_query()
# Add list item
item_properties = {
"Title": "Setup development environment",
"Description": "Install and configure development tools",
"Priority": "High"
}
new_item = new_list.items.add(item_properties).execute_query()
print(f"Created item: {new_item.properties['Title']}")
# Get list items
items = new_list.items.select(["Title", "Description", "Priority"]).get().execute_query()
for item in items:
print(f"Task: {item.properties['Title']} - {item.properties['Priority']}")
# Update list item
new_item.set_field_value("Priority", "Medium")
new_item.update().execute_query()File Operations
# Upload file to document library
with open("project_plan.docx", "rb") as file_content:
uploaded_file = docs_lib.root_folder.upload_file("project_plan.docx", file_content.read())
ctx.execute_query()
print(f"Uploaded: {uploaded_file.server_relative_url}")
# Get file information
file_info = docs_lib.root_folder.files.get_by_url("project_plan.docx").get().execute_query()
print(f"File: {file_info.name}, Size: {file_info.length} bytes")
# Download file
file_content = file_info.get_content()
with open("downloaded_plan.docx", "wb") as local_file:
local_file.write(file_content)
# Check out and check in file
file_info.checkout()
ctx.execute_query()
print("File checked out")
# Update file content (simplified)
with open("updated_plan.docx", "rb") as updated_content:
file_info.save_binary(updated_content.read())
ctx.execute_query()
# Check in file
file_info.checkin("Updated project timeline", 1) # Major version
ctx.execute_query()
print("File checked in")Folder Management
# Create folder structure
project_folder = docs_lib.root_folder.add_sub_folder("Project Alpha").execute_query()
docs_folder = project_folder.add_sub_folder("Documents").execute_query()
images_folder = project_folder.add_sub_folder("Images").execute_query()
# List folder contents
folders = docs_lib.root_folder.folders.get().execute_query()
for folder in folders:
print(f"Folder: {folder.name}")
files = docs_lib.root_folder.files.get().execute_query()
for file in files:
print(f"File: {file.name}")Types
from typing import Dict, List, Any, Optional
class WebCreationInformation:
"""Information for creating new web."""
title: str
url: str
description: str
web_template: str
language: int
use_same_permissions_as_parent_site: bool
class ListCreationInformation:
"""Information for creating new list."""
title: str
description: str
base_template: int
document_template_type: int
quick_launch_option: int
template_feature_id: str
class ListItemCreationInformation:
"""Information for creating new list item."""
folder_url: str
list_item_type: str
under_lyingObjectType: int
class FileCreationInformation:
"""Information for creating new file."""
content: bytes
overwrite: bool
url: str
class FolderCreationInformation:
"""Information for creating new folder."""
url: str
underlyingObjectType: int
class ChangeQuery:
"""Query parameters for retrieving changes."""
add: bool
alert: bool
content_type: bool
delete_object: bool
field: bool
file: bool
folder: bool
group: bool
group_membership: bool
item: bool
list: bool
move: bool
navigation: bool
rename: bool
restore: bool
role_assignment: bool
role_definition: bool
security_policy: bool
site: bool
system_update: bool
update: bool
user: bool
view: bool
web: bool
class CamlQuery:
"""CAML query for retrieving list items."""
view_xml: str
folder_server_relative_url: str
list_item_collection_position: Dict[str, str]
class FieldUserValue:
"""User field value."""
lookup_id: int
lookup_value: str
email: str
class FieldLookupValue:
"""Lookup field value."""
lookup_id: int
lookup_value: str
class FieldUrlValue:
"""URL field value."""
description: str
url: strInstall with Tessl CLI
npx tessl i tessl/pypi-office365-rest-python-client