SharePoint API: sharing & permissions namespaces changes

Author: [email protected]

generator/metadata/SharePoint.xml

@@ -0,0 +1,5 @@
+from office365.runtime.clientValue import ClientValue
+
+
+class ObjectIdentity(ClientValue):
+    pass

office365/graph/directory/objectIdentity.py

@@ -0,0 +1,10 @@
+from office365.runtime.clientValue import ClientValue
+
+
+class UserIdentity(ClientValue):
+
+    def __init__(self):
+        super().__init__()
+        self.displayName = None
+        self.ipAddress = None
+        self.userPrincipalName = None

office365/graph/directory/userIdentity.py

@@ -6,7 +6,7 @@ class ClientObject(object):
 
     def __init__(self, context, resource_path=None, properties=None, parent_collection=None):
         """
-        Base client object
+        Base client object which define named properties and relationships of an entity
 
         :type parent_collection: office365.runtime.client_object_collection.ClientObjectCollection or None
         :type properties: dict or None
@@ -25,7 +25,10 @@ def __init__(self, context, resource_path=None, properties=None, parent_collecti
                 self.set_property(k, v, True)
 
     def is_property_available(self, name):
-        """Returns a Boolean value that indicates whether the specified property has been retrieved or set."""
+        """Returns a Boolean value that indicates whether the specified property has been retrieved or set.
+
+        :param str name: A Property name
+        """
         if name in self.properties:
             return True
         return False
@@ -43,8 +46,18 @@ def remove_from_parent_collection(self):
             return
         self._parent_collection.remove_child(self)
 
+    def get_property(self, name):
+        getter_name = name[0].lower() + name[1:]
+        if hasattr(self, getter_name):
+            return getattr(self, getter_name)
+        return self._properties.get(name, None)
+
     def set_property(self, name, value, persist_changes=True):
-        """Set resource property value"""
+        """Sets Property value
+        :param str name: Property name
+        :param any value: Property value
+        :param bool persist_changes: Persist changes
+        """
         if persist_changes:
             self._changes.append(name)
 
@@ -62,15 +75,22 @@ def set_property(self, name, value, persist_changes=True):
     def to_json(self):
         return dict((k, v) for k, v in self.properties.items() if k in self._changes)
 
-    def ensure_property(self, name, action):
+    def ensure_property(self, name_or_names, action):
         """
-        Ensures property is loaded
+        Ensures if property is loaded or list of properties are loaded
 
         :type action: any
-        :type name: str
+        :type name_or_names: str or list[str]
         """
-        if not self.is_property_available(name):
-            self.context.load(self, [name])
+        names_to_include = []
+        if isinstance(name_or_names, list):
+            names_to_include = [n for n in name_or_names if not self.is_property_available(n)]
+        else:
+            if not self.is_property_available(name_or_names):
+                names_to_include.append(name_or_names)
+
+        if len(names_to_include) > 0:
+            self.context.load(self, names_to_include)
             self.context.afterExecuteOnce += action
         else:
             action(self)
@@ -81,10 +101,6 @@ def entity_type_name(self):
             self._entity_type_name = "SP." + type(self).__name__
         return self._entity_type_name
 
-    @entity_type_name.setter
-    def entity_type_name(self, value):
-        self._entity_type_name = value
-
     @property
     def resource_url(self):
         """Generate resource Url"""

office365/runtime/client_object.py

@@ -1,10 +1,15 @@
+import copy
+from office365.runtime.client_object import ClientObject
+
+
 class ClientQuery(object):
     """Client query"""
 
     def __init__(self, binding_type, parameter_type=None, parameter_name=None, return_type=None):
         """
+        Base query
 
-        :type binding_type: ClientObject
+        :type binding_type: office365.runtime.client_object.ClientObject
         :type parameter_type:  ClientObject or ClientValue or dict or bytes or None
         :type parameter_name:  str or None
         :type return_type:  ClientObject or ClientResult or ClientValueObject or None
@@ -38,9 +43,9 @@ def return_type(self):
 class CreateEntityQuery(ClientQuery):
     def __init__(self, parent_entity, create_info, entity_to_create):
         """
-        Create query
+        Create entity query
 
-        :type entity_to_create: ClientObject
+        :type entity_to_create: office365.runtime.client_object.ClientObject
         :type create_info: ClientObject or ClientValue or dict
         :type parent_entity: ClientObject
         """
