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

office365/sharepoint/navigation/node.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.sharepoint.entity import Entity
 from office365.sharepoint.translation.user_resource import UserResource
@@ -9,6 +11,12 @@ class NavigationNode(Entity):
     manipulating the ordering of the navigation node in a navigation node collection.
     """
 
+    def __str__(self):
+        return self.title
+
+    def __repr__(self):
+        return self.url
+
     @property
     def children(self):
         """Gets the collection of child nodes of the navigation node."""
@@ -25,10 +33,8 @@ class NavigationNode(Entity):
 
     @property
     def title(self):
-        """Gets a value that specifies the anchor text for the navigation node link.
-
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """Gets a value that specifies the anchor text for the navigation node link."""
         return self.properties.get("Title", None)
 
     @title.setter
@@ -38,10 +44,8 @@ class NavigationNode(Entity):
 
     @property
     def url(self):
-        """Gets a value that specifies the URL stored with the navigation node.
-
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """Gets a value that specifies the URL stored with the navigation node."""
         return self.properties.get("Url", None)
 
     @url.setter
@@ -51,17 +55,14 @@ class NavigationNode(Entity):
 
     @property
     def is_visible(self):
-        """Gets a value that specifies the anchor text for the navigation node link.
-
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Gets a value that specifies the anchor text for the navigation node link."""
         return self.properties.get("isVisible", None)
 
     @property
     def is_external(self):
-        """
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """ """
         return self.properties.get("isExternal", None)
 
     @property

office365/sharepoint/navigation/node_collection.py

@@ -1,21 +1,27 @@
+from typing import TYPE_CHECKING
+
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.create_entity import CreateEntityQuery
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.navigation.node import NavigationNode
 
+if TYPE_CHECKING:
+    from office365.sharepoint.navigation.node_creation_information import (
+        NavigationNodeCreationInformation,  # noqa
+    )
+
 
-class NavigationNodeCollection(EntityCollection):
+class NavigationNodeCollection(EntityCollection[NavigationNode]):
     def __init__(self, context, resource_path=None):
         super(NavigationNodeCollection, self).__init__(
             context, NavigationNode, resource_path
         )
 
     def add(self, create_node_info):
+        # type: (NavigationNodeCreationInformation) -> NavigationNode
         """
         Creates a navigation node object and adds it to the collection.
-
-        :type create_node_info: office365.sharepoint.navigation.node_creation_information.NavigationNodeCreationInformation
         """
         return_type = NavigationNode(self.context)
         return_type.title = create_node_info.Title

office365/sharepoint/permissions/base_permissions.py

@@ -1,4 +1,5 @@
 import inspect
+from typing import Iterator
 
 from office365.runtime.client_value import ClientValue
 from office365.sharepoint.permissions.kind import PermissionKind
@@ -12,9 +13,15 @@ class BasePermissions(ClientValue):
         self.High = 0
         self.Low = 0
 
+    def __iter__(self):
+        # type: () -> Iterator[str]
+        for k, v in inspect.getmembers(PermissionKind):
+            if isinstance(v, int) and self.has(v):
+                yield k
+
     def set(self, perm):
         """
-
+        Assigns the permission
         :type perm: int
         """
         if perm == PermissionKind.FullMask:
@@ -34,6 +41,7 @@ class BasePermissions(ClientValue):
                 self.High |= low << high - 32
 
     def has(self, perm):
+        # type: (int) -> bool
         """Determines whether the current instance has the specified permission."""
         if perm == PermissionKind.EmptyMask:
             return True
@@ -59,8 +67,5 @@ class BasePermissions(ClientValue):
 
     @property
     def permission_levels(self):
-        result = []
-        for k, v in inspect.getmembers(PermissionKind):
-            if isinstance(v, int) and self.has(v):
-                result.append(k)
-        return result
+        """Gets permission levels"""
+        return list(self)

office365/sharepoint/permissions/roles/assignments/collection.py

@@ -5,7 +5,7 @@ from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.permissions.roles.assignments.assignment import RoleAssignment
 
 
-class RoleAssignmentCollection(EntityCollection):
+class RoleAssignmentCollection(EntityCollection[RoleAssignment]):
     """Represents a collection of RoleAssignment resources."""
 
     def __init__(self, context, resource_path=None):
@@ -13,18 +13,14 @@ class RoleAssignmentCollection(EntityCollection):
             context, RoleAssignment, resource_path
         )
 
-    def __getitem__(self, index_or_principal_id):
+    def __getitem__(self, key):
         """
-        :param int or str index_or_principal_id: key is used to address a RoleAssignment resource by either an index
+        :param int or str key: key is used to address a RoleAssignment resource by either an index
         in collection or by resource id"""
