sda.api.graph_client
====================

.. py:module:: sda.api.graph_client

.. autoapi-nested-parse::

   MS Graph API client for SharePoint file access.



Attributes
----------

.. autoapisummary::

   sda.api.graph_client.GRAPH_BASE


Classes
-------

.. autoapisummary::

   sda.api.graph_client.GraphClient


Functions
---------

.. autoapisummary::

   sda.api.graph_client.download_presigned_graph_url


Module Contents
---------------

.. py:data:: GRAPH_BASE
   :value: 'https://graph.microsoft.com/v1.0'


.. py:function:: download_presigned_graph_url(url, destination, *, timeout = 300.0, max_attempts = 3)

   Download from ``@microsoft.graph.downloadUrl`` without an Authorization header.

   The URL is already authenticated (temporary SAS). Uses HTTP/1.1 only, a
   normal User-Agent, and limited retries for transient connection resets.


.. py:class:: GraphClient(tenant_id, client_id, client_secret)

   Client for interacting with SharePoint via MS Graph API.


   .. py:method:: download_file(site_id, drive_id, item_path, destination)

      Download a file from SharePoint and save to destination.

      :param site_id: SharePoint site ID.
      :type site_id: :py:class:`str`
      :param drive_id: Drive ID within the site.
      :type drive_id: :py:class:`str`
      :param item_path: Path to the item within the drive root (e.g. ``"Gif/T297/T297.xlsm"``).
      :type item_path: :py:class:`str`
      :param destination: Local path to write the downloaded file.
      :type destination: :py:class:`Path`

      :returns: The ``destination`` path after writing.
      :rtype: :py:class:`Path`

      .. rubric:: Notes

      Uses the ``@microsoft.graph.downloadUrl`` pre-signed URL from the item
      metadata rather than the ``/content`` redirect endpoint.  The
      ``/content`` endpoint issues a 302 to Azure Blob Storage; following it
      with an ``Authorization`` header causes a ``WinError 10054`` connection
      reset because Blob Storage uses SAS-based auth, not Bearer tokens.



   .. py:method:: list_folder_children(site_id, drive_id, folder_path, filename_filter = '*')

      List files inside a SharePoint drive folder, following pagination.

      :param site_id: SharePoint site ID.
      :type site_id: :py:class:`str`
      :param drive_id: Drive ID within the site.
      :type drive_id: :py:class:`str`
      :param folder_path: Path to the folder within the drive root (e.g. ``"Gif/T297"``).
                          Use ``""`` or ``"/"`` for the drive root.
      :type folder_path: :py:class:`str`
      :param filename_filter: Glob pattern to filter file names, by default ``"*"`` (all files).
                              Example: ``"*.xls*"`` to match ``xlsx``/``xlsm``/``xls``.
      :type filename_filter: :py:class:`str`, *optional*

      :returns: List of dicts with keys ``"name"`` and ``"download_url"``
                for each matching file.  ``"download_url"`` is the pre-signed
                Azure Blob Storage URL (``@microsoft.graph.downloadUrl``).
      :rtype: :py:class:`list[dict]`