sharepoint-rest-api 0.20.1__py3-none-any.whl

sharepoint_rest_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.18"

sharepoint_rest_api/admin.py

@@ -0,0 +1,23 @@
+from django.contrib import admin
+
+from .models import SharePointLibrary, SharePointSite, SharePointTenant
+
+
+@admin.register(SharePointTenant)
+class SharepointTenantAdmin(admin.ModelAdmin):
+    search_fields = ("url",)
+    list_display = ("url",)
+
+
+@admin.register(SharePointSite)
+class SharepointSiteAdmin(admin.ModelAdmin):
+    search_fields = ("name",)
+    list_display = ("name", "site_type", "tenant")
+    list_filter = ("site_type", "tenant")
+
+
+@admin.register(SharePointLibrary)
+class DocumentLibraryAdmin(admin.ModelAdmin):
+    search_fields = ("name",)
+    list_display = ("name", "site", "active", "public")
+    list_filter = ("active", "public")

sharepoint_rest_api/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig as BaseAppConfig
+
+
+class AppConfig(BaseAppConfig):
+    name = __name__.rpartition(".")[0]
+    verbose_name = "SharePoint Rest API"

sharepoint_rest_api/builders/camlquery_builder.py

@@ -0,0 +1,89 @@
+import logging
+
+from office365.sharepoint.listitems.caml.query import CamlQuery
+from office365.sharepoint.views.scope import ViewScope
+
+from sharepoint_rest_api.utils import to_camel
+
+logger = logging.getLogger(__name__)
+
+
+def recursive_builder(queries, operator="And"):
+    if queries:
+        query = queries.pop()
+        if len(queries) == 0:
+            return query
+        if len(queries) == 1:
+            last_query = queries.pop()
+            return f"<{operator}>" + query + last_query + f"</{operator}>"
+        return f"<{operator}>" + query + recursive_builder(queries, operator) + f"</{operator}>"
+    return ""
+
+
+class CamlQueryBuilder:
+    """Helper Class to create queries in CamlQuery format."""
+
+    date_operators = ["Geq", "Gt", "Leq", "Lt"]
+    mapping_operator = {
+        "gte": "Geq",
+        "gt": "Gt",
+        "lte": "Leq",
+        "lt": "Lt",
+        "not": "Neq",
+        "contains": "Contains",
+        "eq": "Eq",
+    }
+
+    def __init__(self, filters=None, scope=None):
+        super().__init__()
+        self.scope = scope
+        self.filters = {} if filters is None else filters
+
+    def create_query(self):
+        where_condition = ""
+
+        if self.filters.keys():
+            filter_queries = []
+            for base_filter_name, filter_value in self.filters.items():
+                querystring_operator = base_filter_name.split("__")[-1]
+                operator = self.mapping_operator.get(querystring_operator, "Eq")
+
+                filter_name = to_camel(base_filter_name.split("__")[0])
+                if operator in self.date_operators:
+                    column_type, value = (
+                        "DateTime",
+                        f"{filter_value}T00:00:00Z",
+                    )  # 2016-03-26
+                    query = (
+                        f'<{operator}><FieldRef Name="{filter_name}" />'
+                        f'<Value Type="{column_type}">{value}</Value>'
+                        f"</{operator}>"
+                    )
+                elif operator == "Contains":
+                    column_type = "Text"
+                    query = (
+                        f'<{operator}><FieldRef Name="{filter_name}" />'
+                        f'<Value Type="{column_type}">{filter_value}</Value>'
+                        f"</{operator}>"
+                    )
+                else:
+                    column_type, values = "Text", filter_value.split(",")
+                    queries = [
+                        (
+                            f'<{operator}><FieldRef Name="{filter_name}" />'
+                            f'<Value Type="{column_type}">{value}</Value>'
+                            f"</{operator}>"
+                        )
+                        for value in values
+                    ]
+                    query = recursive_builder(queries, "Or")
+                filter_queries.append(query)
+            where_condition = recursive_builder(filter_queries)
+            if len(filter_queries) > 1:
+                where_condition = f"<And>{where_condition}</And>"
+
+        scope = f' Scope="{self.scope}"' if self.scope else ""
+        return f"<View{scope}><Query><Where>{where_condition}</Where></Query></View>"
+
+    def get_query(self):
+        return CamlQuery.parse(self.create_query(), ViewScope.RecursiveAll)

sharepoint_rest_api/builders/querystring_builder.py

