Office365-REST-Python-Client 2.5.10__py3-none-any.whl → 2.5.12__py3-none-any.whl

office365/directory/identitygovernance/appconsent/request.py

@@ -1,7 +1,13 @@
+from typing import Optional
+
+from office365.directory.identitygovernance.appconsent.request_scope import (
+    AppConsentRequestScope,
+)
 from office365.directory.identitygovernance.userconsent.request_collection import (
     UserConsentRequestCollection,
 )
 from office365.entity import Entity
+from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.resource_path import ResourcePath
 
 
@@ -15,6 +21,32 @@ class AppConsentRequest(Entity):
     the admin consent workflow is enabled.
     """
 
+    def __str__(self):
+        return self.app_display_name or self.entity_type_name
+
+    def __repr__(self):
+        return self.app_id or self.entity_type_name
+
+    @property
+    def app_display_name(self):
+        # type: () -> Optional[str]
+        """Display name of the application object on which this extension property is defined. Read-only"""
+        return self.properties.get("appDisplayName", None)
+
+    @property
+    def app_id(self):
+        # type: () -> Optional[str]
+        """The identifier of the application"""
+        return self.properties.get("appId", None)
+
+    @property
+    def pending_scopes(self):
+        # type: () -> ClientValueCollection[AppConsentRequestScope]
+        """A list of pending scopes waiting for approval. Required."""
+        return self.properties.get(
+            "pendingScopes", ClientValueCollection(AppConsentRequestScope)
+        )
+
     @property
     def user_consent_requests(self):
         """A list of pending user consent requests."""

office365/directory/identitygovernance/appconsent/request_scope.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class AppConsentRequestScope(ClientValue):
+    """The appConsentRequestScope details the dynamic permission scopes for which access is being requested."""

office365/directory/identitygovernance/privilegedaccess/group.py

@@ -0,0 +1,5 @@
+from office365.entity import Entity
+
+
+class PrivilegedAccessGroup(Entity):
+    """The entry point for all resources related to Privileged Identity Management (PIM) for groups."""

office365/directory/identitygovernance/privilegedaccess/root.py

@@ -1,5 +1,19 @@
+from office365.directory.identitygovernance.privilegedaccess.group import (
+    PrivilegedAccessGroup,
+)
 from office365.entity import Entity
+from office365.runtime.paths.resource_path import ResourcePath
 
 
 class PrivilegedAccessRoot(Entity):
     """Represents the entry point for resources related to Privileged Identity Management (PIM)."""
+
+    @property
+    def group(self):
+        """A list of pending user consent requests."""
+        return self.properties.get(
+            "group",
+            PrivilegedAccessGroup(
+                self.context, ResourcePath("group", self.resource_path)
+            ),
+        )

office365/directory/identitygovernance/privilegedaccess/schedule_instance.py

@@ -0,0 +1,6 @@
+from office365.entity import Entity
+
+
+class PrivilegedAccessScheduleInstance(Entity):
+    """An abstract type that exposes properties relating to the instances of membership and ownership assignments
+    and eligibilities to groups that are governed by PIM"""

office365/directory/policies/admin_consent_request.py

@@ -0,0 +1,10 @@
+from office365.entity import Entity
+
+
+class AdminConsentRequestPolicy(Entity):
+    """
+    Represents the policy for enabling or disabling the Microsoft Entra admin consent workflow.
+    The admin consent workflow allows users to request access for apps that they wish to use and that require admin
+    authorization before users can use the apps to access organizational data.
+    There is a single adminConsentRequestPolicy per tenant.
+    """

office365/directory/policies/root.py

@@ -1,3 +1,4 @@
+from office365.directory.policies.admin_consent_request import AdminConsentRequestPolicy
 from office365.directory.policies.app_management import AppManagementPolicy
 from office365.directory.policies.authentication_flows import AuthenticationFlowsPolicy
 from office365.directory.policies.authentication_methods import (
@@ -20,6 +21,19 @@ from office365.runtime.paths.resource_path import ResourcePath
 class PolicyRoot(Entity):
     """Resource type exposing navigation properties for the policies singleton."""
 
+    @property
+    def admin_consent_request_policy(self):
+        """
+        The policy by which consent requests are created and managed for the entire tenant.
+        """
+        return self.properties.get(
+            "adminConsentRequestPolicy",
+            AdminConsentRequestPolicy(
+                self.context,
+                ResourcePath("adminConsentRequestPolicy", self.resource_path),
+            ),
+        )
+
     @property
     def authentication_methods_policy(self):
         """
