Office365-REST-Python-Client 2.4.2__py3-none-any.whl → 2.4.4__py3-none-any.whl

office365/runtime/auth/authentication_context.py

@@ -1,27 +1,33 @@
+import json
+import sys
+
 from office365.runtime.auth.client_credential import ClientCredential
 from office365.runtime.auth.providers.acs_token_provider import ACSTokenProvider
-from office365.runtime.auth.providers.oauth_token_provider import OAuthTokenProvider
 from office365.runtime.auth.providers.saml_token_provider import SamlTokenProvider
 from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.auth.user_credential import UserCredential
 from office365.runtime.compat import get_absolute_url
 
 
+def _get_authorization_header(token):
+    return '{token_type} {access_token}'.format(token_type=token.tokenType, access_token=token.accessToken)
+
+
 class AuthenticationContext(object):
+    """Authentication context for SharePoint Online/OneDrive For Business"""
 
     def __init__(self, url):
         """
-        Authentication context for SharePoint Online/OneDrive For Business
-
-        :param str url:  Absolute Web or Site Url
+        :param str url: SharePoint absolute web or site Url
         """
         self.url = url.rstrip("/")
-        self._provider = None
+        self._authenticate = None
+        self._cached_token = None
 
     def with_client_certificate(self, tenant, client_id, thumbprint, cert_path=None, private_key=None, scopes=None):
-        """Creates authenticated SharePoint context via certificate credentials
+        """Initializes a client to acquire a token via certificate credentials
 
-        :param str tenant: Tenant name, for example {}@
+        :param str tenant: Tenant name, for example: contoso.onmicrosoft.com
         :param str client_id: The OAuth client id of the calling application.
         :param str thumbprint: Hex encoded thumbprint of the certificate.
         :param str or None cert_path: Path to A PEM encoded certificate private key.
@@ -37,7 +43,7 @@ class AuthenticationContext(object):
             with open(cert_path, 'r') as f:
                 private_key = f.read()
 
-        def _acquire_token_for_client_certificate():
+        def _acquire_token():
             authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
             credentials = {"thumbprint": thumbprint, "private_key": private_key}
             import msal
@@ -49,49 +55,141 @@ class AuthenticationContext(object):
             result = app.acquire_token_for_client(scopes)
             return TokenResponse.from_json(result)
 
-        self.with_access_token(_acquire_token_for_client_certificate)
+        self.with_access_token(_acquire_token)
+        return self
+
+    def with_interactive(self, tenant, client_id, scopes=None):
+        """
+        Initializes a client to acquire a token interactively i.e. via a local browser.
+
+        Prerequisite: In Azure Portal, configure the Redirect URI of your
+        "Mobile and Desktop application" as ``http://localhost``.
+
+        :param str tenant: Tenant name, for example: contoso.onmicrosoft.com
+        :param str client_id: The OAuth client id of the calling application.
+        :param list[str] or None scopes:  Scopes requested to access a protected API (a resource)
+        """
+        if scopes is None:
+            resource = get_absolute_url(self.url)
+            scopes = ["{url}/.default".format(url=resource)]
+
+        def _acquire_token():
+            import msal
+            app = msal.PublicClientApplication(
+                client_id,
+                authority='https://login.microsoftonline.com/{0}'.format(tenant),
+                client_credential=None
+            )
+            result = app.acquire_token_interactive(scopes=scopes)
+            return TokenResponse.from_json(result)
+        self.with_access_token(_acquire_token)
+        return self
+
+    def with_device_flow(self, tenant, client_id, scopes=None):
+        """
+        Obtain token by a device flow object, with customizable polling effect.
+
+        :param str tenant: Tenant name, for example: contoso.onmicrosoft.com
+        :param str client_id: The OAuth client id of the calling application.
+        :param list[str] or None scopes:  Scopes requested to access a protected API (a resource)
+        """
+        if scopes is None:
+            resource = get_absolute_url(self.url)
+            scopes = ["{url}/.default".format(url=resource)]
+
+        def _acquire_token():
+            import msal
+            app = msal.PublicClientApplication(
+                client_id,
+                authority='https://login.microsoftonline.com/{0}'.format(tenant),
+                client_credential=None
+            )
+
+            flow = app.initiate_device_flow(scopes=scopes)
+            if "user_code" not in flow:
+                raise ValueError(
+                    "Failed to create device flow: %s" % json.dumps(flow, indent=4))
+
+            print(flow["message"])
+            sys.stdout.flush()
+
+            result = app.acquire_token_by_device_flow(flow)
+            return TokenResponse.from_json(result)
+        self.with_access_token(_acquire_token)
         return self
 
     def with_access_token(self, token_func):
