Highlights

A large release: a full migration toolkit (SharePoint / Outlook / Teams)
with SMAT-style pre-migration assessment, first-class parallel execution
(execute_batch / execute_query_parallel), a data pipeline
(CSV/JSON/NDJSON/Excel + optional pandas), and a set of long-standing
SharePoint/OneDrive fixes (#881, #988, #915, #884, #793, #875).

No breaking API changes - a drop-in upgrade from 3.0.0.

Added

• Migration toolkit - product-agnostic core plus sharepoint, outlook
  and teams products: resumable MigrationJob/MigrationSession with
  checkpoints, filesystem/SharePoint/JSON/Teams archive adapters, parallel
  transfer, a server-side ingestion job, and summary/item/failure reports.
• SMAT-style pre-migration assessment — modular scans/containers,
  MigrationAssessor/MigrationTenantAssessor/MailboxAssessor, typed scan
  reports (LargeSites, LockedSites, MailFolders) and CSV/JSON export.
• Parallel execution - execute_batch(concurrency=N) on ClientContext
  and GraphClient, plus execute_query_parallel(concurrency=N) for
  pipelined I/O over independent queries; both retry transient failures per
  request honoring Retry-After.
• Data pipeline - CSV/JSON/NDJSON/Excel import-export,
  from_csv/from_json/from_records, dynamic list-item columns, and an
  optional pandas bridge (to_dataframe/from_dataframe).
• SharePoint - taxonomy term store (OData v2.1/V4) support, site
  primitives, folder download with version history, zip ↔ folder primitives,
  Web.ensure_list, DriveItem.ensure_folder, and typed field creators.
• Generator - OData function/action method generation, a return-type
  descriptor/resolver, and list-typed primitive collection parameters.

Changed

• Thread-safe auth and form-digest caches (single-flight refresh);
  ClientContext.clone now shares the auth context and transport.
• First-class retry (exponential backoff + jitter) and throttling
  (rate-limit/health headers) primitives; ClientQuery generics made
  consistent.
• Examples reorganized into product galleries and an SPMT-style migration flow
  (assess/ → migrate/ → monitor/).

Fixed

• Long file paths in moves (#988) - body-based File.move_by_path /
  MoveCopyUtil.move_file_by_path; slashes are no longer percent-encoded
  inside OData string literals.
• Bulk OneDrive downloads (#881) - download_folder paginates children
  instead of stopping at the first page.
• SharePoint paging falls back to $skip when no next link is returned
  (#915), and custom headers are preserved across pages.
• Apostrophes in file paths (#884), in-memory upload streams (#793),
  sharing-token UTF-8/padding (#875).
• @odata.type casting for directory collections (#921); principal path
  precedence (#895); delta-token/custom query-param handling (#948);
  malformed JSON surfaced as ClientRequestException.

3.0.0

First major release in over a year - and it's live on PyPI with an automated release pipeline.

⚠️ Breaking changes

• Python 2 dropped - minimum supported version is now Python 3.8
• ACS/SAML retirement - with_user_credentials now raises RuntimeError for SharePoint Online. Use with_username_and_password (MSAL ROPC) instead. ACS App-Only (with_client_credentials) is marked deprecated.
• USGovernment GCC endpoints corrected - were pointing at the wrong URLs

✨ What's new

• Full type hints across the entire library (runtime, directory, onedrive, outlook, teams, sharepoint, intune, and more)
• with_username_and_password (MSAL ROPC) for SharePoint Online auth
• Substantially expanded model coverage: Defender/security evidence types, subject rights requests, retention labels, threat intelligence, Copilot/Teams event details, and more
• Expanded Intune (Cloud PC) and Teams surface area
• New query/example modules for SharePoint, Graph, and Entra ID

🔧 Fixed

• Cryptography CVEs updated to 48.0.0
• Circular import in client_runtime_context.py / read_entity.py
• NameError: name 'List' is not defined in fields/collection.py
• single() and first() return types (never return None)
• AttributeError: 'str' object has no attribute 'get' when SharePoint returns a string error payload
• Pyright type-checking errors across the library and tests
• Python 3.8 compatibility for PEP 604 type annotations

🧹 Removed

• Python 2.7 support
• .travis.yml (moved to GitHub Actions)
• requirements.txt / requirements-dev.txt (use uv/pyproject.toml)

🚀 Install

pip install --upgrade office365-rest-python-client

Or with uv:

uv pip install --upgrade office365-rest-python-client

Changelog

• #953: support Access Token Refresh for MSAL Provided Tokens by @kamilkrukowski
• #956: resolve get_comments() method issue
• #958: added Reply To and HTML ItemBody Type support in send_mail functionality by @bhavberi
• #960: address File.open_binary issue by @bhavberi
• #961: fixed all the issues in linting github action by @bhavberi

Changelog

• support for Azure environments in ClientContext

ctx = ClientContext(
    site_url, environment=AzureEnvironment.USGovernmentHigh
).with_client_credentials(client_id, client_secret)

• #950: Username and password authentication (with_user_credentials method): Added support for automatically renewing authentication cookies when the expiration period ends (after 30 minutes)

• #926: support for used range has been introduced

Changelog

• #900 & #901: Add include_resource_data to SubscriptionCollection.add by @optimygmbh
• #918: Add urllib parse quote encoding to the URL by @CTPassion
• Microsoft Search API enhancements

Changelog

#835 - JSON batch request fixes

Changelog

#788 - batch request fixes and improvements

Changelog

• #873: fix error when creating a choice field
• #872: fix shares.by_url method
• #869: Bump msal from 1.24.1 to 1.28.0
• #627: Fixes failing driveItem move operation by @ErmalKristo

Changelog

• #866: fix path issue when addressing drive items

Changelog

• #847 Add a note for Entra ID permissions when updating SP metadata fields
• #850 Fixes issue of str raising exception when DecodeUrl is None
• #844 changes for DriveItem.get_files and DriveItem.get_folders methods to address retrieving all the items (if collection exceeds the default page size)

Changelog

• SharePoint resources addressing enhancements
• introduced methods for granting and revoking delegated & application permissions

Example 1: grant an app role to a client service principal

client = GraphClient.with_token_interactive(
    tenant_name_or_id, app_client_id, admin_principal_name
)

resource = client.service_principals.get_by_name("Microsoft Graph")
app = client.applications.get_by_app_id(app_client_id)
resource.grant_application(app, "MailboxSettings.Read").execute_query()

Example 2: grant a delegated permission to the client service principal on behalf of a user

client = GraphClient.with_token_interactive(
    tenant_name_or_id, app_client_id, admin_principal_name
)

resource = client.service_principals.get_by_name("Microsoft Graph")
app_role = "User.Read.All"
user = client.users.get_by_principal_name(test_user_principal_name)
resource.grant_delegated(app_client_id, user, app_role).execute_query()

Changelog

• #836: support for passing a passphrase in ClientContext.with_client_certificate method

Example:

cert_credentials = {
    "tenant": tenant_name,
    "client_id": client_id,
    "thumbprint": cert_thumbprint,
    "cert_path": "selfsignkeyenc.pem",
    "passphrase": "Password",
}
ctx = ClientContext(site_url).with_client_certificate(**cert_credentials)
current_web = ctx.web.get().execute_query()

Changelog

• #693: support for folder coloring methods in SharePoint API

Example: create a folder with a color

ctx = ClientContext(site_url).with_credentials(user_credentials)
root_folder = ctx.web.default_document_library().root_folder
folder = root_folder.folders.add(
    "archive", color_hex=FolderColors.DarkGreen
).execute_query()

Changelog

• #745: better support for Range in OneDrive API

Example: get Range

client = GraphClient.with_username_and_password(
    tenant_name, client_id, username, password
)
drive_item = client.me.drive.root.get_by_path("Financial Report.xlsx")
worksheets = drive_item.workbook.worksheets.get().execute_query()
if len(worksheets) == 0:
    sys.exit("No worksheets found")

worksheet_range = worksheets["Sheet1"].range(address="A1:B3").execute_query()

Changelog

• #794 SharePoint authentication support with GCC High Environments by @DEADSCOP
• #802 fix listing folders insted of listing files by @Yusuf-ASM
• #801 fix for addressing shared drive items

Changelog

• #791 fix: do not reuse same instance for recipient by @byenilmez
• #787 support for file_name parameter in File.copyto and File.copyto_using_path methods
• #781: fix for ImportError: cannot import name 'TypedDict' from 'typing' on Python 3.7
• #764: fix for parent_folder and parent_collection empty when retrieving file using ctx.web.get_file_by_server_relative_url
• #735 fix for 401 Client Error: Unauthorised for url on site property update

Changelog

• #762: Missing dependency typing_extensions on Python by @chludwig-haufe
• #764: file and folder addresing methods fixes
• #765: CI & Linting improvements and fixes by @kellerza
• #766: fix to share file with password
• #767: fix change token entity type namefix change token entity type name by @benediktziegler
• #768: documentation fixes by @TomPughe

Changelog

• #757: Conditionally import ParamSpec from typing_extensions by @thaiphv

Changelog

• #740: fix for Folder.copy_to_using_path method
• #743: introduce black for code formatting and fix flake8 by @kellerza
• #746 & #747 typing improvements (support for mypy and pyright type checkers) by @kellerza
• #744: Fix ResourcePath collection by @kellerza
• #748: File.download_session method fix
• introduced GraphClient.with_client_secret and GraphClient.with_username_and_password methods to initialize the client, refer below examples

Example: initializes a GraphClient client using user namename and password flow:

from office365.graph_client import GraphClient

client = GraphClient.with_username_and_password(
    "contoso.onmicrosoft.com", client_id, username, password
)

Example: initializes a GraphClient with client secret:

from office365.graph_client import GraphClient
client = GraphClient.with_client_secret("contoso.onmicrosoft.com", client_id, client_secret)

Changelog

• #723: fixes FieldCollection.add_dependent_lookup_field by @pclasen-eb
• #722: fixes 404 error with Web.get_file_by_server_relative_path method

Changelog

• #682: fixes the bug with loosing event handlers
• Support for Interactive authentication via ClientContext.with_interactive method introduced
• #713: support for oauth2 device code auth introduced

Example: demonstrates how to interactively authenticate via ClientContext client

tenant = "contoso.onmicrosoft.com"

ctx = ClientContext(site_url).with_interactive(tenant, client_id)
me = ctx.web.current_user.get().execute_query()
print(me.login_name)

Changelog

• #645: fixed error when file get addressed by path

Enhancements for files and folders addressing in SharePoint v1 API

When addressing a file or folder, in addition to server relative url format /sites/mysite/folder/filename.ext, it is supported to specify url in site or web relative format now: folder/filename.ext, for example:

ctx = ClientContext(site_url).with_credentials(credentials)
file_url = 'Shared Documents/Report.xlsx'
file = ctx.web.get_file_by_server_relative_url(file_url).get().execute_query()

Support for long running actions in Teams API, polling for status method introduced

Use ensure_created method which polls for team status to determine whether it has been created:

client = GraphClient(acquire_token)
new_team = client.teams.create(team_name).ensure_created().execute_query()

Changelog

• #672: Error handling for when response is not present by @akrymskiy
• #667: add ability to pass b64 formatted string when adding attachments by @padamscrestonecapital
• #666: fix for resetting ClientResult (return type) between calls when passing to execute_query method by @vgrem
• #656: upload session query method compatible with memoryfs python library by @brunoabreu0
• #655: fix for OneDrive example by @GitSumito

Changelog

• #641: add bcc and cc support for users.send_mail by @caleb-depotanalytics
• #649: added examples and authentication clarification by @rebeccajhampton
• SharePoint API search namespace enhancements

SharePoint API search namespace enhancements

For methods from SharePoint API search namespace those return type contains value pf SimpleDataTable type, cell values getting addressed like this:

for row in results.Table.Rows:
    print(row.Cells["Path"])  # prints cell value for `Path` property 

Here is an complete example

ctx = ClientContext(site_url).with_credentials(user_credentials)
result = ctx.search.query("contentclass:STS_Site").execute_query()
results = result.value.PrimaryQueryResult.RelevantResults
for row in results.Table.Rows:
    print(row.Cells["Path"])  # prints site url

Changelog

• OneDrive enhancements in terms of Excel support

Create a new table example

from office365.graph_client import GraphClient
from office365.onedrive.workbooks.tables.rows.row import WorkbookTableRow

file_name = "Financial Sample.xlsx"
client = GraphClient(acquire_token)
workbook = client.me.drive.root.get_by_path(file_name).workbook
table = workbook.tables.add("A1:C10", True).execute_query()

List rows example

from office365.graph_client import GraphClient
from office365.onedrive.workbooks.tables.rows.row import WorkbookTableRow

file_name = "Financial Sample.xlsx"
client = GraphClient(acquire_token)
workbook = client.me.drive.root.get_by_path(file_name).workbook
table = workbook.worksheets["Sheet1"].tables["financials"].get().execute_query()
print(table.name)

# read table content
rows = table.rows.get().execute_query()
for r in rows:  # type: WorkbookTableRow
    print(r.values) 

Changelog

• #569: fix for ClientRuntimeContext.execute_query_retry method by @jneuendorf
• #584: escape password in _acquire_service_token_from_adfs-method by @chrisdecker1201
• #568: support for passing private_key into with_client_certificate method
• enhancements for SharePoint & OneDrive APIs

Enhancements for SharePoint & OneDrive APIs

Instantiate SharePoint client with certificate credentials

cert_path = 'selfsigncert.pem'
with open(cert_path, 'r') as f:
      private_key = open(cert_path).read()

cert_credentials = {
     'tenant': test_tenant,
     'client_id': '--client id--',
     'thumbprint': '--thumbprint--',
     'private_key': private_key
}
ctx = ClientContext(test_team_site_url).with_client_certificate(**cert_credentials)

Setting image field value

field_value = ImageFieldValue(image_url)
list_item.set_property(field_name, field_value).update().execute_query()

Changelog

Paged data retrieval enhancements, namely:

1. introduction of ClientObjectCollection.get_all method to retrieve all the items in a collection, regardless of the size, for example:

def print_progress(items):
    """
    :type items: office365.sharepoint.listitems.collection.ListItemCollection
    """
    print("Items read: {0}".format(len(items)))

page_size = 500
ctx = ClientContext(site_url).with_credentials(client_credentials)
large_list = ctx.web.lists.get_by_title(list_title)

all_items = target_list.items.get_all(page_size, print_progress).execute_query()

1. retrieving paged data via ClientObjectCollection.paged method

page_size = 500

ctx = ClientContext(site_url).with_credentials(client_credentials)
large_list = ctx.web.lists.get_by_title(list_title)
paged_items = large_list.items.paged(page_size, page_loaded=print_progress).get().execute_query()
    for index, item in enumerate(paged_items):  # type: int, ListItem
        print("{0}: {1}".format(index, item.id))

Bug fixes:

• #541: client certificate auth fails when non root site is provided
• #529: Python 2.7 compatibility fixes
• #527: fix for Folder.copy_to_using_path method

Changelog

Bug fixes:

• #524: determine and construct the list of properties (including navigation) to be retrieved of QueryOptions.build method, kudos to @jjloneman
• #505: improved file addressing in SharePoint API by @fan-e-cae
• better support for Sharing namespace in SharePoint API
• introduced support for Site Designs and Site Scripts in SharePoint API

Example: Share an anonymous access link with view permissions to a file

ctx = ClientContext(site_url).with_credentials(credentials)
file = ctx.web.get_file_by_server_relative_url(file_url)
result = target_file.share_link(SharingLinkKind.AnonymousView).execute_query()

Example: create a new site script that apply a custom theme

ctx = ClientContext(site_url).with_credentials(credentials)
site_script = {
    "$schema": "schema.json",
    "actions": [
        {
            "verb": "applyTheme",
            "themeName": "Contoso Theme"
        }
    ],
    "bindata": {},
    "version": 1
}

result = SiteScriptUtility.create_site_script(ctx, "Contoso theme script", "", site_script).execute_query()

Changelog

SharePoint API:

• ListItem.validate_update_list_item method: setting dates_in_utc as an optional parameter (#509)
• Search namespace enhancements #496

Example 1: submit search (KQL) query expression via SearchService.query method

ctx = ClientContext(site_url).with_credentials(credentials)
search = SearchService(ctx)
result = search.query("IsDocument:1").execute_query()

Example 2: construct sorting search results query and submit via SearchService.post_query method

ctx = ClientContext(site_url).with_credentials(credentials)
search = SearchService(ctx)
request = SearchRequest(query_text="IsDocument:1",
                        sort_list=[Sort("LastModifiedTime", 1)],
                        select_properties=["Path", "LastModifiedTime"],
                        row_limit=20)
result = search.post_query(request).execute_query()

Changelog

SharePoint API:

• ListItem introduced support for system metadata update (#330)
• SiteProperies.update method bug fix #480
• Web.ensure_folder_path method bug fix #452

Support for ListItem system update

Prefer ListItem.validate_update_list_item method which supports overriding system metadata, Here is an example which demonstrates how to update list item system metadata (namely Author and Modified field values):

ctx = ClientContext(site_url).with_credentials(credentials)

list_tasks = ctx.web.lists.get_by_title("Tasks")
items = list_tasks.items.get().top(1).execute_query()
if len(items) == 0:
    sys.exit("No items for update found")

item_to_update = items[0]  # type: ListItem
author = ctx.web.site_users.get_by_email(user_principal_name)

modified_date = datetime.utcnow() - timedelta(days=3)
result = item_to_update.validate_update_list_item({
    "Author": FieldUserValue.from_user(author),
    "Modified": modified_date
}).execute_query()

has_any_error = any([item.HasException for item in result.value])
if has_any_error:
    print("Item update completed with errors, for details refer 'ErrorMessage' property")
else:
    print("Item has been updated successfully")

Changelog

• #433: OneDrive API: support for downloading large files (via chunked download) by @juguerre

Example:

from office365.graph_client import GraphClient
from office365.onedrive.driveitems.driveItem import DriveItem


def print_download_progress(offset):
    print("Downloaded '{0}' bytes...".format(offset))


client = GraphClient(acquire_token_by_username_password)
# # 1. address file by path and get file metadata
file_item = client.me.drive.root.get_by_path("archive/big_buck_bunny.mp4").get().execute_query()  # type: DriveItem
# 2 download a large file (chunked file download)
with tempfile.TemporaryDirectory() as local_path:
    with open(os.path.join(local_path, file_item.name), 'wb') as local_file:
        file_item.download_session(local_file, print_download_progress).execute_query()
    print("File '{0}' has been downloaded into {1}".format(file_item.name, local_file.name))

• #430: improved support for overriding underlying HTTP request settings(such as proxy and SSL) by @juguerre

• #465: SharePoint API: allow passing scopes via certificate authentication method by @theodoriss

Example

from office365.sharepoint.client_context import ClientContext


cert_settings = {
    'client_id': '-- app id--',
    'thumbprint': "-- cert thumbprint--",
    'cert_path': 'mycert.pem'),
    'scopes': ['https://contoso.onmicrosoft.com/.default']
}

ctx = ClientContext(test_site_url).with_client_certificate(test_tenant, **cert_settings)
current_web = ctx.web.get().execute_query()
print("{0}".format(current_web.url))

• #461: include pytz to install dependency by @Zahlii

• Microsoft Graph API: Improved support for delta queries (official docs)

Example: get incremental changes for users

client = GraphClient(acquire_token_func)
changed_users = self.client.users.delta.get().execute_query()

Changelog

List of changes:

• #234: determines if security validation expired and refresh if expired for SharePoint client
• SharePoint API enhanced support for publishing & webhooks namespaces
• Planner API model has been updated
• Outlook API enhancements, namely the support for download MIME content of a message

SharePoint API: create a Site Page

The example demonstrates how to create a Site Page

ctx = ClientContext(team_site_url).with_credentials(client_credentials)
new_page = ctx.site_pages.pages.add()
new_page.save_draft(title="My news page")
new_page.publish().execute_query()

SharePoint API: create a new webhook

The example demonstrates how to create a webhook to SharePoint list:

ctx = ClientContext(site_url).with_credentials(client_credentials)
push_service_url = "https://westeurope0.pushnp.svc.ms/notifications?token=526a9d28-d4ec-45b7-81b9-4e1599524784"
target_list = client.web.lists.get_by_title("Documents")
subscription = target_list.subscriptions.add(push_service_url).execute_query()

where

push_service_url - your service endpoint URL. SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource

Refer Overview of SharePoint webhooks for a details.

Planner API: create a task (Create plannerTask endpoint)

from office365.graph_client import GraphClient

client = GraphClient(acquire_token_func)
plan = ensure_plan(client.me.planner, "My plan")
task = client.planner.tasks.add(title="New task", planId=plan.id).execute_query()

Outlook API: download MIME content of a message (Get MIME content of a message endpoint)

The example demonstrates how to download an Outlook message body in MIME format and save into a file:

client = GraphClient(acquire_token_func)
# requires Mail.ReadWrite permission
user = client.users[test_user_principal_name]
messages = user.messages.select(["id"]).top(10).get().execute_query()
with tempfile.TemporaryDirectory() as local_path:
    for message in messages:  # type: Message
        with open(os.path.join(local_path, message.id + ".eml"), 'wb') as local_file:
            message.download(local_file).execute_query()  # download MIME representation of a message

Changelog

Bug fixes

• #407 SecurableObject.get_user_effective_permissions de-serializing response bug fixed
• #400 improved support for managing file versions (SharePoint API)
• initial support for Reports API has been introduced
• initial support for Search API has been introduced

Examples

Example: how to download a file version

ctx = ClientContext(team_site_url).with_credentials(client_credentials)
version = ctx.web.get_file_by_server_relative_path(file_url).versions.get_by_id(512)
with open(download_path, "wb") as local_file:
    file = version.download(local_file).execute_query()

Documentation:

Example: how to determine what kind of permissions the user has on a file

Documentation: ListItem.GetUserEffectivePermissions method

from pprint import pprint

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.permissions.permission_kind import PermissionKind


client = ClientContext(team_site_url).with_credentials(user_credentials)
file_url = "/sites/team/Shared Documents/Guide.docx"

target_user = client.web.site_users.get_by_email(test_user_principal_name_alt)
target_file = client.web.get_file_by_server_relative_path(file_url)
result = target_file.listItemAllFields.get_user_effective_permissions(target_user).execute_query()
pprint(result.value.permission_levels)  # print all permission levels

# verify whether user has Reader role to a file
if result.value.has(PermissionKind.OpenItems):
    print("User has access to read a file")

Example: how to get the count of Microsoft 365 activations on desktops and devices (via Reports API)

Documentation: reportRoot: getOffice365ActivationsUserCounts

import msal
from office365.graph_client import GraphClient

def acquire_token_by_client_credentials():
    settings = load_settings()
    authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
    app = msal.ConfidentialClientApplication(
        authority=authority_url,
        client_id=client_id,
        client_credential=client_secret
    )
    return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

client = GraphClient(acquire_token_by_client_credentials)
result = client.reports.get_office365_activations_user_counts().execute_query()

Example: how to search files (via Search API)

Documentation: use the Microsoft Search API to search content in OneDrive and SharePoint

import msal
from office365.graph_client import GraphClient

def acquire_token_by_client_credentials():
    settings = load_settings()
    authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
    app = msal.ConfidentialClientApplication(
        authority=authority_url,
        client_id=client_id,
        client_credential=client_secret
    )
    return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

client = GraphClient(acquire_token_by_client_credentials)
result = client.search.query("Guide.docx", entity_types=["driveItem"]).execute_query()

Changelog

Bug fixes

• #402 and #387: removed invalid dependency to generator module @rikeshtailor
• #399: fix for downloading a file
• Web.get_folder_by_server_relative_path return type fix @sharifhsn

Improvements:

• error handling improvements (in terms of covering network exceptions along with invalid HTTP requests) @beliaev-maksim
• improvements for JSON Batching support, for both v3 and v4 versions

Changelog

General

• a preliminary support for communications API has been introduced
• optimizing PyPI package in terms of excluding packages from production (e.g. tests)

SharePoint API specific

• upload large files improvements in terms of optimizing of memory consumption (#377) @beliaev-maksim
• new examples for SharePoint section (#293) @beliaev-maksim
• Document Set improvements and bug fixes #379
• settings Taxonomy field values fixes #380

OneDrive API specific

• fixes for addressing drive items #374
• improvements in terms of supporting and new nav types and methods for better API coverage, for example:

Example 1: address folder by path, where archive/2018 is a folder path:

folder_item = client.me.drive.root.get_by_path("archive/2018").get().execute_query()  # type: DriveItem

Teams API specific

• improvements in terms of supporting and new nav types and methods for better API coverage

Examples: list all teams

client = GraphClient(acquire_token_by_client_credentials)
teams = client.teams.get_all(["displayName"]).execute_query()
for team in teams:  # type: Team
    print(team.display_name)

Changelog

• general: compatibility with Python 2.7 (related: #326 & #275)
• OneDrive API: improvements and fixes for addressing drive items #276
• Graph client: improvements in terms of error handling for batch request, dependencies updated: msal 1.12.0
• SharePoint API: fix for ListItem.update method (related #365)
• SharePoint API: better support for addressing resources by resource path
• SharePoint API: batch request improvements, i.e. support for specifying maximum of items to be executed per bulk operations, default is 100 (related: #349)

Changelog

• SharePoint API: improved support for a file and folders addressing details

• SharePoint API: support for saving taxonomy columns #353

Example: save a single-valued taxonomy field value

ctx = ClientContext(site_url).with_credentials(credentials)

tasks_list = ctx.web.lists.get_by_title("Tasks")
tax_field_value = TaxonomyFieldValue("{term-label}", "{term-guid}")
item_to_create = tasks_list.add_item({
    "Title": "New task",
    "{tex-column-name}": tax_field_value,
}).execute_query()

Example: save a multi-valued taxonomy field value

ctx = ClientContext(site_url).with_credentials(credentials)

tasks_list = ctx.web.lists.get_by_title("Tasks")
tax_field_value = TaxonomyFieldValue("{term-label}", "{term-guid}")
tax_field_values = TaxonomyFieldValueCollection([tax_field_value])
item_to_create = tasks_list.add_item({
    "Title": "New task",
    "{tex-column-name}": tax_field_values,
}).execute_query()

Changelog

• #339: Introduced browser mode to imitate browser when obtaining the authentication cookies by @nsmcan
• API improvements for Fluent interface
• SharePoint Batching API improvements for error handling

Changelog

• #320: escape XML characters in STS request by @andreas-j-hauser
• #310: Revert ClientObject.get_property() semantics by @kraptor
• SharePoint API improvements: #303 (addressing versions of ListItem), hubsite namespace, File/Folder copy/move operations
• Graph client: initial support for batching
• improved support for Calendar API

Support for batching for Graph client

def acquire_token_client_credentials():

    authority_url = 'https://login.microsoftonline.com/{tenant}'
    app = msal.ConfidentialClientApplication(
        authority=authority_url,
        client_id='{client-id}',
        client_credential='{client-secret}'
    )
    result = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
    return result

client = GraphClient(acquire_token_client_credentials)

current_user = self.client.users['{user-principal-name}'].get()  # 1.1: construct query to retrieve user details
my_drive = self.client.users['{user-principal-name}'].drive.get()  # 1.2: construct query to retrieve user's drive
client.execute_batch()  # 2: submit a query to the server

Changelog

Summary:

• improved support for SharePoint API (fields, tenants namespaces)
• bug fixes: #303 , #302 and #265

Improved support for SharePoint API

Here are a few examples which demonstrate how to create field and set values for a different field types:

Create a multi lookup field:

lookup_field = list.fields.add_lookup_field(title=lookup_field_name,
                                                                lookup_list_id=lookup_list.properties['Id'],
                                                                lookup_field_name='Title',
                                                                allow_multiple_values=True).execute_query()

Set a multi lookup field value

field_value = FieldMultiLookupValue()
field_value.add(FieldLookupValue(lookup_id))
updated = item_to_update.set_property(lookup_field_name, field_value).update().execute_query()

The list of methods (fields namespace):

• FieldCollection.add_url_field(title)
• FieldCollection.add_lookup_field(title, lookup_list_id, lookup_field_name, allow_multiple_values)
• FieldCollection.add_choice_field(title, values, multiple_values)
• FieldCollection.create_taxonomy_field(name, ssp_id, term_set_id, anchor_id,field_id, text_field_id, web_id, list_id)

The list of methods (tenant namespace):

• Tenant.get_site_health_status(site_url)

Changelog

• requests_ntlm is included as an optional dependency
• README.md broken links resolved

Changelog

• improvements for SAML-based claims authentication, kudos to @wreiner for the implementation and @nsmcan for the proposal #297, #272
• support for # and % in SharePoint Online and OneDrive for Business by @kraptor #300
• support for optional arguments for FileCollection.create_upload_session method by @beliaev-maksim #289
• migration from adal library to msal as a mandatory dependency #296
• improved support for sharepoint namespace, new types and methods (Tenant, ViewField, ContentType classes)
• migration from Outlook API v1.0 to Microsoft Graph. Note: OutlookClient is decommissioned and no longer available

Changelog

• Migration from Azure Active Directory Authentication Library (ADAL) to use the Microsoft Authentication Library (MSAL) library as a mandatory dependency
• Bug fixes: #278 - escape special characters in xml
• SharePoint API: support for creating fields from schema xml, methods: FieldCollection.create_field_as_xml, FieldCollection.create_taxonomy_field

Changelog

• Improved support for SharePoint API Batch requests

Here is the comparison of two approaches, in the first example update operation is submitted to server per every list item, while in the second one multiple list item update operations are submitted via a since (batch) request:

list_tasks = ctx.web.lists.get_by_title("Tasks")
items = list_tasks.items.get().execute_query() #  
for task_id, item in enumerate(items):
    task_prefix = str(randint(0, 10000))
    item.set_property("Title", f"Task {task_prefix}")
    item.update()
    ctx.execute_query()  #  <- update operation is submitted to server per every  list item

list_tasks = ctx.web.lists.get_by_title("Tasks")
items = list_tasks.items.get().execute_query()   
for task_id, item in enumerate(items):
    task_prefix = str(randint(0, 10000))
    item.set_property("Title", f"Task {task_prefix}")
    item.update()
ctx.execute_batch()   # <- construct a single (batch) for all list items and submit to server

• API improvements for Fluent interface, for example, instead:

   list = client.web.lists.get_by_title(list_title)
   list.delete_object()
   client.execute_query()

list delete operation could be constructed and submitted to a server in a more compact manner:

   client.web.lists.get_by_title(list_title).delete_object().execute_query()

• SharePoint API Changes namespace improvements (#259), here is the list of operations:

  • Site.get_changes
  • Web.get_changes
  • List.get_changes
  • ListItem.get_changes

• SharePoint API RecycleBin entity class and operations

Changelog

Finally the initial support for SharePoint API Batch requests has been introduced. All insert/update/delete operations are supported.

The following example how current user and web objects could be retrieved by grouping two operations and submitting it as a single request to the server:

client = ClientContext(site_url).with_credentials(user_credentials)
current_user = client.web.currentUser
client.load(current_user)
current_web = client.web
client.load(current_web)
client.execute_batch()

which offers a new way of improving the performance.

Among another improvements and changes:

• improved support for Office365 auth with ADFS by @liuliqiu

• style enforcement (flake8), code formatting (isort) configuration by @domdinicola

• ClientRuntimeContext.execute_query_retry method which implements Retry pattern

The list of changes

API support for Fluent interface

ctx = ClientContext(settings['url']).with_credentials(credentials)

target_web = ctx.web.load().execute_query()  #method chaining
print(target_web.url)

Support for addressing Web and File resources by absolute Url

abs_file_url = "https://{tenant}.sharepoint.com/sites/team/Shared Documents/sample.docx".format(tenant=tenant)
user_credentials = UserCredential(username, password)

with open(local_path, 'wb') as local_file:
    file = File.from_url(abs_file_url).with_credentials(user_credentials).download(local_file).execute_query()
print("'{0}' file has been downloaded".format(file.serverRelativeUrl))

Support for SharePoint Search API

According to Documentation

Search in SharePoint includes a Search REST service you can use to add search functionality to your client and mobile applications by using any technology that supports REST web requests.

Example

The following example demonstrates how to construct a search for a documents (via Keyword Query Language syntax) and print file url (Path managed property)

from office365.runtime.auth.userCredential import UserCredential
from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.search.searchRequest import SearchRequest
from office365.sharepoint.search.searchService import SearchService
from settings import settings


ctx = ClientContext.connect_with_credentials(site_url,
                                             UserCredential(username, password))

search = SearchService(ctx)
request = SearchRequest("IsDocument:1")
result = search.post_query(request)
ctx.execute_query()
relevant_results = result.PrimaryQueryResult.RelevantResults
for i in relevant_results['Table']['Rows']:
    cells = relevant_results['Table']['Rows'][i]['Cells']
    print(cells[6]['Value'])

Support for SharePoint TenantAdministration namespace

The following example demonstrates how to create a site collection via Tenant.CreateSite method:

admin_site_url = "https://{0}-admin.sharepoint.com/".format(tenant)
credentials = UserCredential(username, password)
client = ClientContext(admin_site_url).with_credentials(credentials)
tenant = Tenant(client)

props = SiteCreationProperties(target_site_url, user_principal_name)
site_props = tenant.ensure_site(props)
client.execute_query()

Improved support for SharePoint fields namespace

Creating list item and setting multi lookup field value:

create_info = {
            "Title": "New task"
        }
multi_lookup_value = FieldMultiLookupValue()
multi_lookup_value.add(FieldLookupValue(lookup_id))
new_item = self.target_list.add_item(create_info)
new_item.set_property("Predecessors", multi_lookup_value)
client.load(items)
client.execute_query()

Updating list item with multi choice field value:

multi_choice_value = FieldMultiChoiceValue(["In Progress"])
item_to_update.set_property("TaskStatuses", multi_choice_value)
item_to_update.update()
client.execute_query()

Bug fixes

• #210: connect to Office 365 with federated accounts, credit goes to @liuliqiu

• #206: SharePoint Session API upload

The list of changes

• initial support for Microsoft Teams API
• improved support for working with paged data
• introduced support for certificate authentication for SharePoint API
• improvements and model updates for SharePoint and OneDrive APIs

and more

Initial support for [Microsoft Teams API

The support for Microsoft Teams API has been introduced, the following example demonstrates how how create a new team under a group which corresponds to Create team endpoint

tenant_name = "contoso.onmicrosoft.com"
client = GraphClient(tenant_name, get_token)
new_team = client.groups[group_id].add_team()
client.execute_query()

where

def get_token(auth_ctx):
    """Acquire token via client credential flow (ADAL Python library is utilized)
    :type auth_ctx: adal.AuthenticationContext
    """
    token = auth_ctx.acquire_token_with_client_credentials(
        "https://graph.microsoft.com",
        client_id,
        client_secret)
    return token

Improved support for working with paged data

Here is an example which demonstrates how to retrieve data from a SharePoint list which contains more then 5k items:

def print_progress(items_read):
    print("Items read: {0}".format(items_read))


ctx = ClientContext.connect_with_credentials(site_url,
                                             ClientCredential(client_id,client_secret))

list_source = ctx.web.lists.get_by_title("Contacts_Large")
items = list_source.items
items.page_loaded += print_progress  # page load event
items.page_size = 400  # specify custom page size (default is 100)
ctx.load(items)
ctx.execute_query()

#print("Items count: {0}".format(len(items)))
for item in items:
    print("{0}".format(item.properties['Title']))

Support for certificate authentication for SharePoint API

The example demonstrates how to connect to SharePoint Online with certificate credentials:

ctx = ClientContext.connect_with_certificate(site_url,
                                             client_id,
                                             thumbprint,
                                             certificate_path)

current_web = ctx.web
ctx.load(current_web)
ctx.execute_query()
print("{0}".format(current_web.url))

Refer how-to page for a more details

Improvements and model updates for SharePoint and OneDrive APIs

In terms of file and folder operations the following methods have been introduced:

• File.download(file_object) - download a file content into a file object (SharePoint API)
• Folder.copyto(new_folder_url, overwrite) - copy a folder (SharePoint API)
• Folder.moveto(new_folder_url, flags) move a folder (SharePoint API)
• DriveItem.download(file_object) - downloads a file content into a file object (OneDrive API)
• DriveItem.get_content() - downloads a file content (OneDrive API)

Support for simplified methods to authenticate against SharePoint

Now for user credentials flow, instead of

ctx_auth = AuthenticationContext(url=site_url)
ctx_auth.acquire_token_for_user(username,password):
ctx = ClientContext(site_url, ctx_auth)

an authenticated client could be initialized like this:

ctx = ClientContext.connect_with_credentials(site_url, UserCredential(username,password))

and for client credentials flow (aka SharePoint App-Only) instead of

ctx_auth = AuthenticationContext(url=site_url)
ctx_auth.acquire_token_for_app(client_id,client_secret):
ctx = ClientContext(site_url, ctx_auth)

like this:

ctx = ClientContext.connect_with_credentials(site_url, ClientCredential(client_id,client_secret))

Introduced support for provision modern Team & Communication sites (#179)

• GroupSiteManager.create_group_ex - create a Team site

• SPSiteManager.create - create a Communication site

Examples

Create a Team Site

client = ClientContext.connect_with_credentials(url,ClientCredential(client_id,client_secret))
site_manager = GroupSiteManager(client)
info = site_manager.create_group_ex("Team Site", "teamsite", True, None)
client.execute_query()

Create a Communication site

client = ClientContext.connect_with_credentials(url,ClientCredential(client_id,client_secret))
site_manager = SPSiteManager(client)
request = SPSiteCreationRequest("CommSite", "https://contoso.sharepoint.com/sites/commsite")
response = site_manager.create(request)
client.execute_query()

Bug fixes and feature requests

• #174 and #28 - a bug which prevented to authenticate successfully with user credentials on not root site collections or a sub sites
• #181 - missing types
• #178 - introduced support for provision modern Team & Communication sites

Release changes:

• GraphClient client has been introduced for working with Microsoft Graph endpoint
• CAML query builder has been introduced (credit goes to @domdinicola)

• introduced support for Introduced support for SharePoint 2010 list data service, ListDataService class

• added methods and properties for List, ListItem and Field resources:

  • ListItem.validate_update_listItem method - Validates and sets the values of the specified collection of fields for the list item.
  • ListItem.system_update method
  • ListItem.update_overwrite_version method
  • ListItem.parent_list navigation property
  • List.fields navigation property
  • FieldCollection.add method
  • FieldCollection.get_by_id method
  • FieldCollection.get_by_internal_name_or_title method
  • FieldCollection.get_by_title method
  • Field.update method
  • Field.delete method

• Added support for NTLM authentication #110

• Switch context per web #111

All the credit goes to @Aisbergg for those changes!

• Outlook client transitioned from Office 365 Outlook REST API to Microsoft Graph-based Outlook REST API

• introduced support for for Resource Owner Password Credential (ROPC) flow, which is suitable for scenarios where BasicAuth (discontinued nowadays) was utilized before

Introduced support for SharePoint authentication via OAuth (app principal) and SharePoint CAML queries