@@ -151,6 +165,7 @@ class PolicyRoot(Entity):
     def get_property(self, name, default_value=None):
         if default_value is None:
             property_mapping = {
+                "adminConsentRequestPolicy": self.admin_consent_request_policy,
                 "authenticationStrengthPolicies": self.authentication_strength_policies,
                 "authenticationFlowsPolicy": self.authentication_flows_policy,
                 "appManagementPolicies": self.app_management_policies,

office365/directory/synchronization/status.py

@@ -1,5 +1,8 @@
 from office365.directory.synchronization.progress import SynchronizationProgress
 from office365.directory.synchronization.quarantine import SynchronizationQuarantine
+from office365.directory.synchronization.task_execution import (
+    SynchronizationTaskExecution,
+)
 from office365.runtime.client_value import ClientValue
 from office365.runtime.client_value_collection import ClientValueCollection
 
@@ -7,10 +10,20 @@ from office365.runtime.client_value_collection import ClientValueCollection
 class SynchronizationStatus(ClientValue):
     """Represents the current status of the synchronizationJob."""
 
-    def __init__(self, progress=None, quarantine=SynchronizationQuarantine()):
+    def __init__(
+        self,
+        progress=None,
+        quarantine=SynchronizationQuarantine(),
+        last_execution=SynchronizationTaskExecution(),
+        last_successful_execution=SynchronizationTaskExecution(),
+        last_successful_execution_with_exports=SynchronizationTaskExecution(),
+    ):
         """
         :param list[SynchronizationProgress] progress: Details of the progress of a job toward completion.
         :param SynchronizationQuarantine quarantine:
         """
         self.progress = ClientValueCollection(SynchronizationProgress, progress)
         self.quarantine = quarantine
+        self.lastExecution = last_execution
+        self.lastSuccessfulExecution = last_successful_execution
+        self.lastSuccessfulExecutionWithExports = last_successful_execution_with_exports

office365/directory/synchronization/task_execution.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class SynchronizationTaskExecution(ClientValue):
+    """Summarizes the results of the synchronization job run."""

office365/directory/users/user.py

@@ -1,6 +1,6 @@
 import json
 from datetime import datetime
-from typing import Optional
+from typing import List, Optional
 
 from office365.communications.onlinemeetings.collection import OnlineMeetingCollection
 from office365.communications.presences.presence import Presence
@@ -46,6 +46,7 @@ from office365.outlook.contacts.collection import ContactCollection
 from office365.outlook.contacts.folder import ContactFolder
 from office365.outlook.convert_id_result import ConvertIdResult
 from office365.outlook.mail.folders.collection import MailFolderCollection
+from office365.outlook.mail.item_body import ItemBody
 from office365.outlook.mail.mailbox_settings import MailboxSettings
 from office365.outlook.mail.messages.collection import MessageCollection
 from office365.outlook.mail.messages.message import Message
@@ -201,6 +202,7 @@ class User(DirectoryObject):
         bcc_recipients=None,
         save_to_sent_items=False,
     ):