@@ -50,31 +55,39 @@ def __init__(self, parent_entity, create_info, entity_to_create):
 class ReadEntityQuery(ClientQuery):
     def __init__(self, entity_to_read, properties_to_include=None):
         """
-        Read query
+        Read entity query
 
         :type properties_to_include: list[str] or None
-        :type entity_to_read: ClientObject
+        :type entity_to_read: office365.runtime.client_object.ClientObject
         """
-        super(ReadEntityQuery, self).__init__(entity_to_read, None, None, entity_to_read)
+        binding_type = copy.deepcopy(entity_to_read)
+        super(ReadEntityQuery, self).__init__(binding_type, None, None, entity_to_read)
         if properties_to_include:
-            entity_to_read.query_options.expand = properties_to_include
+            self._include_properties(properties_to_include)
+
+    def _include_properties(self, properties_to_include):
+        for n in properties_to_include:
+            prop_val = self._binding_type.get_property(n)
+            if isinstance(prop_val, ClientObject):
+                self._binding_type.query_options.expand.append(n)
+            self._binding_type.query_options.select.append(n)
 
 
 class UpdateEntityQuery(ClientQuery):
     def __init__(self, entity_to_update):
         """
-        Update query
+        Update entity query
 
-        :type entity_to_update: ClientObject
+        :type entity_to_update: office365.runtime.client_object.ClientObject
         """
         super(UpdateEntityQuery, self).__init__(entity_to_update, entity_to_update, None, None)
 
 
 class DeleteEntityQuery(ClientQuery):
     def __init__(self, entity_to_delete):
         """
-        Delete query
+        Delete entity query
 
-        :type entity_to_delete: ClientObject
+        :type entity_to_delete: office365.runtime.client_object.ClientObject
         """
         super(DeleteEntityQuery, self).__init__(entity_to_delete, None, None, None)

office365/runtime/client_query.py

@@ -5,24 +5,44 @@ def _normalize(key, value):
 
 
 class QueryOptions(object):
-    """OData query options"""
 
-    def __init__(self):
-        self.select = None  # type: list or None
-        self.expand = None  # type: list or None
-        self.filter = None  # type: str or None
-        self.orderBy = None  # type: str or None
-        self.skip = None  # type: int or None
-        self.top = None  # type: int or None
+    def __init__(self, select=None, expand=None, filter_expr=None, orderBy=None, top=None, skip=None):
+        """
+        A query option is a set of query string parameters applied to a resource that can help control the amount
+        of data being returned for the resource in the URL
+
+        :param list[str] select: The $select system query option allows the clients to requests a limited set of
+        properties for each entity or complex type.
+        :param list[str] expand: The $expand system query option specifies the related resources to be included in
+        line with retrieved resources.
+        :param str filter_expr: The $filter system query option allows clients to filter a collection of resources
+        that are addressed by a request URL.
+        :param str orderBy: The $orderby system query option allows clients to request resources in either ascending
+        order using asc or descending order using desc
+        :param int top: The $top system query option requests the number of items in the queried collection to
+        be included in the result.
+        :param int skip: The $skip query option requests the number of items in the queried collection that
+        are to be skipped and not included in the result.
+        """
+        if expand is None:
+            expand = []
+        if select is None:
+            select = []
+        self.select = select
+        self.expand = expand
+        self.filter = filter_expr
+        self.orderBy = orderBy
+        self.skip = skip
+        self.top = top
 
     @property
     def is_empty(self):
-        result = {k: v for (k, v) in self.__dict__.items() if v is not None}
+        result = {k: v for (k, v) in self.__dict__.items() if v is not None and v}
         return not result
 
     def to_url(self):
         """Convert query options to url
         :return: str
         """
         return '&'.join(['$%s=%s' % (key, _normalize(key, value))
-                         for (key, value) in self.__dict__.items() if value is not None])
+                         for (key, value) in self.__dict__.items() if value is not None and value])

office365/runtime/odata/odata_query_options.py