-        self._provider = OAuthTokenProvider(token_func)
+        """
+        Initializes a client to acquire a token from a callback
+
+        :param () -> dict token_func: A callback
+        """
+        def _authenticate(request):
+            if self._cached_token is None:
+                self._cached_token = token_func()
+            request.set_header('Authorization', _get_authorization_header(self._cached_token))
+        self._authenticate = _authenticate
 
     def with_credentials(self, credentials, **kwargs):
+        """
+        Initializes a client to acquire a token via user or client credentials
+
+        :param UserCredential or ClientCredential credentials:
+        """
         if isinstance(credentials, ClientCredential):
-            self._provider = ACSTokenProvider(self.url, credentials.clientId, credentials.clientSecret)
+            provider = ACSTokenProvider(self.url, credentials.clientId, credentials.clientSecret)
         elif isinstance(credentials, UserCredential):
             allow_ntlm = kwargs.get('allow_ntlm', False)
             if allow_ntlm:
                 from office365.runtime.auth.providers.ntlm_provider import NtlmProvider
-                self._provider = NtlmProvider(credentials.userName, credentials.password)
+                provider = NtlmProvider(credentials.userName, credentials.password)
             else:
                 browser_mode = kwargs.get('browser_mode', False)
-                self._provider = SamlTokenProvider(self.url, credentials.userName, credentials.password, browser_mode)
+                provider = SamlTokenProvider(self.url, credentials.userName, credentials.password, browser_mode)
         else:
             raise ValueError("Unknown credential type")
 
+        def _authenticate(request):
+            provider.authenticate_request(request)
+        self._authenticate = _authenticate
+
     def acquire_token_for_user(self, username, password, browser_mode=False):
-        """Acquire token via user credentials
+        """
+        Initializes a client to acquire a token via user credentials
         Status: deprecated!
 
-        :type password: str
-        :type username: str
-        :type browser_mode: str
+        :param str password: The user password
+        :param str username: Typically a UPN in the form of an email address
+        :param bool browser_mode:
         """
-        self._provider = SamlTokenProvider(url=self.url, username=username, password=password,
-                                           browser_mode=browser_mode)
-        return self._provider.ensure_authentication_cookie()
+        provider = SamlTokenProvider(self.url, username, password, browser_mode)
+
+        def _authenticate(request):
+            provider.authenticate_request(request)
+        self._authenticate = _authenticate
+        return self
 
     def acquire_token_for_app(self, client_id, client_secret):
-        """Acquire token via client credentials (SharePoint App Principal)
+        """
+        Initializes a client to acquire a token via client credentials (SharePoint App-Only)
+
         Status: deprecated!
+
+        :param str client_id: The OAuth client id of the calling application.
+        :param str client_secret: Secret string that the application uses to prove its identity when requesting a token
         """
-        self._provider = ACSTokenProvider(url=self.url, client_id=client_id, client_secret=client_secret)
-        return self._provider.ensure_app_only_access_token()
+        provider = ACSTokenProvider(self.url, client_id, client_secret)
+
+        def _authenticate(request):
+            provider.authenticate_request(request)
+        self._authenticate = _authenticate
+        return self
 
     def authenticate_request(self, request):
         """
         Authenticate request
-
         :type request: office365.runtime.http.request_options.RequestOptions
         """
-        self._provider.authenticate_request(request)
+        if self._authenticate is None:
+            raise ValueError("Authentication credentials are missing or invalid")
+        self._authenticate(request)

office365/runtime/auth/client_credential.py

@@ -4,8 +4,8 @@ class ClientCredential(object):
         """
         Client credentials
 
-        :type client_secret: str
-        :type client_id: str
+        :param str client_secret:
+        :param str client_id:
         """
         self.clientId = client_id
         self.clientSecret = client_secret

office365/runtime/auth/providers/acs_token_provider.py

@@ -12,9 +12,9 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         """
         Provider to acquire the access token from a Microsoft Azure Access Control Service (ACS)
 
-        :type client_id: str
-        :type client_secret: str
-        :type url: str
+        :param str client_id: The OAuth client id of the calling application.
+        :param str client_secret: Secret string that the application uses to prove its identity when requesting a token
+        :param str url: SharePoint web or site url
         """
         self.url = url
         self.redirect_url = None
@@ -37,6 +37,9 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         return self._cached_token and self._cached_token.is_valid
 
     def get_app_only_access_token(self):