+        # type: (str, str|ItemBody, List[str], List[str], List[str], bool) -> Message
         """Send a new message on the fly
 
         :param str subject: The subject of the message.
@@ -347,7 +349,7 @@ class User(DirectoryObject):
                 start_dt.isoformat(), end_dt.isoformat()
             )
 
-        self.context.add_query(qry).before_execute(_construct_request)
+        self.context.add_query(qry).before_query_execute(_construct_request)
         return return_type
 
     def get_reminder_view(self, start_dt, end_dt):

office365/graph_client.py

@@ -41,6 +41,7 @@ from office365.directory.users.collection import UserCollection
 from office365.directory.users.user import User
 from office365.education.root import EducationRoot
 from office365.entity_collection import EntityCollection
+from office365.graph_request import GraphRequest
 from office365.intune.devices.app_management import DeviceAppManagement
 from office365.intune.devices.collection import DeviceCollection
 from office365.intune.devices.management.management import DeviceManagement
@@ -58,7 +59,6 @@ from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
-from office365.runtime.odata.request import ODataRequest
 from office365.runtime.odata.v4.batch_request import ODataV4BatchRequest
 from office365.runtime.odata.v4.json_format import V4JsonFormat
 from office365.runtime.paths.resource_path import ResourcePath
@@ -73,31 +73,14 @@ from office365.teams.collection import TeamCollection
 from office365.teams.template import TeamsTemplate
 from office365.teams.viva.employee_experience import EmployeeExperience
 
-environments_endpoints = {
-    "GCCH": {
-        "graph_url": "https://graph.microsoft.com",
-        "entra_url": "https://login.microsoftonline.com",
-    },
-    "GCC High": {
-        "graph_url": "https://graph.microsoft.us",
-        "entra_url": "https://login.microsoftonline.us",
-    },
-    "DoD": {
-        "graph_url": "https://dod-graph.microsoft.us",
-        "entra_url": "https://login.chinacloudapi.cn",
-    },
-}
-
 
 class GraphClient(ClientRuntimeContext):
     """Graph Service client"""
 
-    def __init__(self, acquire_token_callback, version="v1.0", environment="GCCH"):
-        # type: (Callable[[], dict], str, str) -> None
+    def __init__(self, acquire_token_callback):
+        # type: (Callable[[], dict]) -> None
         super(GraphClient, self).__init__()
         self._pending_request = None
-        self._version = version
-        self._environment_endpoints = environments_endpoints.get(environment, None)
         self._acquire_token_callback = acquire_token_callback
 
     @staticmethod
@@ -127,7 +110,7 @@ class GraphClient(ClientRuntimeContext):
                 "thumbprint": thumbprint,
                 "private_key": private_key,
             },
-            token_cache=token_cache  # Default cache is in memory only.
+            token_cache=token_cache,  # Default cache is in memory only.
             # You can learn how to use SerializableTokenCache from
             # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
         )
@@ -246,29 +229,32 @@ class GraphClient(ClientRuntimeContext):
 
         return GraphClient(_acquire_token)
 
-    def execute_batch(self, items_per_batch=100):
+    def execute_batch(self, items_per_batch=100, success_callback=None):
         """Constructs and submit a batch request
 
         :param int items_per_batch: Maximum to be selected for bulk operation
+        :param (List[ClientObject|ClientResult])-> None success_callback: A success callback
         """
         batch_request = ODataV4BatchRequest(V4JsonFormat())
         batch_request.beforeExecute += self._authenticate_request
         while self.has_pending_request:
             qry = self._get_next_query(items_per_batch)
             batch_request.execute_query(qry)
+            if callable(success_callback):
+                success_callback(qry.return_type)
         return self
 
     def pending_request(self):
-        # type: () -> ODataRequest
+        # type: () -> GraphRequest
         if self._pending_request is None:
-            self._pending_request = ODataRequest(V4JsonFormat())
+            self._pending_request = GraphRequest()
             self._pending_request.beforeExecute += self._authenticate_request
             self._pending_request.beforeExecute += self._build_specific_query
         return self._pending_request
 
     def service_root_url(self):
         # type: () -> str
-        return "https://graph.microsoft.com/{0}".format(self._version)
+        return self.pending_request().service_root_url
 
     def _build_specific_query(self, request):
         # type: (RequestOptions) -> None

office365/graph_request.py

@@ -1,7 +1,30 @@
 from office365.runtime.odata.request import ODataRequest
 from office365.runtime.odata.v4.json_format import V4JsonFormat
 
+environments_endpoints = {
+    "GCCH": {
+        "graph_url": "https://graph.microsoft.com",
+        "entra_url": "https://login.microsoftonline.com",
+    },
+    "GCC High": {
+        "graph_url": "https://graph.microsoft.us",
+        "entra_url": "https://login.microsoftonline.us",
+    },
+    "DoD": {
+        "graph_url": "https://dod-graph.microsoft.us",
+        "entra_url": "https://login.chinacloudapi.cn",
+    },
+}
+
 
 class GraphRequest(ODataRequest):
-    def __init__(self):
+    def __init__(self, version="v1.0", environment="GCCH"):
+        # type: (str, str) -> None
         super(GraphRequest, self).__init__(V4JsonFormat())
+        self._version = version
+        self._environment_endpoints = environments_endpoints.get(environment, None)
+
+    @property
+    def service_root_url(self):
+        # type: () -> str
+        return "https://graph.microsoft.com/{0}".format(self._version)

office365/onedrive/driveitems/driveItem.py

@@ -469,6 +469,7 @@ class DriveItem(BaseItem):
         return self.get_content(format_name)
 
     def copy(self, name=None, parent=None, conflict_behavior=ConflictBehavior.Fail):
+        # type: (str, ItemReference|"DriveItem", str) -> ClientResult[str]
         """Asynchronously creates a copy of an driveItem (including any children), under a new parent item or with a
         new name.
 