@@ -0,0 +1,51 @@
+import logging
+
+from sharepoint_rest_api.utils import to_camel
+
+logger = logging.getLogger(__name__)
+
+
+class QueryStringBuilder:
+    """Helper class to create sharepoint querystring."""
+
+    date_operators = ["ge", "gt", "le", "lt"]
+    mapping_operator = {
+        "gte": "ge",
+        "gt": "gt",
+        "lte": "le",
+        "lt": "lt",
+        "not": "ne",
+        "contains": "substringof",
+    }
+    search = []
+
+    def __init__(self, filters=None):
+        super().__init__()
+        self.filters = {} if filters is None else filters
+
+    def get_filter_querystring(self):
+        filter_queries = []
+        for base_filter_name, filter_value in self.filters.items():
+            # operator
+            querystring_operator = base_filter_name.split("__")[-1]
+            operator = self.mapping_operator.get(querystring_operator, "eq")
+            # filter
+            filter_name = to_camel(base_filter_name.split("__")[0])
+            if operator in self.date_operators:
+                values = [f"{filter_value}T00:00:00Z"]  # 2016-03-26
+                query = " or ".join([f"{filter_name} {operator} datetime'{value}'" for value in values])
+            elif operator == "substringof":
+                values = filter_value.split(",")
+                query = " or ".join([f"{operator}('{value}', {filter_name})" for value in values])
+
+            else:
+                values = filter_value.split(",")
+                query = " or ".join([f"{filter_name} {operator} '{value}'" for value in values])
+                if len(values) > 1:
+                    query = f"({query})"
+            filter_queries.append(query)
+            logger.info(query)
+        return str(" and ".join(filter_queries))
+
+    def get_querystring(self):
+        return self.get_filter_querystring() or ""

sharepoint_rest_api/builders/rest_builder.py

@@ -0,0 +1,90 @@
+import logging
+
+from sharepoint_rest_api import config
+
+logger = logging.getLogger(__name__)
+
+GRAPH_URL = "https://graph.microsoft.com/v1.0"
+GRAPH_SEARCH_URL = "https://graph.microsoft.com/v1.0/search/query"
+GRAPH_SCOPE = ["https://graph.microsoft.com/.default"]
+
+
+class RestBuilderError(Exception):
+    """Exception when communicating with the Graph API."""
+
+
+class RestBuilder:
+    """Builds JSON request bodies for Microsoft Graph API queries.
+
+    Provides static methods to construct Graph API request payloads,
+    including KQL query strings and structured JSON bodies for the
+    search and batch endpoints.  Does not perform any HTTP calls.
+    """
+
+    @staticmethod
+    def build_kql_clause(qs_filter_name, filter_value):
+        """Build a single KQL clause from a filter expression."""
+        parts = qs_filter_name.split("__")
+        raw_name = parts[0]
+        operator_key = parts[-1] if len(parts) > 1 else "eq"
+
+        kql_op_map = {
+            "not": "<>",
+            "contains": ":",
+            "eq": ":",
+            "gte": ">=..",
+            "gt": ">..",
+            "lte": "..<=",
+            "lt": "..<",
+            "between": "..",
+        }
+        kql_op = kql_op_map.get(operator_key, ":")
+        values = [v.strip() for v in filter_value.split(",")]
+
+        if operator_key == "not_in":
+            return [f'-"{v}"' for v in values]
+        if operator_key == "contains":
+            return [f'{raw_name}:"{values[0]}*"']
+        if kql_op == "<>":
+            return [f'{raw_name}<>"{values[0]}"']
+        if len(values) == 1:
+            return [f'{raw_name}:"{values[0]}"']
+        or_parts = [f'"{v}"' for v in values]
+        return [f"{raw_name}:({' OR '.join(or_parts)})"]
+
+    @staticmethod
+    def build_kql(search=None, filters=None):
+        """Build a KQL query string from already-mapped managed property names.
+
+        Filters dict keys are managed property names (mapped by caller).
+        Supports DRF-style operators (__not, __contains) and multi-value.
+        """
+        if filters is None:
+            filters = {}
+
+        clauses = []
+        for qs_filter_name, filter_value in filters.items():
+            clauses.extend(RestBuilder.build_kql_clause(qs_filter_name, filter_value))
+
+        if not clauses:
+            return search or "*"
+        if search:
+            return f"{search} AND {' AND '.join(clauses)}"
+        return " AND ".join(clauses)
+
+    @staticmethod
+    def build_search_request_body(kql, start_row, page_size):
+        """Build the JSON POST body for a Graph Search API request."""
+        request_body = {
+            "entityTypes": ["driveItem"],
+            "query": {"queryString": kql},
+            "region": config.GRAPH_REGION,
+            "from": start_row,
+            "size": page_size,
+        }
+        return {"requests": [request_body]}
+
+    @staticmethod
+    def build_batch_body(requests):
+        """Build the JSON POST body for a Graph batch request."""
+        return {"requests": requests[:20]}