-        if type(index_or_principal_id) == int:
-            return super(RoleAssignmentCollection, self).__getitem__(
-                index_or_principal_id
-            )
+        if isinstance(key, int):
+            return super(RoleAssignmentCollection, self).__getitem__(key)
         else:
-            return self._item_type(
-                self.context, ResourcePath(index_or_principal_id, self.resource_path)
-            )
+            return self._item_type(self.context, ResourcePath(key, self.resource_path))
 
     def get_by_principal_id(self, principal_id):
         """Retrieves the role assignment object (1) based on the specified user or group.
@@ -39,10 +35,10 @@ class RoleAssignmentCollection(EntityCollection):
         )
 
     def add_role_assignment(self, principal_id, role_def_id):
-        """Adds a role assignment to the role assignment collection.<81>
+        """Adds a role assignment to the role assignment collection.
 
-        :param int role_def_id: Specifies the role definition of the role assignment.
         :param int principal_id: Specifies the user or group of the role assignment.
+        :param int role_def_id: Specifies the role definition of the role assignment.
         """
         payload = {"principalId": principal_id, "roleDefId": role_def_id}
         qry = ServiceOperationQuery(

office365/sharepoint/permissions/roles/definitions/definition.py

@@ -9,7 +9,7 @@ class RoleDefinition(Entity):
     """Defines a single role definition, including a name, description, and set of rights."""
 
     def __repr__(self):
-        return self.name
+        return self.name or self.entity_type_name
 
     @property
     def base_permissions(self):
@@ -22,12 +22,14 @@ class RoleDefinition(Entity):
 
     @property
     def id(self):
+        # type: () -> Optional[int]
         """Specifies the identifier of the role definition.
         Its value MUST be equal to or greater than 1073741824."""
         return self.properties.get("Id", None)
 
     @property
     def role_type_kind(self):
+        # type: () -> Optional[int]
         """Specifies the type of the role definition.
         Its value MUST be equal to or greater than 0. Its value MUST be equal to or less than 5.
         """

office365/sharepoint/permissions/securable_object.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from typing_extensions import Self
 
 from office365.runtime.client_result import ClientResult
@@ -33,41 +35,50 @@ class SecurableObject(Entity):
         principal.ensure_property("Id", _principal_loaded)
         return return_type
 
-    def add_role_assignment(self, principal, role_def):
-        # type: (Principal, RoleDefinition) -> Self
+    def add_role_assignment(self, principal, role):
+        # type: (Principal|str, RoleDefinition|int) -> Self
         """Adds a role assignment to securable resource.
 
-        :param office365.sharepoint.permissions.roles.definitions.definition.RoleDefinition role_def: Specifies the
-            role definition of the role assignment.
-        :param office365.sharepoint.principal.principal.Principal principal: Specifies the user or group of the
-            role assignment.
+        :param RoleDefinition or int principal: Specifies the role definition or role type.
+        :param Principal or str role: Specifies the user or group of the role assignment.
         """
 
-        def _principal_loaded():
-            role_def.ensure_property("Id", _role_def_loaded)
+        if not isinstance(principal, Principal):
+            principal = self.context.web.site_users.get_by_principal_name(principal)
 
-        def _role_def_loaded():
-            self.role_assignments.add_role_assignment(principal.id, role_def.id)
+        if not isinstance(role, RoleDefinition):
+            role = self.context.web.role_definitions.get_by_type(role)
 
-        principal.ensure_property("Id", _principal_loaded)
+        def _ensure_role_def():
+            role.ensure_property("Id", _add_role_assignment)
+
+        def _add_role_assignment():
+            self.role_assignments.add_role_assignment(principal.id, role.id)
+
+        principal.ensure_property("Id", _ensure_role_def)
         return self
 
     def remove_role_assignment(self, principal, role_def):
-        """Removes a role assignment from a securable resource.<81>
-
-        :param office365.sharepoint.permissions.role_definition.RoleDefinition role_def: Specifies the role definition
-        of the role assignment.
-        :param office365.sharepoint.principal.principal.Principal principal: Specifies the user or group of the
+        # type: (Principal|str, RoleDefinition|int) -> Self
+        """Removes a role assignment from a securable resource.
+        :param Principal principal: Specifies the user or group of the
         role assignment.
+        :param RoleDefinition role_def: Specifies the role definition
+        of the role assignment.
         """
+        if not isinstance(principal, Principal):
+            principal = self.context.web.site_users.get_by_principal_name(principal)
 
-        def _principal_loaded():
-            def _role_def_loaded():
-                self.role_assignments.remove_role_assignment(principal.id, role_def.id)
+        if not isinstance(role_def, RoleDefinition):
+            role_def = self.context.web.role_definitions.get_by_type(role_def)
 
-            role_def.ensure_property("Id", _role_def_loaded)
+        def _remove_role_assignment():
+            self.role_assignments.remove_role_assignment(principal.id, role_def.id)
 
-        principal.ensure_property("Id", _principal_loaded)
+        def _ensure_role_def():
+            role_def.ensure_property("Id", _remove_role_assignment)
+
+        principal.ensure_property("Id", _ensure_role_def)
         return self
 
     def break_role_inheritance(self, copy_role_assignments=True, clear_sub_scopes=True):
@@ -110,19 +121,16 @@ class SecurableObject(Entity):
         return self
 
     def get_user_effective_permissions(self, user):
+        # type: (str|User) -> ClientResult[BasePermissions]
         """
-        Returns the user permissions for this list.
+        Returns the user permissions for secured object.
 
         :param str or User user: Specifies the user login name or User object.
         """
-        return_type = ClientResult(
-            self.context, BasePermissions()
-        )  # type: ClientResult[BasePermissions]
+        return_type = ClientResult(self.context, BasePermissions())
 
         def _create_and_add_query(login_name):
-            """
-            :param str login_name:
-            """
+            # type: (str) -> None
             qry = ServiceOperationQuery(
                 self,
                 "GetUserEffectivePermissions",
@@ -145,17 +153,16 @@ class SecurableObject(Entity):
 
     @property
     def has_unique_role_assignments(self):
+        # type: () -> Optional[bool]
         """Specifies whether the role assignments are uniquely defined for this securable object or inherited from a
         parent securable object. If the value is "false", role assignments are inherited from a parent securable
         object.
-
-        :rtype: bool or None
         """
         return self.properties.get("HasUniqueRoleAssignments", None)
 
     @property
     def first_unique_ancestor_securable_object(self):
-        """Specifies the object where role assignments for this object are defined.<85>."""
+        """Specifies the object where role assignments for this object are defined"""
         return self.properties.get(
             "FirstUniqueAncestorSecurableObject",
             SecurableObject(

office365/sharepoint/portal/groups/service.py

@@ -1,40 +1,36 @@
 import random
+from typing import AnyStr
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.http.http_method import HttpMethod
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity import Entity
 
 
 class GroupService(Entity):
-    def __init__(self, context, resource_path=None):
-        super(GroupService, self).__init__(context, resource_path)
-
-    def get_group_image(self, group_id, image_hash=None, image_color=None):
-        """
-        :param str group_id:
-        :param int or None image_hash:
-        :param str or None image_color:
-        """
-        return_type = ClientResult(self.context)
+    def get_group_image(
+        self, group_id, image_hash=None, image_color=None, return_type=None
+    ):
+        # type: (str, str, str, ClientResult) -> ClientResult[AnyStr]
+        if return_type is None:
+            return_type = ClientResult(self.context)
         if image_hash is None:
             image_hash = random.getrandbits(64)
         qry = ServiceOperationQuery(
             self, "GetGroupImage", None, None, None, return_type
         )
 
-        def _modify_request(request):
-            """
-            :type request: office365.runtime.http.request_options.RequestOptions
-            """
+        def _create_request(request):
+            # type: (RequestOptions) -> None
             request.url += "?id='{0}'&hash={1}".format(group_id, image_hash)
             request.method = HttpMethod.Get
 
-        self.context.before_execute(_modify_request)
-        self.context.add_query(qry)
+        self.context.add_query(qry).before_execute(_create_request)
         return return_type
 
     def sync_group_properties(self):
+        """ """
         qry = ServiceOperationQuery(self, "SyncGroupProperties")
         self.context.add_query(qry)
         return self

office365/sharepoint/portal/groups/site_manager.py

@@ -120,7 +120,6 @@ class GroupSiteManager(ClientObject):
     ):
         """
         Get the teams in Microsoft Teams that the current user is a direct member of.
-
         :type get_logo_data: bool
         :type force_cache_update: bool
         """

office365/sharepoint/principal/groups/group.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING, Optional
+
 from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.resource_path import ResourcePath
@@ -5,6 +7,9 @@ from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.principal.principal import Principal
 from office365.sharepoint.utilities.principal_info import PrincipalInfo
 
+if TYPE_CHECKING:
+    from office365.sharepoint.principal.groups.collection import GroupCollection
+
 
 class Group(Principal):
     """Represents a collection of members in a SharePoint site. A group is a type of SP.Principal."""
@@ -67,72 +72,61 @@ class Group(Principal):
 
     @property
     def parent_collection(self):
-        """
-        :rtype: office365.sharepoint.principal.groups.collection.GroupCollection
-        """
+        # type: () -> GroupCollection
         return self._parent_collection
 
     @property
     def allow_members_edit_membership(self):
-        """Specifies whether a member of the group can add and remove members from the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether a member of the group can add and remove members from the group"""
         return self.properties.get("AllowMembersEditMembership", None)
 
     @property
     def allow_request_to_join_leave(self):
-        """Specifies whether to allow users to request to join or leave in the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether to allow users to request to join or leave in the group."""
         return self.properties.get("AllowRequestToJoinLeave", None)
 
     @property
     def auto_accept_request_to_join_leave(self):
-        """Specifies whether requests to join or leave the group are automatically accepted.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether requests to join or leave the group are automatically accepted"""
         return self.properties.get("AutoAcceptRequestToJoinLeave", None)
 
     @property
     def can_current_user_edit_membership(self):
-        """Specifies whether the current user can add and remove members from the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether the current user can add and remove members from the group."""
         return self.properties.get("CanCurrentUserEditMembership", None)
 
     @property
     def can_current_user_manage_group(self):
-        """Gets a Boolean value that indicates whether the current user can manage the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Gets a Boolean value that indicates whether the current user can manage the group."""
         return self.properties.get("CanCurrentUserManageGroup", None)
 
     @property
     def can_current_user_view_membership(self):
-        """Specifies whether the current user can view the membership of the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether the current user can view the membership of the group."""
         return self.properties.get("CanCurrentUserViewMembership", None)
 
     @property
     def only_allow_members_view_membership(self):
-        """Specifies whether viewing the membership of the group is restricted to members of the group.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether viewing the membership of the group is restricted to members of the group."""
         return self.properties.get("OnlyAllowMembersViewMembership", None)
 
     @property
     def owner_title(self):
-        """Specifies the name of the owner of the group.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the name of the owner of the group."""
         return self.properties.get("OwnerTitle", None)
 
     @property
     def request_to_join_leave_email_setting(self):
-        """Specifies the e-mail address to which requests to join or leave the group are sent.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the e-mail address to which requests to join or leave the group are sent."""
         return self.properties.get("RequestToJoinLeaveEmailSetting", None)
 
     @property

office365/sharepoint/principal/principal.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.sharepoint.entity import Entity
 
@@ -5,54 +7,54 @@ from office365.sharepoint.entity import Entity
 class Principal(Entity):
     """Represents a user or group that can be assigned permissions to control security."""
 
+    def __str__(self):
+        return self.title
+
+    def __repr__(self):
+        return self.user_principal_name or self.id or self.entity_type_name
+
     @property
     def id(self):
-        """Gets a value that specifies the member identifier for the user or group.
-        :rtype: int or None
-        """
+        # type: () -> Optional[int]
+        """Gets a value that specifies the member identifier for the user or group."""
         return self.properties.get("Id", None)
 
     @property
     def title(self):
-        """Gets a value that specifies the name of the principal.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets a value that specifies the name of the principal."""
         return self.properties.get("Title", None)
 
     @title.setter
     def title(self, value):
+        # type: (str) -> None
         """
         Sets a value that specifies the name of the principal.
-        :type value: str
         """
         self.set_property("Title", value)
 
     @property
     def login_name(self):
-        """Gets the login name of the principal.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the login name of the principal."""
         return self.properties.get("LoginName", None)
 
     @property
     def user_principal_name(self):
-        """Gets the UPN of the principal.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the UPN of the principal."""
         return self.properties.get("UserPrincipalName", None)
 
     @property
     def is_hidden_in_ui(self):
-        """Gets the login name of the principal.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Gets the login name of the principal."""
         return self.properties.get("IsHiddenInUI", None)
 
     @property
     def principal_type(self):
-        """Gets the type of the principal.
-        :rtype: int or None
-        """
+        # type: () -> Optional[int]
+        """Gets the type of the principal."""
         return self.properties.get("PrincipalType", None)
 
     def set_property(self, name, value, persist_changes=True):

office365/sharepoint/principal/users/collection.py

@@ -36,6 +36,11 @@ class UserCollection(EntityCollection[User]):
             _create_and_add_query(user)
         return return_type
 
+    def get_by_principal_name(self, value):
+        # type: (str) -> User
+        """Returns the user with the specified principal name."""
+        return self.single("UserPrincipalName eq '{0}'".format(value))
+
     def get_by_email(self, email):
         """
         Returns the user with the specified e-mail address.