Office365-REST-Python-Client 2.5.1__py3-none-any.whl → 2.5.3__py3-none-any.whl

office365/outlook/mail/conversation.py

@@ -1,4 +1,5 @@
 import datetime
+from typing import Optional
 
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
@@ -15,33 +16,34 @@ class Conversation(Entity):
 
     @property
     def has_attachments(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether any of the posts within this Conversation has at least one attachment.
         Supports $filter (eq, ne) and $search.
-        :rtype: bool or None
         """
         return self.properties.get("hasAttachments", None)
 
     @property
     def last_delivered_datetime(self):
+        # type: () -> Optional[datetime.datetime]
         """The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time."""
         return self.properties.get("lastDeliveredDateTime", datetime.datetime.min)
 
     @property
     def preview(self):
+        # type: () -> Optional[str]
         """
         A short summary from the body of the latest post in this conversation.
         Supports $filter (eq, ne, le, ge).
-        :rtype: str or None
         """
         return self.properties.get("preview", None)
 
     @property
     def topic(self):
+        # type: () -> Optional[str]
         """
         The topic of the conversation. This property can be set when the conversation is created, but it cannot be
         updated.
-        :rtype: str or None
         """
         return self.properties.get("topic", None)
 
@@ -49,12 +51,12 @@ class Conversation(Entity):
     def unique_senders(self):
         """
         All the users that sent a message to this Conversation.
-        :rtype: str or None
         """
         return self.properties.get("uniqueSenders", StringCollection())
 
     @property
     def threads(self):
+        # type: () -> EntityCollection[ConversationThread]
         """A collection of all the conversation threads in the conversation."""
         return self.properties.get(
             "threads",

office365/outlook/mail/folders/collection.py

@@ -5,10 +5,3 @@ from office365.outlook.mail.folders.folder import MailFolder
 class MailFolderCollection(DeltaCollection[MailFolder]):
     def __init__(self, context, resource_path=None):
         super(MailFolderCollection, self).__init__(context, MailFolder, resource_path)
-
-    def __getitem__(self, key):
-        """
-        :param str key: MailFolder identifier or display name
-        :rtype: MailFolder
-        """
-        return super(MailFolderCollection, self).__getitem__(key)

office365/outlook/mail/folders/folder.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.extensions.extended_property import (
     MultiValueLegacyExtendedProperty,
     SingleValueLegacyExtendedProperty,
@@ -26,57 +28,84 @@ class MailFolder(Entity):
         self.context.add_query(qry)
         return return_type
 
-    @property
-    def child_folder_count(self):
+    def empty(self, delete_sub_folders=False):
         """
-        The number of immediate child mailFolders in the current mailFolder.
-        :rtype: int or None
+        Empties the folder
+        :param bool delete_sub_folders: true to indicate that subfolders should also be deleted; otherwise, false.
         """
+
+        def _empty(col):
+            # type: (MessageCollection) -> None
+            if not col.has_next:
+                [m.delete_object() for m in col]
+
+        self.messages.get_all(page_loaded=_empty)
+        return self
+
+    def mark_all_items_as_read(self):
+        """Marks all items in folder as read."""
+
+        def _mark_all_items_as_read(col):
+            # type: (MessageCollection) -> None
+            [m.set_property("isRead", True).update() for m in col.current_page]
+
+        self.messages.get_all(1, page_loaded=_mark_all_items_as_read)
+        return self
+
+    def mark_all_items_as_unread(self):
+        """Marks all items in folder as unread."""
+
+        def _mark_all_items_as_unread(col):
+            # type: (MessageCollection) -> None
+            [m.set_property("isRead", False).update() for m in col.current_page]
+
+        self.messages.get_all(page_loaded=_mark_all_items_as_unread)
+        return self
+
+    @property
+    def child_folder_count(self):
+        # type: () -> Optional[int]
+        """The number of immediate child mailFolders in the current mailFolder."""
         return self.properties.get("childFolderCount", None)
 
     @property
     def display_name(self):
-        """
-        The name of the Mail folder
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The name of the Mail folder"""
         return self.properties.get("displayName", None)
 
     @property
     def is_hidden(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether the mailFolder is hidden. This property can be set only when creating the folder.
         Find more information in Hidden mail folders.
-        :rtype: bool or None
         """
         return self.properties.get("isHidden", None)
 
     @property
     def parent_folder_id(self):
+        # type: () -> Optional[str]
         """
         The unique identifier for the mailFolder's parent mailFolder.
-        :rtype: str or None
         """
         return self.properties.get("parentFolderId", None)
 
     @property
     def total_item_count(self):
-        """
-        The number of items in the mailFolder.
-        :rtype: int
-        """
+        # type: () -> Optional[int]
+        """The number of items in the mailFolder."""
         return self.properties.get("totalItemCount", None)
 
     @property
     def unread_item_count(self):
-        """
-        The number of items in the mailFolder marked as unread.
-        :rtype: int
-        """
+        # type: () -> Optional[int]
+        """The number of items in the mailFolder marked as unread."""
         return self.properties.get("unreadItemCount", None)
 
     @property
     def child_folders(self):
+        # type: () -> EntityCollection[MailFolder]
         """The collection of child folders in the mailFolder."""
         return self.properties.get(
             "childFolders",
@@ -89,6 +118,7 @@ class MailFolder(Entity):
 
     @property
     def message_rules(self):
+        # type: () -> EntityCollection[MessageRule]
         """"""
         return self.properties.get(
             "messageRules",
@@ -112,6 +142,7 @@ class MailFolder(Entity):
 
     @property
     def multi_value_extended_properties(self):
+        # type: () -> EntityCollection[MultiValueLegacyExtendedProperty]
         """The collection of multi-value extended properties defined for the MailFolder."""
         return self.properties.get(
             "multiValueExtendedProperties",
@@ -124,6 +155,7 @@ class MailFolder(Entity):
 
     @property
     def single_value_extended_properties(self):
+        # type: () -> EntityCollection[SingleValueLegacyExtendedProperty]
         """The collection of single-value extended properties defined for the MailFolder."""
         return self.properties.get(
             "singleValueExtendedProperties",

office365/outlook/mail/messages/collection.py

@@ -16,7 +16,6 @@ class MessageCollection(DeltaCollection[Message]):
         :param str subject: The subject of the message.
         :param str or ItemBody body: The body of the message. It can be in HTML or text format
         :param list[str] to_recipients:
-        :rtype: Message
         """
         if to_recipients is not None:
             kwargs["toRecipients"] = ClientValueCollection(

office365/outlook/mail/messages/message.py

@@ -1,7 +1,9 @@
 import os
 import uuid
 from datetime import datetime
-from typing import Optional
+from typing import IO, AnyStr, Optional
+
+from typing_extensions import Self
 
 from office365.directory.extensions.extended_property import (
     MultiValueLegacyExtendedProperty,
@@ -26,11 +28,8 @@ class Message(OutlookItem):
     """A message in a mailbox folder."""
 
     def add_extended_property(self, name, value):
-        """
-        Create a single-value extended property for a message
-        :param str name: A property name
-        :param str value:
-        """
+        # type: (str, str) -> Self
+        """Create a single-value extended property for a message"""
         prop_id = str(uuid.uuid4())
         prop_type = "String"
         prop_value = [
@@ -63,25 +62,20 @@ class Message(OutlookItem):
         return self
 
     def download(self, file_object):
-        """Download MIME content of a message into a file
-
-        :type file_object: typing.IO
-        """
+        # type: (IO) -> Self
+        """Download MIME content of a message into a file"""
 
         def _save_content(return_type):
-            """
-            :type return_type: ClientResult
-            """
+            # type: (ClientResult[AnyStr]) -> None
             file_object.write(return_type.value)
 
         self.get_content().after_execute(_save_content)
         return self
 
     def get_content(self):
-        """
-        Get MIME content of a message
-        """
-        return_type = ClientResult[str](self.context)
+        # type: () -> ClientResult[AnyStr]
+        """Get MIME content of a message"""
+        return_type = ClientResult(self.context)
         qry = FunctionQuery(self, "$value", None, return_type)
         self.context.add_query(qry)
         return return_type
@@ -180,17 +174,30 @@ class Message(OutlookItem):
         self.context.add_query(qry)
         return self
 
-    def move(self, destination_id):
+    def move(self, destination):
         """
         Move a message to another folder within the specified user's mailbox.
         This creates a new copy of the message in the destination folder and removes the original message.
 
-        :param str destination_id: The destination folder ID, or a well-known folder name.
+        :param str or MailFolder destination: The destination folder ID, or a well-known folder name.
             For a list of supported well-known folder names, see mailFolder resource type.
         """
-        payload = {"DestinationId": destination_id}
-        qry = ServiceOperationQuery(self, "move", None, payload, None, None)
-        self.context.add_query(qry)
+        from office365.outlook.mail.folders.folder import MailFolder
+
+        def _move(destination_id):
+            # type: (str) -> None
+            payload = {"DestinationId": destination_id}
+            qry = ServiceOperationQuery(self, "move", None, payload, None, None)
+            self.context.add_query(qry)
+
+        if isinstance(destination, MailFolder):
+
+            def _loaded():
+                _move(destination.id)
+
+            destination.ensure_property("id", _loaded)
+        else:
+            _move(destination)
         return self
 
     def forward(self, to_recipients, comment=""):
@@ -211,13 +218,12 @@ class Message(OutlookItem):
 
     @property
     def has_attachments(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether the message has attachments. This property doesn't include inline attachments,
         so if a message contains only inline attachments, this property is false. To verify the existence
         of inline attachments, parse the body property to look for a src attribute,
         such as <IMG src="cid:image001.jpg@01D26CD8.6C05F070">.
-
-        :rtype: bool or None
         """
         return self.properties.get("hasAttachments", None)
 
@@ -235,6 +241,7 @@ class Message(OutlookItem):
 
     @property
     def extensions(self):
+        # type: () -> EntityCollection[Extension]
         """The collection of open extensions defined for the message. Nullable."""
         return self.properties.get(
             "extensions",
@@ -245,44 +252,33 @@ class Message(OutlookItem):
 
     @property
     def body(self):
-        """The body of the message. It can be in HTML or text format.
-
-        :rtype: ItemBody
-        """
+        """The body of the message. It can be in HTML or text format."""
         return self.properties.setdefault("body", ItemBody())
 
     @body.setter
     def body(self, value):
-        """The body of the message. It can be in HTML or text format.
-
-        :type value: str or ItemBody
-        """
+        # type: (str|ItemBody) -> None
+        """Sets the body of the message. It can be in HTML or text format."""
         if not isinstance(value, ItemBody):
             value = ItemBody(value)
         self.set_property("body", value)
 
     @property
     def body_preview(self):
-        """
-        The first 255 characters of the message body. It is in text format.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The first 255 characters of the message body. It is in text format."""
         return self.properties.get("bodyPreview", None)
 
     @property
     def conversation_id(self):
-        """
-        The ID of the conversation the email belongs to.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The ID of the conversation the email belongs to."""
         return self.properties.get("conversationId", None)
 
     @property
     def conversation_index(self):
-        """
-        Indicates the position of the message within the conversation.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Indicates the position of the message within the conversation."""
         return self.properties.get("conversationIndex", None)
 
     @property
@@ -303,23 +299,22 @@ class Message(OutlookItem):
 
     @property
     def importance(self):
-        """
-        The importance of the message.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The importance of the message."""
         return self.properties.get("importance", None)
 
     @property
     def inference_classification(self):
+        # type: () -> Optional[str]
         """
         The classification of the message for the user, based on inferred relevance or importance,
         or on an explicit override. The possible values are: focused or other.
-        :rtype: str
         """
         return self.properties.get("inferenceClassification", None)
 
     @property
     def internet_message_headers(self):
+        # type: () -> ClientValueCollection[InternetMessageHeader]
         """
         A collection of message headers defined by RFC5322. The set includes message headers indicating the network
         path taken by a message from the sender to the recipient. It can also contain custom message headers that
@@ -331,41 +326,37 @@ class Message(OutlookItem):
 
     @property
     def internet_message_id(self):
-        """
-        The message ID in the format specified by RFC2822
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The message ID in the format specified by RFC2822"""
         return self.properties.get("internetMessageId", None)
 
     @property
     def is_delivery_receipt_requested(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether a read receipt is requested for the message.
-        :rtype: bool
         """
         return self.properties.get("isDeliveryReceiptRequested", None)
 
     @property
     def is_draft(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet.
-        :rtype: bool
         """
         return self.properties.get("isDraft", None)
 
     @property
     def is_read(self):
-        """
-        Indicates whether the message has been read.
-        :rtype: bool
-        """
+        # type: () -> Optional[bool]
+        """Indicates whether the message has been read."""
         return self.properties.get("isRead", None)
 
     @property
     def is_read_receipt_requested(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether a read receipt is requested for the message.
-        :rtype: bool
         """
         return self.properties.get("isReadReceiptRequested", None)
 
@@ -389,10 +380,8 @@ class Message(OutlookItem):
 
     @subject.setter
     def subject(self, value):
-        """
-        The subject of the message.
-        :type value: str
-        """
+        # type: (str) -> None
+        """Sets the subject of the message."""
         self.set_property("subject", value)
 
     @property
@@ -429,13 +418,13 @@ class Message(OutlookItem):
 
     @property
     def parent_folder_id(self):
-        """The unique identifier for the message's parent mailFolder.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The unique identifier for the message's parent mailFolder."""
         return self.properties.get("parentFolderId", None)
 
     @property
     def web_link(self):
+        # type: () -> Optional[str]
         """
         The URL to open the message in Outlook on the web.
 
@@ -447,12 +436,12 @@ class Message(OutlookItem):
         You will be prompted to login if you are not already logged in with the browser.
 
         This URL cannot be accessed from within an iFrame.
-        :rtype: str or None
         """
         return self.properties.get("webLink", None)
 
     @property
     def multi_value_extended_properties(self):
+        # type: () -> EntityCollection[MultiValueLegacyExtendedProperty]
         """The collection of multi-value extended properties defined for the event."""
         return self.properties.get(
             "multiValueExtendedProperties",
@@ -465,6 +454,7 @@ class Message(OutlookItem):
 
     @property
     def single_value_extended_properties(self):
+        # type: () -> EntityCollection[SingleValueLegacyExtendedProperty]
         """The collection of single-value extended properties defined for the message"""
         return self.properties.get(
             "singleValueExtendedProperties",

office365/outlook/mail/physical_address.py

@@ -1,5 +1,10 @@
+from typing import TYPE_CHECKING
+
 from office365.runtime.client_value import ClientValue
 
+if TYPE_CHECKING:
+    from typing import Optional  # noqa
+
 
 class PhysicalAddress(ClientValue):
     """The physical address of a contact."""
@@ -12,12 +17,13 @@ class PhysicalAddress(ClientValue):
         state=None,
         street=None,
     ):
+        # type: (Optional[str], Optional[str], Optional[str], Optional[str], Optional[str]) -> None
         """
-        :param str city: The city.
-        :param str country_or_region: The country or region. It's a free-format string value, for example, "United States".
-        :param str postal_code: The postal code.
-        :param str state:
-        :param str street:
+        :param city: The city.
+        :param country_or_region: The country or region. It's a free-format string value, for example, "United States".
+        :param postal_code: The postal code.
+        :param state:
+        :param street:
         """
         super(PhysicalAddress, self).__init__()
         self.city = city

office365/outlook/mail/recipient.py

@@ -5,10 +5,12 @@ from office365.runtime.client_value import ClientValue
 class Recipient(ClientValue):
     """Represents information about a user in the sending or receiving end of an event, message or group post."""
 
-    def __init__(self, email_address=EmailAddress()):
+    def __init__(self, email_address=None):
         """
         :param EmailAddress email_address: The recipient's email address.
         """
+        if email_address is None:
+            email_address = EmailAddress()
         super(Recipient, self).__init__()
         self.emailAddress = email_address
 

office365/outlook/mail/recurrence_range.py

@@ -1,9 +1,16 @@
+from typing import TYPE_CHECKING
+
 from office365.runtime.client_value import ClientValue
 
+if TYPE_CHECKING:
+    import datetime  # noqa
+
+    from typing import Optional  # noqa
+
 
 class RecurrenceRange(ClientValue):
     """
-    Describes a date range over which a recurring event. This shared object is used to define the recurrence
+    Describes a date range over which a recurring event. This shared hobject is used to define the recurrence
     of access reviews, calendar events, and access package assignments in Azure AD.
     """
 
@@ -15,17 +22,18 @@ class RecurrenceRange(ClientValue):
         recurrence_timezone=None,
         range_type=None,
     ):
+        # type: (Optional[datetime.date], Optional[datetime.date], Optional[int], Optional[str], Optional[str]) -> None
         """
-        :param datetime.date start_date: The date to start applying the recurrence pattern. The first occurrence of
+        :param start_date: The date to start applying the recurrence pattern. The first occurrence of
             the meeting may be this date or later, depending on the recurrence pattern of the event. Must be the
             same value as the start property of the recurring event. Required.
-        :param datetime.date end_date: The date to stop applying the recurrence pattern. Depending on the recurrence pattern of
+        :param end_date: The date to stop applying the recurrence pattern. Depending on the recurrence pattern of
             the event, the last occurrence of the meeting may not be this date. Required if type is endDate.
-        :param int number_of_occurrences: The number of times to repeat the event. Required and must be positive
+        :param number_of_occurrences: The number of times to repeat the event. Required and must be positive
             if type is numbered.
-        :param str recurrence_timezone: Time zone for the startDate and endDate properties. Optional. If not specified,
+        :param recurrence_timezone: Time zone for the startDate and endDate properties. Optional. If not specified,
             the time zone of the event is used.
-        :param str range_type: The recurrence range. The possible values are: endDate, noEnd, numbered. Required.
+        :param range_type: The recurrence range. The possible values are: endDate, noEnd, numbered. Required.
         """
         self.endDate = end_date
         self.numberOfOccurrences = number_of_occurrences

office365/outlook/user.py

@@ -41,6 +41,7 @@ class OutlookUser(Entity):
 
     @property
     def master_categories(self):
+        # type: () -> EntityCollection[OutlookCategory]
         """A list of categories defined for the user."""
         return self.properties.get(
             "masterCategories",

office365/planner/planner.py

@@ -1,7 +1,7 @@
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.planner.buckets.bucket import PlannerBucket
-from office365.planner.plans.plan import PlannerPlan
+from office365.planner.plans.collection import PlannerPlanCollection
 from office365.planner.tasks.task import PlannerTask
 from office365.runtime.paths.resource_path import ResourcePath
 
@@ -14,9 +14,8 @@ class Planner(Entity):
 
     @property
     def buckets(self):
-        """
-        Read-only. Nullable. Returns the plannerBuckets assigned to the user.
-        """
+        # type: () -> EntityCollection[PlannerBucket]
+        """Returns the plannerBuckets assigned to the user."""
         return self.properties.get(
             "buckets",
             EntityCollection(
@@ -26,9 +25,8 @@ class Planner(Entity):
 
     @property
     def tasks(self):
-        """
-        Read-only. Nullable. Returns the plannerTasks assigned to the user.
-        """
+        # type: () -> EntityCollection[PlannerTask]
+        """Returns the plannerTasks assigned to the user."""
         return self.properties.get(
             "tasks",
             EntityCollection(
@@ -38,12 +36,11 @@ class Planner(Entity):
 
     @property
     def plans(self):
-        """
-        Read-only. Nullable. Returns the plannerTasks assigned to the user.
-        """
+        # type: () -> PlannerPlanCollection
+        """Returns the plannerTasks assigned to the user."""
         return self.properties.get(
             "plans",
-            EntityCollection(
-                self.context, PlannerPlan, ResourcePath("plans", self.resource_path)
+            PlannerPlanCollection(
+                self.context, ResourcePath("plans", self.resource_path)
             ),
         )