sharepoint_rest_api/builders/search_request_builder.py

@@ -0,0 +1,86 @@
+from office365.sharepoint.search.query.sort.sort import Sort
+
+from sharepoint_rest_api import config
+from sharepoint_rest_api.utils import to_camel
+
+
+class SearchRequestBuilder:
+    """Helper class to build queries in Keyword Query Language (KQL)."""
+
+    select = None
+
+    mapping_operator = {
+        "gte": ">=",
+        "gt": ">",
+        "lte": "<=",
+        "lt": "<",
+        "not": "<>",
+        "not_in": ":",
+        "eq": ":",
+        "between": "..",
+        "contains": "*",
+    }
+
+    def __init__(  # noqa
+        self,
+        search=None,
+        filters=None,
+        select=None,
+        order_by=None,
+        source_id=None,
+        start_row=None,
+    ):  # noqa
+        self.search = search
+        self.filters = {} if filters is None else filters
+        self.select = select
+        self.order_by = order_by
+        self.source_id = source_id
+        self.start_row = start_row
+
+    def get_select_properties(self):
+        return self.select
+
+    def get_order_by(self):
+        if self.order_by:
+            order = to_camel(self.order_by).split(",")
+            return [Sort(item[1:], 1) if item.startswith("-") else Sort(item, 0) for item in order]
+        return None
+
+    def get_query(self):
+        filter_queries = []
+        if self.filters.keys():
+            filter_queries = []
+            for qs_filter_name, filter_value in self.filters.items():
+                filter_name = qs_filter_name.split("__")[0]
+                querystring_operator = qs_filter_name.split("__")[-1]
+                operator = self.mapping_operator.get(querystring_operator, ":")
+                if operator == "..":
+                    filter_value_from, filter_value_to = filter_value.split("__")
+                    query = f"{filter_name}:{filter_value_from}{operator}{filter_value_to}"
+                elif operator == "*":
+                    query = f'{filter_name}:"{filter_value}{operator}"'
+                else:
+                    values = filter_value.split(",")
+                    if querystring_operator == "not_in":
+                        filter_values = "(" + " ".join([f'-"{value}"' for value in values]) + ")"
+                    elif len(values) == 1:
+                        filter_values = f'"{values[0]}"'
+                    else:
+                        filter_values = "(" + " OR ".join([f'"{value}"' for value in values]) + ")"
+                    query = f"{filter_name}{operator}{filter_values}"
+                filter_queries.append(query)
+        if not filter_queries:
+            return f"{self.search}" if self.search else "*"
+        qry = " AND ".join(f"{query}" for query in filter_queries)
+        return f"{self.search} {qry}" if self.search else qry
+
+    def build(self):
+        return {
+            "query_text": self.get_query(),
+            "sort_list": self.get_order_by(),
+            "select_properties": self.get_select_properties(),
+            "start_row": self.start_row,
+            "row_limit": config.SHAREPOINT_PAGE_SIZE,
+            "trim_duplicates": False,
+            "SourceId": self.source_id,
+        }

sharepoint_rest_api/client.py