@@ -8,7 +8,7 @@ class ResourcePathServiceOperation(ResourcePath):
 
     def __init__(self, method_name, method_parameters=None, parent=None):
         """
-        :type method_parameters: list or dict or office365.runtime.clientValue.ClientValue
+        :type method_parameters: list or dict or office365.runtime.clientValue.ClientValue or None
         :type method_name: str
 
 

office365/runtime/resource_path_service_operation.py

@@ -120,6 +120,11 @@ def files(self):
             from office365.sharepoint.files.file_collection import FileCollection
             return FileCollection(self.context, ResourcePath("Files", self.resource_path))
 
+    @property
+    def serverRelativeUrl(self):
+        """Gets the server-relative URL of the list folder."""
+        return self.properties.get("ServerRelativeUrl", None)
+
     @property
     def folders(self):
         """Get a folder collection"""

office365/sharepoint/folders/folder.py

@@ -1,16 +1,84 @@
 from office365.runtime.clientValueCollection import ClientValueCollection
 from office365.runtime.client_query import UpdateEntityQuery, DeleteEntityQuery
+from office365.runtime.client_result import ClientResult
 from office365.runtime.resource_path import ResourcePath
 from office365.runtime.resource_path_service_operation import ResourcePathServiceOperation
 from office365.runtime.queries.serviceOperationQuery import ServiceOperationQuery
 from office365.sharepoint.fields.fieldLookupValue import FieldLookupValue
 from office365.sharepoint.fields.fieldMultiLookupValue import FieldMultiLookupValue
 from office365.sharepoint.permissions.securable_object import SecurableObject
+from office365.sharepoint.sharing.externalSharingSiteOption import ExternalSharingSiteOption
+from office365.sharepoint.sharing.objectSharingInformation import ObjectSharingInformation
+from office365.sharepoint.sharing.sharingResult import SharingResult
+from office365.sharepoint.ui.applicationpages.clientPeoplePickerQueryParameters import ClientPeoplePickerQueryParameters
+from office365.sharepoint.ui.applicationpages.clientPeoplePickerWebServiceInterface import \
+    ClientPeoplePickerWebServiceInterface
 
 
 class ListItem(SecurableObject):
     """ListItem resource"""
 
+    def share(self, user_principal_name,
+              shareOption=ExternalSharingSiteOption.View,
+              sendEmail=True, emailSubject=None, emailBody=None):
+        """
+        Share a ListItem (file or folder facet)
+
+        :param str user_principal_name: User identifier
+        :param ExternalSharingSiteOption shareOption: The sharing type of permission to grant on the object.
+        :param bool sendEmail: A flag to determine if an email notification SHOULD be sent (if email is configured).
+        :param str emailSubject: The email subject.
+        :param str emailBody: The email subject.
+        :return: SharingResult
+        """
+
+        result = ClientResult(SharingResult(self.context))
+        file_result = ClientResult(str)
+
+        role_values = {
+            ExternalSharingSiteOption.View: "role:1073741826",
+            ExternalSharingSiteOption.Edit: "role:1073741827",
+        }
+
+        def _property_resolved(target_item):
+            file_result.value = target_item.get_property("EncodedAbsUrl")
+
+        def _picker_value_resolved(picker_value):
+            from office365.sharepoint.webs.web import Web
+            result.value = Web.share_object(self.context, file_result.value, picker_value, role_values[shareOption],
+                                            0,
+                                            False, sendEmail, False, emailSubject, emailBody)
+
+        self.ensure_property("EncodedAbsUrl", _property_resolved)
+        params = ClientPeoplePickerQueryParameters(user_principal_name)
+        ClientPeoplePickerWebServiceInterface.client_people_picker_resolve_user(self.context,
+                                                                                params, _picker_value_resolved)
+        return result.value
+
+    def unshare(self):
+        """
+                Share a ListItem (file or folder facet)
+        """
+        result = ClientResult(SharingResult(self.context))
+
+        def _property_resolved(target_item):
+            abs_url = target_item.get_property("EncodedAbsUrl")
+            from office365.sharepoint.webs.web import Web
+            result.value = Web.unshare_object(self.context, abs_url)
+
+        self.ensure_property("EncodedAbsUrl", _property_resolved)
+        return result.value
+
+    def get_sharing_information(self):
+        result = ClientResult(ObjectSharingInformation(self.context))
+
+        def _item_resolved(return_type):
+            result.value = ObjectSharingInformation.get_list_item_sharing_information(
+                self.context, return_type.parentList.properties["Id"], return_type.properties["Id"])
+
+        self.ensure_property(["Id", "ParentList"], _item_resolved)
+        return result.value
+
     def update(self):
         """Update the list item."""
         self.ensure_type_name(self.parentList)
@@ -89,8 +157,6 @@ def set_property(self, name, value, persist_changes=True):
             if name == "Id" and self._parent_collection:
                 self._resource_path = ResourcePathServiceOperation(
                     "getItemById", [value], self._parent_collection.resource_path.parent)
-            elif name == "GUID":
-                self._resource_path = ResourcePathServiceOperation("GetFileById", [value], self.context.web.resource_path)
 
     def ensure_type_name(self, target_list):
         """