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

office365/directory/permissions/grants/resource_specific.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.object import DirectoryObject
 
 
@@ -9,31 +11,30 @@ class ResourceSpecificPermissionGrant(DirectoryObject):
 
     @property
     def client_id(self):
+        # type: () -> Optional[str]
         """ID of the Azure AD app that has been granted access."""
         return self.properties.get("clientId", None)
 
     @property
     def client_app_id(self):
+        # type: () -> Optional[str]
         """ID of the service principal of the Azure AD app that has been granted access."""
         return self.properties.get("clientAppId", None)
 
     @property
     def permission(self):
-        """The name of the resource-specific permission.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The name of the resource-specific permission."""
         return self.properties.get("permission", None)
 
     @property
     def permission_type(self):
-        """The type of permission. Possible values are: Application, Delegated. Read-only.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The type of permission. Possible values are: Application, Delegated. Read-only."""
         return self.properties.get("permissionType", None)
 
     @property
     def resource_app_id(self):
-        """ID of the Azure AD app that is hosting the resource. Read-only.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """ID of the Azure AD app that is hosting the resource. Read-only."""
         return self.properties.get("resourceAppId", None)

office365/directory/permissions/identity.py

@@ -16,3 +16,6 @@ class Identity(ClientValue):
         super(Identity, self).__init__()
         self.displayName = display_name
         self.id = _id
+
+    def __repr__(self):
+        return repr(self.to_json())

office365/directory/permissions/identity_set.py

@@ -17,3 +17,6 @@ class IdentitySet(ClientValue):
         self.application = application
         self.device = device
         self.user = user
+
+    def __repr__(self):
+        return repr({n: v.to_json() for n, v in self if v.to_json()})

office365/directory/policies/base.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.object import DirectoryObject
 
 
@@ -6,8 +8,6 @@ class PolicyBase(DirectoryObject):
 
     @property
     def display_name(self):
-        """
-        Display name for this policy
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Display name for this policy"""
         return self.properties.get("displayName", None)

office365/directory/policies/root.py

@@ -34,6 +34,7 @@ class PolicyRoot(Entity):
         )
 
     def authentication_strength_policies(self):
+        # type: () -> EntityCollection[AuthenticationStrengthPolicy]
         """
         The authentication method combinations that are to be used in scenarios defined by Azure AD Conditional Access.
         """
@@ -69,6 +70,7 @@ class PolicyRoot(Entity):
 
     @property
     def app_management_policies(self):
+        # type: () -> EntityCollection[AppManagementPolicy]
         """The policies that enforce app management restrictions for specific applications and service principals,
         overriding the defaultAppManagementPolicy."""
         return self.properties.get(
@@ -108,7 +110,8 @@ class PolicyRoot(Entity):
 
     @property
     def permission_grant_policies(self):
-        """ "
+        # type: () -> EntityCollection[PermissionGrantPolicy]
+        """
         The policy that specifies the conditions under which consent can be granted.
         """
         return self.properties.get(
@@ -122,9 +125,8 @@ class PolicyRoot(Entity):
 
     @property
     def conditional_access_policies(self):
-        """ "
-        The custom rules that define an access scenario.
-        """
+        # type: () -> EntityCollection[ConditionalAccessPolicy]
+        """The custom rules that define an access scenario"""
         return self.properties.get(
             "conditionalAccessPolicies",
             EntityCollection(

office365/directory/protection/information.py

@@ -3,6 +3,7 @@ from office365.directory.protection.threatassessment.request import (
 )
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.create_entity import CreateEntityQuery
 
@@ -29,9 +30,7 @@ class InformationProtection(Entity):
         self.threat_assessment_requests.add_child(return_type)
 
         def _construct_request(request):
-            """
-            :type request: office365.runtime.http.request_options.RequestOptions
-            """
+            # type: (RequestOptions) -> None
             request.set_header("Content-Type", "application/json")
 
         def _create_and_add_query():
@@ -51,6 +50,7 @@ class InformationProtection(Entity):
 
     @property
     def threat_assessment_requests(self):
+        # type: () -> EntityCollection[ThreatAssessmentRequest]
         """"""
         return self.properties.get(
             "threatAssessmentRequests",

office365/directory/rolemanagement/application.py

@@ -17,6 +17,7 @@ class RbacApplication(Entity):
 
     @property
     def role_assignments(self):
+        # type: () -> EntityCollection[UnifiedRoleAssignment]
         """Resource to grant access to users or groups."""
         return self.properties.get(
             "roleAssignments",
@@ -28,6 +29,7 @@ class RbacApplication(Entity):
         )
 
     def role_definitions(self):
+        # type: () -> EntityCollection[UnifiedRoleDefinition]
         """Resource representing the roles allowed by RBAC providers and the permissions assigned to the roles."""
         return self.properties.get(
             "roleDefinitions",

office365/directory/rolemanagement/role.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.object import DirectoryObject
 from office365.runtime.paths.resource_path import ResourcePath
 
@@ -6,27 +8,26 @@ class DirectoryRole(DirectoryObject):
     """Represents an Azure AD directory role. Azure AD directory roles are also known as administrator roles"""
 
     def __repr__(self):
-        return self.display_name
+        return self.id or self.entity_type_name
+
+    def __str__(self):
+        return "Name: {0}".format(self.display_name)
 
     @property
     def description(self):
-        """The description for the directory role.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The description for the directory role."""
         return self.properties.get("Description", None)
 
     @property
     def display_name(self):
-        """The display name for the directory role.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The display name for the directory role."""
         return self.properties.get("displayName", None)
 
     @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

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.object import DirectoryObject
 
 
@@ -5,18 +7,17 @@ class DirectoryRoleTemplate(DirectoryObject):
     """Represents a directory role template. A directory role template specifies the property values of a directory
     role (directoryRole)."""
 
+    def __repr__(self):
+        return self.display_name
+
     @property
     def display_name(self):
-        """
-        The display name to set for the directory role
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The display name to set for the directory role"""
         return self.properties.get("displayName", None)
 
     @property
     def description(self):
-        """
-        The display name to set for the directory role
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """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 @@ class UnifiedRoleDefinition(Entity):
 
     @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/security/security.py

@@ -17,6 +17,7 @@ class Security(Entity):
 
     @property
     def alerts(self):
+        # type: () -> EntityCollection[Alert]
         return self.properties.get(
             "alerts",
             EntityCollection(
@@ -26,6 +27,7 @@ class Security(Entity):
 
     @property
     def alerts_v2(self):
+        # type: () -> EntityCollection[Alert]
         """
         A collection of alerts in Microsoft 365 Defender.
         """
@@ -55,6 +57,7 @@ class Security(Entity):
 
     @property
     def incidents(self):
+        # type: () -> EntityCollection[Incident]
         """A collection of correlated alert instances and associated metadata that reflects the story of
         an attack in a tenant"""
         return self.properties.get(

office365/directory/serviceprincipals/collection.py

@@ -1,9 +1,10 @@
 from office365.delta_collection import DeltaCollection
+from office365.directory.applications.application import Application
 from office365.directory.serviceprincipals.service_principal import ServicePrincipal
 from office365.runtime.paths.appid import AppIdPath
 
 
-class ServicePrincipalCollection(DeltaCollection):
+class ServicePrincipalCollection(DeltaCollection[ServicePrincipal]):
     """Service Principal's collection"""
 
     def __init__(self, context, resource_path=None):
@@ -14,15 +15,30 @@ class ServicePrincipalCollection(DeltaCollection):
     def add(self, app_id):
         """
         Create a new servicePrincipal object.
-
         :param str app_id: The unique identifier for the associated application
-        :rtype: ServicePrincipal
         """
         return super(ServicePrincipalCollection, self).add(appId=app_id)
 
     def get_by_app_id(self, app_id):
         """Retrieves the service principal using appId.
-
         :param str app_id: appId is referred to as Application (Client) ID, respectively, in the Azure portal
         """
         return ServicePrincipal(self.context, AppIdPath(app_id, self.resource_path))
+
+    def get_by_app(self, app):
+        # type: (str|Application) -> ServicePrincipal
+        if isinstance(app, Application):
+            return_type = ServicePrincipal(self.context, parent_collection=self)
+
+            def _app_resolved():
+                return_type.set_property("appId", app.app_id)
+
+            app.ensure_properties(["appId"], _app_resolved)
+            return return_type
+        else:
+            return self.get_by_app_id(app)
+
+    def get_by_name(self, name):
+        # type: (str) -> ServicePrincipal
+        """Retrieves the service principal using displayName."""
+        return self.single("displayName eq '{0}'".format(name))

office365/directory/serviceprincipals/service_principal.py

@@ -1,9 +1,13 @@
 from typing import Optional
 
+from typing_extensions import Self
+
 from office365.delta_collection import DeltaCollection
+from office365.directory.applications.application import Application
 from office365.directory.applications.roles.assignment_collection import (
     AppRoleAssignmentCollection,
 )
+from office365.directory.applications.roles.collection import AppRoleCollection
 from office365.directory.applications.roles.role import AppRole
 from office365.directory.certificates.self_signed import SelfSignedCertificate
 from office365.directory.key_credential import KeyCredential
@@ -15,6 +19,7 @@ from office365.directory.permissions.scope import PermissionScope
 from office365.directory.synchronization.synchronization import Synchronization
 from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value_collection import ClientValueCollection
+from office365.runtime.paths.appid import AppIdPath
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.types.collections import StringCollection
@@ -23,6 +28,9 @@ from office365.runtime.types.collections import StringCollection
 class ServicePrincipal(DirectoryObject):
     """Represents an instance of an application in a directory."""
 
+    def __str__(self):
+        return self.display_name
+
     def add_key(self, key_credential, password_credential, proof):
         """
         Adds a key credential to a servicePrincipal. This method along with removeKey can be used by a servicePrincipal
@@ -32,8 +40,9 @@ class ServicePrincipal(DirectoryObject):
             The type, usage and key are required properties for this usage. Supported key types are:
                 AsymmetricX509Cert: The usage must be Verify.
                 X509CertAndPassword: The usage must be Sign
-        :param PasswordCredential password_credential: Only secretText is required to be set which should contain the password
-             for the key. This property is required only for keys of type X509CertAndPassword. Set it to null otherwise.
+        :param PasswordCredential password_credential: Only secretText is required to be set which should contain
+            the password for the key. This property is required only for keys of type X509CertAndPassword.
+            Set it to null otherwise.
         :param str proof: A self-signed JWT token used as a proof of possession of the existing keys
         """
         payload = {
@@ -92,6 +101,56 @@ class ServicePrincipal(DirectoryObject):
         self.context.add_query(qry)
         return return_type
 
+    def grant(self, app, app_role):
+        # type: (Application|str, AppRole|str) -> Self
+        """
+        Revokes an app role assignment to a client service principal
+        :param Application or str app: Application object or app identifier
+        :param AppRole or str app_role: AppRole object or name
+        """
+
+        def _grant(principal):
+            # type: ("ServicePrincipal") -> None
+            app_role_id = repr(app_role)
+            principal_id = principal.id
+            self.app_role_assigned_to.add(
+                principalId=principal_id, resourceId=self.id, appRoleId=app_role_id
+            )
+
+        def _ensure_principal():
+            self.context.service_principals.get_by_app(app).get().after_execute(_grant)
+
+        self.ensure_property("id", _ensure_principal)
+        return self
+
+    def revoke(self, app, app_role):
+        # type: (Application|str, AppRole|str) -> Self
+        """Revokes an app role assignment from a client service principal"""
+
+        def _revoke(principal):
+            # type ("ServicePrincipal") -> None
+            principal_id = principal.id
+            app_role_id = repr(app_role)
+            app_role_assigned_to_ids = [
+                item.id
+                for item in self.app_role_assigned_to
+                if item.principal_id == principal_id and item.app_role_id == app_role_id
+            ]
+            if len(app_role_assigned_to_ids) > 0:
+                self.app_role_assigned_to[app_role_assigned_to_ids[0]].delete_object()
+
+        def _ensure_resource(principal):
+            self.ensure_properties(["id", "appRoleAssignedTo"], _revoke, principal)
+            # self.app_role_assigned_to.get_all(page_loaded=_revoke)
+
+        def _ensure_principal():
+            self.context.service_principals.get_by_app(app).get().after_execute(
+                _ensure_resource
+            )
+
+        self.ensure_property("id", _ensure_principal)
+        return self
+
     def remove_password(self, key_id):
         """
         Remove a password from a servicePrincipal object.
@@ -129,9 +188,7 @@ class ServicePrincipal(DirectoryObject):
     @property
     def app_display_name(self):
         # type: () -> Optional[str]
-        """
-        The display name exposed by the associated application.
-        """
+        """The display name exposed by the associated application."""
         return self.properties.get("appDisplayName", None)
 
     @property
@@ -151,14 +208,18 @@ class ServicePrincipal(DirectoryObject):
         """
         The roles exposed by the application which this service principal represents.
         """
-        return self.properties.get("appRoles", ClientValueCollection(AppRole))
+        return self.properties.get("appRoles", AppRoleCollection())
+
+    @property
+    def display_name(self):
+        # type: () -> Optional[str]
+        """The display name."""
+        return self.properties.get("displayName", None)
 
     @property
     def homepage(self):
         # type: () -> Optional[str]
-        """
-        Home page or landing page of the application.
-        """
+        """Home page or landing page of the application"""
         return self.properties.get("homepage", None)
 
     @property
@@ -184,10 +245,10 @@ class ServicePrincipal(DirectoryObject):
 
     @property
     def logout_url(self):
+        # type: () -> Optional[str]
         """
         Specifies the URL that will be used by Microsoft's authorization service to logout an user using
         OpenId Connect front-channel, back-channel or SAML logout protocols.
-        :rtype: str
         """
         return self.properties.get("logoutUrl", None)
 
@@ -202,6 +263,7 @@ class ServicePrincipal(DirectoryObject):
 
     @property
     def service_principal_type(self):
+        # type: () -> Optional[str]
         """
         Identifies whether the service principal represents an application, a managed identity, or a legacy application.
         This is set by Azure AD internally. The servicePrincipalType property can be set to three different values:
@@ -220,8 +282,6 @@ class ServicePrincipal(DirectoryObject):
             but does not have an associated app registration. The appId value does not associate
             the service principal with an app registration.
             The service principal can only be used in the tenant where it was created.
-
-        :rtype: str or None
         """
         return self.properties.get("servicePrincipalType", None)
 
@@ -249,6 +309,7 @@ class ServicePrincipal(DirectoryObject):
 
     @property
     def oauth2_permission_grants(self):
+        # type: () -> DeltaCollection[OAuth2PermissionGrant]
         """"""
         return self.properties.get(
             "oauth2PermissionGrants",
@@ -294,6 +355,7 @@ class ServicePrincipal(DirectoryObject):
 
     @property
     def token_encryption_key_id(self):
+        # type: () -> Optional[str]
         """
         Specifies the keyId of a public key from the keyCredentials collection. When configured, Azure AD issues tokens
         for this application encrypted using the key specified by this property. The application code that receives
@@ -315,3 +377,8 @@ class ServicePrincipal(DirectoryObject):
             }
             default_value = property_mapping.get(name, None)
         return super(ServicePrincipal, self).get_property(name, default_value)
+
+    def set_property(self, name, value, persist_changes=True):
+        if self._resource_path is None and name == "appId":
+            self._resource_path = AppIdPath(value, self.parent_collection.resource_path)
+        return super(ServicePrincipal, self).set_property(name, value, persist_changes)

office365/directory/users/activities/activity.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from typing import Optional
 
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
@@ -15,14 +16,15 @@ class UserActivity(Entity):
 
     @property
     def activation_url(self):
+        # type: () -> Optional[str]
         """URL used to launch the activity in the best native experience represented by the appId.
         Might launch a web-based app if no native app exists
-        :rtype: str or None
         """
         return self.properties.get("activationUrl", None)
 
     @property
     def activity_source_host(self):
+        # type: () -> Optional[str]
         """Required. URL for the domain representing the cross-platform identity mapping for the app.
         Mapping is stored either as a JSON file hosted on the domain or configurable via Windows Dev Center.
         The JSON file is named cross-platform-app-identifiers and is hosted at root of your HTTPS domain,
@@ -30,24 +32,23 @@ class UserActivity(Entity):
         For example: https://contoso.com or https://myapp.contoso.com but NOT https://myapp.contoso.com/somepath.
         You must have a unique file and domain (or sub domain) per cross-platform app identity.
         For example, a separate file and domain is needed for Word vs. PowerPoint.
-        :rtype: str or None
         """
         return self.properties.get("activitySourceHost", None)
 
     @property
     def app_activity_id(self):
+        # type: () -> Optional[str]
         """
         The unique activity ID in the context of the app - supplied by caller and immutable thereafter.
-        :rtype: str
         """
         return self.properties.get("appActivityId", None)
 
     @property
     def app_display_name(self):
+        # type: () -> Optional[str]
         """
         Short text description of the app used to generate the activity for use in cases when the app is
         not installed on the user’s local device.
-        :rtype: str
         """
         return self.properties.get("appDisplayName", None)