typings enhancements and examples updates

examples/auth/register_sharepoint_apponly.py

@@ -0,0 +1,21 @@
+"""
+Setting up an Azure AD app for app-only access for SharePoint API
+
+Steps:
+
+1. create and configure a self-signed X.509 certificate, which will be used to authenticate your Application
+    against Azure AD, while requesting the App Only access token. For example, to create the self-signed certificate,
+    run the following command at a terminal prompt:
+    openssl req -x509 -newkey rsa:2048 -keyout selfsignkey.pem -out selfsigncert.pem -nodes -days 365
+
+2. register Azure AD application
+3. add permissions
+4. upload certificate (public key)
+
+"""
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+admin_client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)

examples/outlook/messages/mark_all_as_read.py

@@ -1,5 +1,5 @@
 """
-
+Marks all items (messages) in folder as read
 """
 from office365.graph_client import GraphClient
 from tests import test_client_id, test_password, test_tenant, test_username

examples/sharepoint/contenttypes/get_by_name.py

@@ -7,4 +7,4 @@
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
 ct = ctx.web.content_types.get_by_name("Document").get().execute_query()
-print(ct.id)
+print(ct)

examples/sharepoint/files/get_from_sharing_link.py → examples/sharepoint/files/get_by_sharing_link.py

@@ -1,3 +1,7 @@
+"""
+Gets file by shared link
+"""
+
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.sharing.links.kind import SharingLinkKind
 from tests import test_team_site_url, test_user_credentials
@@ -12,6 +16,5 @@
 result = file.share_link(SharingLinkKind.OrganizationView).execute_query()
 
 # Resolve file by sharing link url (guest url)
-guest_url = result.value.sharingLinkInfo.Url
-shared_file = ctx.web.get_file_by_guest_url(guest_url).execute_query()
-print(shared_file.name)
+file = ctx.web.get_file_by_guest_url(str(result.value)).execute_query()
+print(file)

examples/sharepoint/sharing/share_web.py

@@ -18,6 +18,10 @@
     test_user_principal_name_alt, ExternalSharingSiteOption.View
 ).execute_query()
 if result.error_message is not None:
-    sys.exit(f"Web sharing failed: {result.error_message}")
+    sys.exit("Web sharing failed: {0}".format(result.error_message))
 
-print(f"Web '{result.url}' has been shared with user '{test_user_principal_name_alt}'")
+print(
+    "Web '{0}' has been shared with user '{1}'".format(
+        result.url, test_user_principal_name_alt
+    )
+)

office365/directory/audit/signins/signin.py

@@ -14,18 +14,14 @@ class SignIn(Entity):
 
     @property
     def app_display_name(self):
-        """
-        App name displayed in the Azure Portal.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """App name displayed in the Azure Portal."""
         return self.properties.get("appDisplayName", None)
 
     @property
     def app_id(self):
-        """
-        Unique GUID representing the app ID in the Azure Active Directory.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """Unique GUID representing the app ID in the Azure Active Directory."""
         return self.properties.get("appId", None)
 
     @property
@@ -92,34 +88,34 @@ def resource_id(self):
 
     @property
     def risk_detail(self):
+        # type: () -> Optional[str]
         """
         Provides the 'reason' behind a specific state of a risky user, sign-in or a risk event.
-        :rtype: str or None
         """
         return self.properties.get("riskDetail", None)
 
     @property
     def user_id(self):
+        # type: () -> Optional[str]
         """
         ID of the user that initiated the sign-in. Supports $filter (eq operator only).
-        :rtype: str or None
         """
         return self.properties.get("userId", None)
 
     @property
     def user_principal_name(self):
+        # type: () -> Optional[str]
         """
         User principal name of the user that initiated the sign-in. Supports $filter (eq and startsWith operators only).
-        :rtype: str or None
         """
         return self.properties.get("userPrincipalName", None)
 
     @property
     def status(self):
+        # type: () -> Optional[SignInStatus]
         """
         Sign-in status. Includes the error code and description of the error (in case of a sign-in failure).
         Supports $filter (eq operator only) on errorCode property.
-        :rtype: str or None
         """
         return self.properties.get("status", SignInStatus())
 

office365/directory/groups/lifecycle_policy.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity import Entity
 from office365.runtime.client_result import ClientResult
 from office365.runtime.queries.service_operation import ServiceOperationQuery
@@ -28,12 +30,12 @@ def add_group(self, group_id):
         return return_type
 
     def remove_group(self, group_id):
+        # type: (str) -> ClientResult[bool]
         """
         Removes a group from a lifecycle policy.
-
         :param str group_id: The identifier of the group to add to the policy.
         """