+        """
+        Retrieves an app-only access token from ACS
+        """
         try:
             realm = self._get_realm_from_target_url()
             url_info = urlparse(self.url)

office365/runtime/auth/providers/saml_token_provider.py

@@ -30,18 +30,22 @@ def xml_escape(s_val):
 
 
 def is_valid_auth_cookies(values):
+    """
+    Validates authorization cookies
+    """
     return any(values) and (values.get('FedAuth', None) is not None or values.get('SPOIDCRL', None) is not None)
 
 
 class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
 
     def __init__(self, url, username, password, browser_mode):
-        """SAML Security Token Service provider
+        """
+        SAML Security Token Service provider (claims-based authentication)
 
-        :type url: str
-        :type username: str
-        :type password: str
-        :type browser_mode: str
+        :param str url: Site or Web absolute url
+        :param str username: Typically a UPN in the form of an email address
+        :param str password: The password
+        :param bool browser_mode:
         """
         # Security Token Service info
         self._sts_profile = STSProfile(resolve_base_url(url))
@@ -70,8 +74,7 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
 
     def authenticate_request(self, request):
         """
-
-        :param request:
+        Authenticate request handler
         """
         logger = self.logger(self.authenticate_request.__name__)
         self.ensure_authentication_cookie()

office365/runtime/auth/token_response.py

@@ -1,8 +1,8 @@
 class TokenResponse(object):
 
-    def __init__(self, accessToken=None, tokenType=None, **kwargs):
-        self.accessToken = accessToken
-        self.tokenType = tokenType
+    def __init__(self, access_token=None, token_type=None, **kwargs):
+        self.accessToken = access_token
+        self.tokenType = token_type
         for key, value in kwargs.items():
             setattr(self, key, value)
 

office365/runtime/client_object_collection.py

@@ -206,8 +206,11 @@ class ClientObjectCollection(ClientObject):
         self.context.load(self, before_loaded=_construct_next_query, after_loaded=after_loaded)
         return self
 
-    def first(self):
-        """Return the first Entity instance that matches current query"""
+    def first(self, expression):
+        """Return the first Entity instance that matches current query
+
+        :param str expression: Filter expression
+        """
         return_type = self.create_typed_object()
         self.add_child(return_type)
         key = return_type.property_ref_name
@@ -221,13 +224,15 @@ class ClientObjectCollection(ClientObject):
                 raise ValueError(message)
             return_type.set_property(key, col[0].get_property(key))
 
-        self.top(1)
+        self.filter(expression).top(1)
         self.context.load(self, [key], after_loaded=_after_loaded)
         return return_type
 
-    def single(self):
+    def single(self, expression):
         """
         Return only one resulting Entity
+
+        :param str expression: Filter expression
         """
         return_type = self.create_typed_object()
         self.add_child(return_type)
@@ -238,14 +243,14 @@ class ClientObjectCollection(ClientObject):
             :type col: ClientObjectCollection
             """
             if len(col) == 0:
-                message = "Not found for filter: {0}".format(self.query_options.filter)
+                message = "Not found for filter: {0}".format(expression)
                 raise ValueError(message)
             elif len(col) > 1:
-                message = "Ambiguous match found for filter: {0}".format(self.query_options.filter)
+                message = "Ambiguous match found for filter: {0}".format(expression)
                 raise ValueError(message)
             return_type.set_property(key, col[0].get_property(key), False)
 
-        self.top(2)
+        self.filter(expression).top(2)
         self.context.load(self, after_loaded=_after_loaded)
         return return_type
 

office365/runtime/client_result.py

@@ -19,9 +19,18 @@ class ClientResult(object):
         self._context = context
         self._value = copy.deepcopy(default_value)
 
+    def before_execute(self, action, *args, **kwargs):
+        """
+        Attach an event handler which is triggered before query is submitted to server
+        :param (office365.runtime.http.request_options.RequestOptions) -> None action: Event handler
+        """
+        self._context.before_query_execute(action, *args, **kwargs)
+        return self
+
     def after_execute(self, action, *args, **kwargs):
         """
         Attach an event handler which is triggered after query is submitted to server
+        :param (ClientResult) -> None action: Event handler
         """
         self._context.after_query_execute(action, self, *args, **kwargs)
         return self

office365/runtime/client_runtime_context.py

@@ -92,28 +92,25 @@ class ClientRuntimeContext(object):
             self.after_query_execute(after_loaded, client_object)
         return self
 
