Office365 REST Python Client Versions Save

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()

2. 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")