@@ -480,32 +481,30 @@ class DriveItem(BaseItem):
 
         Returns location for details about how to monitor the progress of the copy, upon accepting the request.
         """
-        return_type = ClientResult(self.context)  # type: ClientResult[str]
+        return_type = ClientResult(self.context, str())
 
-        def _create_request(request):
-            # type: (RequestOptions) -> None
-            request.url += "?@microsoft.graph.conflictBehavior={0}".format(
-                conflict_behavior
-            )
+        def _copy(parent_reference):
+            # type: (ItemReference) -> None
+
+            def _create_request(request):
+                # type: (RequestOptions) -> None
+                request.url += "?@microsoft.graph.conflictBehavior={0}".format(
+                    conflict_behavior
+                )
+
+            def _process_response(resp):
+                # type: (requests.Response) -> None
+                resp.raise_for_status()
+                location = resp.headers.get("Location", None)
+                if location is None:
+                    return
+                return_type.set_property("__value", location)
 
-        def _process_response(resp):
-            # type: (requests.Response) -> None
-            resp.raise_for_status()
-            location = resp.headers.get("Location", None)
-            if location is None:
-                return
-            return_type.set_property("__value", location)
-
-        def _create_and_add_query(parent_reference):
-            """
-            :param office365.onedrive.listitems.item_reference.ItemReference or None parent_reference:  Reference to the
-             parent item the copy will be created in.
-            """
             payload = {"name": name, "parentReference": parent_reference}
-            self.context.before_execute(_create_request)
-            self.context.after_execute(_process_response)
             qry = ServiceOperationQuery(self, "copy", None, payload, None, return_type)
-            self.context.add_query(qry)
+            self.context.add_query(qry).before_query_execute(
+                _create_request
+            ).after_execute(_process_response)
 
         if isinstance(parent, DriveItem):
 
@@ -513,14 +512,15 @@ class DriveItem(BaseItem):
                 parent_reference = ItemReference(
                     drive_id=parent.parent_reference.driveId, _id=parent.id
                 )
-                _create_and_add_query(parent_reference)
+                _copy(parent_reference)
 
             parent.ensure_property("parentReference", _drive_item_loaded)
         else:
-            _create_and_add_query(parent)
+            _copy(parent)
         return return_type
 
-    def move(self, name=None, parent=None):
+    def move(self, name=None, parent=None, conflict_behavior=ConflictBehavior.Fail):
+        # type: (str, ItemReference|"DriveItem", str) -> "DriveItem"
         """To move a DriveItem to a new parent item, your app requests to update the parentReference of the DriveItem
         to move.
 
@@ -528,29 +528,34 @@ class DriveItem(BaseItem):
              original.
         :param ItemReference or DriveItem or None parent: Reference to the
              parent item the move will be created in.