-    def before_query_execute(self, action, query=None, *args, **kwargs):
+    def before_query_execute(self, action, once=True, *args, **kwargs):
         """
         Attach an event handler which is triggered before query is submitted to server
 
         :type action: (office365.runtime.http.request_options.RequestOptions, *args, **kwargs) -> None
-        :type query: office365.runtime.queries.client_query.ClientQuery or None
+        :param bool once: Flag which determines whether action is executed once or multiple times
         """
 
-        if query is None:
-            query = self._queries[-1]
+        query = self._queries[-1]
 
         def _prepare_request(request):
             """
             :type request: office365.runtime.http.request_options.RequestOptions
             """
-            if query.id == self.current_query.id:
-                print(query.url)
 
             if self.current_query.id == query.id:
+                if once:
+                    self.pending_request().beforeExecute -= _prepare_request
                 action(request, *args, **kwargs)
-            else:
-                self.pending_request().beforeExecute -= _prepare_request
 
         self.pending_request().beforeExecute += _prepare_request
         return self
@@ -152,6 +149,11 @@ class ClientRuntimeContext(object):
                 action(*args, **kwargs)
 
         self.pending_request().afterExecute += _process_response
+
+        execute_first = kwargs.pop("execute_first", False)
+        if execute_first and len(self._queries) > 1:
+            self._queries.insert(0, self._queries.pop())
+
         return self
 
     def after_execute(self, action, once=True, *args, **kwargs):

office365/runtime/http/request_options.py

@@ -6,8 +6,9 @@ class RequestOptions(object):
 
     def __init__(self, url):
         """
+        Request options
 
-        :type url: str
+        :param str url: URL for the new :class:`requests.Request` object
         """
         self.url = url
         self.data = None

office365/runtime/odata/request.py

@@ -27,7 +27,7 @@ class ODataRequest(ClientRequest):
         self.beforeExecute += self._ensure_json_format
 
     @property
-    def default_json_format(self):
+    def json_format(self):
         return self._default_json_format
 
     def build_request(self, query):
@@ -51,7 +51,7 @@ class ODataRequest(ClientRequest):
         :type response: requests.Response
         :type query: office365.runtime.queries.client_query.ClientQuery
         """
-        json_format = copy.deepcopy(self.default_json_format)
+        json_format = copy.deepcopy(self.json_format)
         return_type = query.return_type
         if return_type is None:
             return
@@ -76,7 +76,7 @@ class ODataRequest(ClientRequest):
         :type json_format: office365.runtime.odata.json_format.ODataJsonFormat
         """
         if json_format is None:
-            json_format = self.default_json_format
+            json_format = self.json_format
 
         if json and return_type is not None:
             for k, v in self._next_property(json, json_format):
@@ -143,6 +143,6 @@ class ODataRequest(ClientRequest):
         """
         :type request: RequestOptions
         """
-        media_type = self.default_json_format.media_type
+        media_type = self.json_format.media_type
         request.ensure_header('Content-Type', media_type)
         request.ensure_header('Accept', media_type)

office365/runtime/paths/appid.py

@@ -2,7 +2,8 @@ from office365.runtime.paths.resource_path import ResourcePath
 
 
 class AppIdPath(ResourcePath):
-    """Path for addressing a Service Principal"""
+    """Path for addressing a Service Principal or Application by appId where
+    appId is referred to as Application (client) ID on the Azure portal"""
 
     @property
     def segment(self):

office365/runtime/paths/entity.py

@@ -19,9 +19,9 @@ class EntityPath(ResourcePath):
     def segment(self):
         return str(self.key or '<key>')
 