@@ -0,0 +1,214 @@
+import logging
+
+from office365.runtime.auth.client_credential import ClientCredential
+from office365.runtime.auth.user_credential import UserCredential
+from office365.sharepoint.client_context import ClientContext
+from office365.sharepoint.files.creation_information import FileCreationInformation
+from office365.sharepoint.files.file import File
+from office365.sharepoint.search.service import SearchService
+
+from sharepoint_rest_api import config
+from sharepoint_rest_api.builders.camlquery_builder import CamlQueryBuilder
+from sharepoint_rest_api.builders.querystring_builder import QueryStringBuilder
+from sharepoint_rest_api.builders.search_request_builder import SearchRequestBuilder
+from sharepoint_rest_api.config import SHAREPOINT_PAGE_SIZE
+
+logger = logging.getLogger(__name__)
+
+
+default_select = ["*", "FileLeafRef"]
+
+
+class SharePointClientException(BaseException):
+    """SharePoint Exception when initializing the client."""
+
+
+class SharePointClient:
+    """Client to access SharePoint Document Library."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        self.relative_url = kwargs.get("relative_url")
+        self.site_path = kwargs.get("url", config.SHAREPOINT_TENANT)
+        if config.SHAREPOINT_CONNECTION == "app":
+            client_id = kwargs.get("client_id", config.SHAREPOINT_CLIENT_ID)
+            client_secret = kwargs.get("client_secret", config.SHAREPOINT_CLIENT_SECRET)
+            credentials = ClientCredential(client_id, client_secret)
+        elif config.SHAREPOINT_CONNECTION == "user":
+            username = kwargs.get("username", config.SHAREPOINT_USERNAME)
+            password = kwargs.get("password", config.SHAREPOINT_PASSWORD)
+            credentials = UserCredential(username, password)
+        else:
+            raise SharePointClientException("Invalid connection type")
+        self.folder = kwargs.get("folder", "Documents")
+        self.context = ClientContext(self.site_path).with_credentials(credentials)
+
+    def __reduce__(self):
+        return SharePointClient, (
+            self.relative_url,
+            self.site_path,
+            self.folder,
+        )
+
+    def get_folder(self, folder_name):
+        """Return folder object.
+
+        :param folder_name: name of the folder
+        :return: folder object
+        """
+        list_obj = self.context.web.lists.get_by_title(folder_name)
+        folder = list_obj.root_folder
+        self.context.load(folder)
+        self.context.execute_query()
+        logger.info(f"List url: {folder.properties['ServerRelativeUrl']}")
+        return folder
+
+    def read_folders(self, folder_name):
+        """Return folders metadata for subfolder of current folder.
+
+        :param folder_name:
+        :return: folders
+        """
+        self.get_folder(folder_name)
+        folders = self.context.web.folders
+        self.context.load(folders)
+        self.context.execute_query()
+        for folder in folders:
+            logger.info(f"Folder name: {folder.properties['Name']}")
+        return folders
+
+    def read_files(self, filters=None):
+        """Return files metadata for files in current folder.
+
+        :param filters:
+        :return: files
+        """
+        filters = {} if filters is None else filters
+        querystring = QueryStringBuilder(filters).get_querystring()
+        folder = self.get_folder(self.folder)
+        files = folder.files.filter(querystring)
+        self.context.load(files)
+        self.context.execute_query()
+        for cur_file in files:
+            logger.info(f"File name: {cur_file.properties['Name']}")
+
+        return files
+
+    def read_items(self, filters=None, select=None):
+        """Retrieve (filtered) items on current folder using querystring.
+
+        :param filters: filter dictionary
+        :param scope: SharePoint scope
+        :return: items
+        """
+        filters = {} if filters is None else filters
+        querystring = QueryStringBuilder(filters).get_querystring()
+        list_object = self.context.web.lists.get_by_title(self.folder)
+        select_string = select or default_select
+        items = list_object.get_items().filter(querystring).select(select_string)
+        self.context.load(items)
+        self.context.execute_query()
+        return items
+
+    def read_file(self, filename):
+        """Retrieve file in current folder.
+
+        :param filename: filename
+        :return:
+        """
+        folder = self.get_folder(self.folder)
+        cur_file = folder.files.get_by_url(f"/{self.relative_url}/{self.folder}/{filename}")
+        self.context.load(cur_file)
+        self.context.execute_query()
+        logger.info(f"File name: {cur_file.properties['Name']}")
+        return cur_file
+
+    def read_caml_items(self, filters=None, scope=None):
+        """Retrieve (filtered) items on current folder using CamlQueries.
+
+        :param filters: filter dictionary
+        :param scope: SharePoint scope
+        :return: items
+        """
+        filters = {} if filters is None else filters
+        list_obj = self.context.web.lists.get_by_title(self.folder)
+        qry = CamlQueryBuilder(filters, scope).get_query()
+        items = list_obj.get_items(qry)
+        self.context.execute_query()
+        return items
+
+    def search(  # noqa
+        self,
+        search=None,
+        filters=None,
+        select=None,
+        order_by=None,
+        source_id=None,
+        page=1,
+    ):
+        """Search file in the SharePoint site.
+
+        :param filter: filter dictionary
+        :param select: select string
+        :param order_by: SharePoint order fields
+        :param source_id: SharePoint SourceId
+        :return: items and total row number
+        """
+        filters = {} if filters is None else filters
+        search_service = SearchService(self.context)
+        query = SearchRequestBuilder(
+            search,
+            filters,
+            select,
+            order_by,
+            source_id,
+            (page - 1) * SHAREPOINT_PAGE_SIZE,
+        ).build()
+        result = search_service.post_query(**query)
+        self.context.execute_query()
+        relevant_results = result.value.PrimaryQueryResult.RelevantResults
+        results = relevant_results.Table.Rows
+        logger.info(f"Retrieved: {relevant_results.TotalRows} results")
+        items = [item.Cells for item in results]
+        return items, relevant_results.TotalRows
+
+    def upload_file_alt(self, target_folder, name, content):
+        context = target_folder.context
+        info = FileCreationInformation()
+        info.content = content
+        info.url = name
+        info.overwrite = True
+        target_file = target_folder.files.add(info)
+        context.execute_query()
+        return target_file
+
+    def upload_file(self, file, folder_name="Documents", metadata=None):
+        """Upload a file to SharePoint.
+
+        :param path: inmemory file
+        :param folder_name: name of the folder
+        :param metadata: metadata dictionary
+        :return:
+        """
+        metadata = {} if metadata is None else metadata
+        file_content = file.read()
+        target_folder = self.context.web.lists.get_by_title(folder_name).root_folder
+        target_file = target_folder.upload_file(file.name, file_content).execute_query()
+        logger.info(f"File has been uploaded to url: {target_file.serverRelativeUrl}")
+        context = target_folder.context
+        item = target_file.listItemAllFields
+        for key, value in metadata.items():
+            item.set_property(name=key, value=value)
+        item.update()
+        context.execute_query()
+
+    def download_file(self, filename):
+        """Open a file for downloading.
+
+        :param filename: name of the file to download
+        :return:
+
+        download file in current folder
+        """
+        response = File.open_binary(self.context, f"/{self.folder}/{filename}")
+        with open(f"./data/{filename}", "wb") as local_file:
+            local_file.write(response.content)

sharepoint_rest_api/config.py

@@ -0,0 +1,24 @@
+import os
+
+from django.conf import settings
+
+
+def env_or_settings(name, default):
+    return os.environ.get(name, getattr(settings, name, default))
+
+
+SHAREPOINT_TENANT = env_or_settings("SHAREPOINT_TENANT", "https://unitst.sharepoint.com")
+SHAREPOINT_SITE = env_or_settings("SHAREPOINT_SITE", "GLB-DRP")
+SHAREPOINT_SITE_TYPE = env_or_settings("SHAREPOINT_SITE_TYPE", "sites")
+SHAREPOINT_CONNECTION = env_or_settings("SHAREPOINT_CONNECTION", "app")
+SHAREPOINT_CLIENT_ID = env_or_settings("SHAREPOINT_CLIENT_ID", "invalid_client_id")
+SHAREPOINT_CLIENT_SECRET = env_or_settings("SHAREPOINT_CLIENT_SECRET", "invalid_client_secret")
+SHAREPOINT_USERNAME = env_or_settings("SHAREPOINT_USERNAME", "invalid_username")
+SHAREPOINT_PASSWORD = env_or_settings("SHAREPOINT_PASSWORD", "invalid_password")
+SHAREPOINT_PAGE_SIZE = int(env_or_settings("SHAREPOINT_PAGE_SIZE", 25))
+
+GRAPH_CLIENT_ID = env_or_settings("GRAPH_CLIENT_ID", "invalid_graph_client_id")
+GRAPH_CLIENT_SECRET = env_or_settings("GRAPH_CLIENT_SECRET", "invalid_graph_client_secret")
+GRAPH_TENANT = env_or_settings("GRAPH_TENANT", "")
+GRAPH_REGION = env_or_settings("GRAPH_REGION", "US")
+GRAPH_PAGE_SIZE = int(env_or_settings("GRAPH_PAGE_SIZE", 25))

sharepoint_rest_api/filters.py

@@ -0,0 +1,14 @@
+from django_filters import rest_framework as filters
+
+from sharepoint_rest_api.models import SharePointLibrary
+
+
+class SharePointLibraryFilter(filters.FilterSet):
+    class Meta:
+        model = SharePointLibrary
+        fields = {
+            "site": ["exact", "in"],
+            "active": [
+                "exact",
+            ],
+        }