Office365-REST-Python-Client

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

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