+        :param str conflict_behavior: query parameter to customize the behavior when a conflict occurs.
         """
 
-        return_type = ClientResult(self.context, str())
+        return_type = DriveItem(self.context)
+        self.children.add_child(return_type)
 
-        def _create_and_add_query(parent_reference):
+        def _move(parent_reference):
+            # type: (ItemReference) -> None
             payload = {"name": name, "parentReference": parent_reference}
 
             def _construct_request(request):
                 # type: (RequestOptions) -> None
                 request.method = HttpMethod.Patch
+                request.url += "?@microsoft.graph.conflictBehavior={0}".format(
+                    conflict_behavior
+                )
 
-            self.context.before_execute(_construct_request)
-            qry = ServiceOperationQuery(self, "move", None, payload, None, return_type)
-            self.context.add_query(qry)
+            qry = ServiceOperationQuery(self, "", None, payload, None, return_type)
+            self.context.add_query(qry).before_execute(_construct_request)
 
         if isinstance(parent, DriveItem):
 
             def _drive_item_loaded():
-                _create_and_add_query(ItemReference(_id=parent.id))
+                _move(ItemReference(_id=parent.id))
 
             parent.ensure_property("parentReference", _drive_item_loaded)
         else:
-            _create_and_add_query(parent)
+            _move(parent)
         return return_type
 
     def rename(self, new_name):
@@ -618,9 +623,9 @@ class DriveItem(BaseItem):
                 DriveRecipient, [DriveRecipient.from_email(r) for r in recipients]
             ),
             "message": message,
-            "expirationDateTime": expiration_datetime.isoformat() + "Z"
-            if expiration_datetime
-            else None,
+            "expirationDateTime": (
+                expiration_datetime.isoformat() + "Z" if expiration_datetime else None
+            ),
             "password": password,
             "retainInheritedPermissions": retain_inherited_permissions,
         }
@@ -662,7 +667,7 @@ class DriveItem(BaseItem):
         return self
 
     def restore(self, parent_reference=None, name=None):
-        # type: (ItemReference or None, str or None) -> DriveItem
+        # type: (Optional[ItemReference], str) -> "DriveItem"
         """
         Restore a driveItem that has been deleted and is currently in the recycle bin.
         NOTE: This functionality is currently only available for OneDrive Personal.
@@ -910,8 +915,6 @@ class DriveItem(BaseItem):
 
     def set_property(self, name, value, persist_changes=True):
         super(DriveItem, self).set_property(name, value, persist_changes)
-        if name == "parentReference":
-            pass
         return self
 
     def get_property(self, name, default_value=None):

office365/onedrive/idle_session_signout.py

@@ -0,0 +1,15 @@
+from office365.runtime.client_value import ClientValue
+
+
+class IdleSessionSignOut(ClientValue):
+    """Represents the idle session sign-out policy settings for SharePoint."""
+
+    def __init__(
+        self,
+        is_enabled=None,
+        sign_out_after_in_seconds=None,
+        warn_after_in_seconds=None,
+    ):
+        self.isEnabled = is_enabled
+        self.signOutAfterInSeconds = sign_out_after_in_seconds
+        self.warnAfterInSeconds = warn_after_in_seconds

office365/onedrive/listitems/list_item.py

@@ -38,6 +38,7 @@ class ListItem(BaseItem):
 
     @property
     def versions(self):
+        # type: () -> EntityCollection[ListItemVersion]
         """The list of previous versions of the list item."""
         return self.properties.get(
             "versions",

office365/onedrive/lists/collection.py

@@ -26,3 +26,9 @@ class ListCollection(EntityCollection[List]):
         qry = CreateEntityQuery(self, payload, return_type)
         self.context.add_query(qry)
         return return_type
+
+    def get_by_name(self, name):
+        return List(self.context, EntityPath(name, self.resource_path))
+
+    def get_by_id(self, list_id):
+        return List(self.context, EntityPath(list_id, self.resource_path))

office365/onedrive/sharepoint_ids.py

@@ -5,13 +5,30 @@ class SharePointIds(ClientValue):
     """The SharePointIds resource groups the various identifiers for an item stored in a SharePoint site or OneDrive
     for Business into a single structure."""
 
-    def __init__(self, list_id=None, list_item_id=None, list_item_unique_id=None):
+    def __init__(
+        self,
+        list_id=None,
+        list_item_id=None,
+        list_item_unique_id=None,
+        siteId=None,
+        siteUrl=None,
+        tenantId=None,
+        webId=None,
+    ):
         """
         :param str list_id: The unique identifier (guid) for the item's list in SharePoint.
         :param str list_item_id: An integer identifier for the item within the containing list.
         :param str list_item_unique_id: The unique identifier (guid) for the item within OneDrive for Business
             or a SharePoint site.
+        :param str siteId: The unique identifier (guid) for the item's site collection (SPSite).
+        :param str siteUrl: The SharePoint URL for the site that contains the item.
+        :param str tenantId: The unique identifier (guid) for the tenancy.
+        :param str webId: The unique identifier (guid) for the item's site (SPWeb).
         """
         self.listId = list_id
         self.listItemId = list_item_id
         self.listItemUniqueId = list_item_unique_id
+        self.siteId = siteId
+        self.siteUrl = siteUrl
+        self.tenantId = tenantId
+        self.webId = webId

office365/onedrive/sharepoint_settings.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from office365.entity import Entity
+from office365.onedrive.idle_session_signout import IdleSessionSignOut
 from office365.runtime.types.collections import StringCollection
 
 
@@ -26,6 +27,18 @@ class SharepointSettings(Entity):
             "excludedFileExtensionsForSyncApp", StringCollection()
         )
 
