lunapi.bdc
==========

.. py:module:: lunapi.bdc

.. autoapi-nested-parse::

   Small Python client for files stored in a Gen3/BioData Catalyst commons.

   The client deliberately deals in file-index records rather than depending on
   the external ``gen3-client`` executable.  This keeps it usable by notebooks
   and desktop applications alike while allowing each Gen3 deployment to supply
   its own endpoint and project identifier.



Attributes
----------

.. autoapisummary::

   lunapi.bdc.bdc


Classes
-------

.. autoapisummary::

   lunapi.bdc.BDCClient


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

.. py:class:: BDCClient(endpoint=_DEFAULT_ENDPOINT, key_id=None, api_key=None, project=None, session=None, token=None)

   Authenticated file browser/downloader for a Gen3 commons.

   :param endpoint: Base URL of the Gen3 commons.
   :type endpoint: str
   :param key_id: API-key pair created by the commons Profile page.
   :type key_id: str
   :param api_key: API-key pair created by the commons Profile page.
   :type api_key: str
   :param project: Project identifier used by :meth:`files` when supplied.
   :type project: str, optional
   :param session: Injectable HTTP session for tests or callers with custom TLS setup.
   :type session: requests.Session, optional


   .. py:attribute:: endpoint
      :value: ''



   .. py:attribute:: key_id
      :value: ''



   .. py:attribute:: api_key
      :value: ''



   .. py:attribute:: project
      :value: None



   .. py:attribute:: token
      :value: None



   .. py:attribute:: session


   .. py:property:: authenticated
      :type: bool



   .. py:method:: authenticate() -> str


   .. py:method:: projects() -> list[str]

      Return project IDs visible to the current credentials when available.



   .. py:method:: files(project=None) -> list[dict]

      Return normalized file-index records for *project*.

      Gen3 deployments expose slightly different metadata keys.  The
      normalizer accepts the common indexd fields and preserves the raw
      record under ``raw`` for callers needing deployment-specific data.



   .. py:method:: recording_groups(project=None) -> list[dict]

      Group EDF records with same-basename sidecars.



   .. py:method:: download(record: dict, destination: str | os.PathLike, force=False, progress: Callable[[int, int], None] | None = None) -> pathlib.Path

      Download one normalized index record to *destination*.

      Existing files are skipped unless *force* is true.  A ``Range`` header
      resumes a partial file when the server supports it.



.. py:data:: bdc