-    def normalize(self, key, inplace=False):
+    def patch(self, key, inplace=False):
         """
-        Normalizes entity path
+        Patches path
 
         :type key: str or None
         :type inplace: bool

office365/{sharepoint/internal/paths/entity.py → runtime/paths/key.py}

@@ -1,12 +1,14 @@
 from office365.runtime.paths.resource_path import ResourcePath
 
 
-class EntityPath(ResourcePath):
-    """Path for addressing a single SharePoint entity"""
+class KeyPath(ResourcePath):
+    """Path for addressing a single entity by key"""
 
     @property
     def segment(self):
-        if isinstance(self.key, int):
+        if self.key is None:
+            return "(<key>)"
+        elif isinstance(self.key, int):
             return "({0})".format(self.key)
         return "('{0}')".format(self.key)
 

office365/runtime/paths/resource_path.py

@@ -9,6 +9,9 @@ class ResourcePath(object):
         self._key = key
         self._parent = parent
 
+    def patch(self, key, inplace=False):
+        return self
+
     def __iter__(self):
         current = self
         while current:

office365/runtime/types/event_handler.py

@@ -3,6 +3,12 @@ class EventHandler:
         self._listeners = []
         self._once = once
 
+    def __contains__(self, e):
+        return e in self._listeners
+
+    def __iter__(self):
+        return iter(self._listeners)
+
     def __iadd__(self, listener):
         self._listeners.append(listener)
         return self

office365/search/external/configuration.py

@@ -0,0 +1,8 @@
+from office365.runtime.client_value import ClientValue
+
+
+class Configuration(ClientValue):
+    """
+    Specifies additional application IDs that are allowed to manage the externalConnection and
+    to index content in a externalConnection.
+    """

office365/search/external/connection.py

@@ -0,0 +1,27 @@
+from office365.entity import Entity
+from office365.search.external.configuration import Configuration
+from office365.search.external.search_settings import SearchSettings
+
+
+class ExternalConnection(Entity):
+    """A logical container to add content from an external source into Microsoft Graph."""
+
+    @property
+    def configuration(self):
+        """
+        Specifies additional application IDs that are allowed to manage the connection and to index
+        content in the connection. Optional.
+        """
+        return self.properties.get("configuration", Configuration())
+
+    @property
+    def search_settings(self):
+        """
+        The settings configuring the search experience for content in this connection,
+        such as the display templates for search results.
+        """
+        return self.properties.get("searchSettings", SearchSettings())
+
+    @property
+    def entity_type_name(self):
+        return "microsoft.graph.externalConnectors.externalConnection"

office365/{external → search/external}/external.py

@@ -1,6 +1,6 @@
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
-from office365.external.connection import ExternalConnection
+from office365.search.external.connection import ExternalConnection
 from office365.runtime.paths.resource_path import ResourcePath
 
 

office365/search/external/search_settings.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class SearchSettings(ClientValue):
+    """Collects all configurable settings related to search over connector content."""

office365/search/query.py

@@ -3,11 +3,13 @@ from office365.runtime.client_value import ClientValue
 
 class SearchQuery(ClientValue):
 
-    def __init__(self, query_string=None):
+    def __init__(self, query_string=None, query_template=None):
         """
         Represents a search query that contains search terms and optional filters.
 
         :param str query_string: The search query containing the search terms.
+        :param str query_template: Provides a way to decorate the query string. Supports both KQL and query variables.
         """
         super(SearchQuery, self).__init__()
         self.queryString = query_string
+        self.queryTemplate = query_template

office365/search/request.py

@@ -1,6 +1,7 @@
 from office365.runtime.client_value import ClientValue
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.types.collections import StringCollection
+from office365.search.sharepoint_onedrive_options import SharePointOneDriveOptions
 from office365.search.sort_property import SortProperty
 
 
@@ -8,7 +9,7 @@ class SearchRequest(ClientValue):
     """A search request formatted in a JSON blob."""
 
     def __init__(self, query, entity_types=None, fields=None, search_from=None, sort_properties=None,
-                 content_sources=None):
+                 content_sources=None, sharepoint_onedrive_options=SharePointOneDriveOptions()):
         """
         :param office365.search.query.SearchQuery query: Contains the query terms.
         :param list[str] entity_types: One or more types of resources expected in the response.
@@ -33,4 +34,5 @@ class SearchRequest(ClientValue):
         self.search_from = search_from
         self.sortProperties = ClientValueCollection(SortProperty, sort_properties)
         self.contentSources = StringCollection(content_sources)
+        self.sharePointOneDriveOptions = sharepoint_onedrive_options
 

office365/search/sharepoint_onedrive_options.py

@@ -3,3 +3,6 @@ from office365.runtime.client_value import ClientValue
 
 class SharePointOneDriveOptions(ClientValue):
     """Provides the search content options when a search is performed using application permissions"""
+
+    def __init__(self, search_content=None):
+        self.searchContent = search_content

office365/search/sort_property.py

@@ -3,3 +3,12 @@ from office365.runtime.client_value import ClientValue
 
 class SortProperty(ClientValue):
     """Indicates the order to sort search results."""
+
+    def __init__(self, is_descending=None, name=None):
+        """
+        :param bool is_descending: True if the sort order is descending. Default is false,
+             with the sort order as ascending. Optional.
+        :param str name: The name of the property to sort on. Required.
+        """
+        self.isDescending = is_descending
+        self.name = name

office365/sharepoint/activities/client_request.py

@@ -2,4 +2,7 @@ from office365.runtime.client_value import ClientValue
 
 
 class ActivityClientRequest(ClientValue):
-    pass
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.SharePoint.Activities.ActivityClientRequest"