+    @property
+    def idle_session_sign_out(self):
+        # type: () -> IdleSessionSignOut
+        """Specifies the idle session sign-out policies for the tenant."""
+        return self.properties.get("idleSessionSignOut", IdleSessionSignOut())
+
+    @property
+    def is_commenting_on_site_pages_enabled(self):
+        # type: () -> Optional[bool]
+        """Indicates whether comments are allowed on modern site pages in SharePoint."""
+        return self.properties.get("isCommentingOnSitePagesEnabled", None)
+
     @property
     def site_creation_default_managed_path(self):
         # type: () -> Optional[str]

office365/onedrive/shares/drive_item.py

@@ -8,7 +8,6 @@ from office365.onedrive.lists.list import List
 from office365.onedrive.permissions.permission import Permission
 from office365.onedrive.sites.site import Site
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.paths.v4.entity import EntityPath
 
 
 class SharedDriveItem(BaseItem):
@@ -48,7 +47,7 @@ class SharedDriveItem(BaseItem):
         """Used to access the underlying driveItem"""
         return self.properties.get(
             "driveItem",
-            DriveItem(self.context, EntityPath("driveItem", self.resource_path)),
+            DriveItem(self.context, ResourcePath("driveItem", self.resource_path)),
         )
 
     @property

office365/onedrive/sitepages/title_area.py

@@ -4,10 +4,20 @@ from office365.runtime.client_value import ClientValue
 class TitleArea(ClientValue):
     """Represents the title area of a given SharePoint page."""
 
-    def __init__(self, alternativeText=None, enableGradientEffect=None):
+    def __init__(
+        self,
+        alternative_text=None,
+        enable_gradient_effect=None,
+        image_web_url=None,
+        show_author=None,
+    ):
         """
-        :param str alternativeText: Alternative text on the title area.
-        :param bool enableGradientEffect: Indicates whether the title area has a gradient effect enabled.
+        :param str alternative_text: Alternative text on the title area.
+        :param bool enable_gradient_effect: Indicates whether the title area has a gradient effect enabled.
+        :param str image_web_url:
+        :param bool show_author:
         """
-        self.alternativeText = alternativeText
-        self.enableGradientEffect = enableGradientEffect
+        self.alternativeText = alternative_text
+        self.enableGradientEffect = enable_gradient_effect
+        self.imageWebUrl = image_web_url
+        self.showAuthor = show_author

office365/onedrive/storage/storage.py

@@ -0,0 +1,5 @@
+from office365.entity import Entity
+
+
+class Storage(Entity):
+    """Facilitates the structures of fileStorageContainers."""

office365/onedrive/workbooks/filter.py

@@ -2,11 +2,18 @@ from typing import Optional
 
 from office365.entity import Entity
 from office365.onedrive.workbooks.filter_criteria import WorkbookFilterCriteria
+from office365.runtime.queries.service_operation import ServiceOperationQuery
 
 
 class WorkbookFilter(Entity):
     """Manages the filtering of a table's column."""
 
+    def clear(self):
+        """Clear the filter on the given column."""
+        qry = ServiceOperationQuery(self, "clear")
+        self.context.add_query(qry)
+        return self
+
     @property
     def criteria(self):
         # type: () -> Optional[WorkbookFilterCriteria]