-        return_type = ClientResult[bool](self.context)
+        return_type = ClientResult(self.context)
         payload = {"groupId": group_id}
         qry = ServiceOperationQuery(
             self, "removeGroup", None, payload, None, return_type
@@ -43,25 +45,24 @@ def remove_group(self, group_id):
 
     @property
     def alternate_notification_emails(self):
+        # type: () -> Optional[str]
         """
         List of email address to send notifications for groups without owners.
         Multiple email address can be defined by separating email address with a semicolon.
-        :rtype: str or None
         """
         return self.properties.get("alternateNotificationEmails", None)
 
     @property
     def group_lifetime_in_days(self):
+        # type: () -> Optional[int]
         """
         Number of days before a group expires and needs to be renewed. Once renewed, the group expiration is extended
         by the number of days defined.
-        :rtype: int or None
         """
         return self.properties.get("groupLifetimeInDays", None)
 
     @property
     def managed_group_types(self):
-        """The group type for which the expiration policy applies. Possible values are All, Selected or None.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The group type for which the expiration policy applies. Possible values are All, Selected or None."""
         return self.properties.get("managedGroupTypes", None)

office365/directory/permissions/email_identity.py

@@ -3,3 +3,10 @@
 
 class EmailIdentity(Identity):
     """Represents the email identity of a user."""
+
+    def __init__(self, id_=None, email=None, display_name=None):
+        """
+        :param str email:
+        """
+        super(EmailIdentity, self).__init__(display_name, id_)
+        self.email = email

office365/directory/rolemanagement/role.py

@@ -24,9 +24,7 @@ def display_name(self):
 
     @property
     def members(self):
-        """
-        Users that are members of this directory role.
-        """
+        """Users that are members of this directory role."""
         from office365.directory.object_collection import DirectoryObjectCollection
 
         return self.properties.get(

office365/directory/rolemanagement/template.py

@@ -13,15 +13,11 @@ def __repr__(self):
     @property
     def display_name(self):
         # type: () -> Optional[str]
-        """
-        The display name to set for the directory role
-        """
+        """The display name to set for the directory role"""
         return self.properties.get("displayName", None)
 
     @property
     def description(self):
         # type: () -> Optional[str]
-        """
-        The display name to set for the directory role
-        """
+        """The display name to set for the directory role"""
         return self.properties.get("description", None)

office365/directory/rolemanagement/unified_role_assignment.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.rolemanagement.unified_role_definition import (
     UnifiedRoleDefinition,
 )
@@ -13,20 +15,19 @@ class UnifiedRoleAssignment(Entity):
 
     @property
     def app_scope_id(self):
+        # type: () -> Optional[str]
         """
         Identifier of the app-specific scope when the assignment scope is app-specific. Either this property or
         directoryScopeId is required. App scopes are scopes that are defined and understood by this application only.
         Use / for tenant-wide app scopes. Use directoryScopeId to limit the scope to particular directory objects,
         for example, administrative units. Supports $filter (eq, in).
-        :rtype: str
         """
         return self.properties.get("appScopeId", None)
 
     @property
     def condition(self):
-        """
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """ """
         return self.properties.get("condition", None)
 
     @property

office365/directory/rolemanagement/unified_role_definition.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.rolemanagement.unified_role_permission import (
     UnifiedRolePermission,
 )
@@ -13,16 +15,15 @@ class UnifiedRoleDefinition(Entity):
 
     @property
     def display_name(self):
-        """The display name for the unifiedRoleDefinition.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The display name for the unifiedRoleDefinition."""
         return self.properties.get("displayName", None)
 
     @property
     def is_built_in(self):
+        # type: () -> Optional[bool]
         """Flag indicating whether the role definition is part of the default set included in
         Azure Active Directory (Azure AD) or a custom definition.
-        :rtype: bool
         """
         return self.properties.get("isBuiltIn", None)
 
@@ -37,6 +38,7 @@ def role_permissions(self):
 
     @property
     def inherits_permissions_from(self):
+        # type: () -> EntityCollection[UnifiedRoleDefinition]
         """
         Read-only collection of role definitions that the given role definition inherits from. Only Azure AD built-in
         roles (isBuiltIn is true) support this attribute. Supports $expand.

office365/directory/users/user.py

@@ -71,6 +71,9 @@
 class User(DirectoryObject):
     """Represents an Azure AD user account. Inherits from directoryObject."""
 
+    def __repr__(self):
+        return self.user_principal_name or self.id or self.entity_type_name
+
     def add_extension(self, name):
         """
         Creates an open extension (openTypeExtension object) and add custom properties in a new or existing instance

office365/outlook/calendar/calendar.py

@@ -28,7 +28,7 @@ class Calendar(Entity):
     """
 
     def __repr__(self):
-        return self.name
+        return self.name or self.id or self.entity_type_name
 
     def allowed_calendar_sharing_roles(self, user):
         """

office365/outlook/contacts/contact.py

@@ -45,25 +45,19 @@ def manager(self):
     @manager.setter
     def manager(self, value):
         # type: (str) -> None
-        """
-        Sets name of the contact's manager.
-        """
+        """Sets name of the contact's manager."""
         self.set_property("manager", value)
 
     @property
     def mobile_phone(self):
         # type: () -> Optional[str]
-        """
-        The contact's mobile phone number.
-        """
+        """The contact's mobile phone number."""
         return self.properties.get("mobilePhone", None)
 
     @mobile_phone.setter
     def mobile_phone(self, value):
         # type: (str) -> None
-        """
-        Sets contact's mobile phone number.
-        """
+        """Sets contact's mobile phone number."""
         self.set_property("mobilePhone", value)
 
     @property