thoth.bulk_import
=================

.. py:module:: thoth.bulk_import


Attributes
----------

.. autoapisummary::

   thoth.bulk_import.DEFAULT_LIMIT
   thoth.bulk_import.THOTH_ENDPOINT
   thoth.bulk_import.logger
   thoth.bulk_import.plugin
   thoth.bulk_import.here


Functions
---------

.. autoapisummary::

   thoth.bulk_import.fetch_books
   thoth.bulk_import.bulk_translate
   thoth.bulk_import.bulk_import


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

.. py:data:: DEFAULT_LIMIT
   :value: 50


.. py:data:: THOTH_ENDPOINT
   :value: 'https://api.thoth.pub'


.. py:data:: logger

.. py:data:: plugin

.. py:function:: fetch_books(query: str = 'Python', limit: int = DEFAULT_LIMIT, offset: int = 0) -> list[server.plugins.thoth.thoth_models.ThothBook]

   Fetch open-access books from the Thoth GraphQL API.

   Uses ``thothlibrary.ThothClient`` to query the ``books`` endpoint with the
   given search term.  The Munch objects returned by the client are converted
   to :class:`ThothBook` Pydantic models for type-safe downstream processing.

   Args:
       query:  Search term passed to the Thoth ``books`` endpoint filter.
       limit:  Maximum number of results to return (default 50).
       offset: Pagination offset (default 0).

   Returns:
       A list of :class:`ThothBook` records.

   Raises:
       RuntimeError: If the Thoth API request fails.


.. py:function:: bulk_translate(items: list[dict]) -> collections.abc.Iterator[server.plugins.ome_plugin.EducationResource]

   Translate a list of raw Thoth book dicts to OME EducationResource cards.


.. py:function:: bulk_import(query: str = 'Python', limit: int = DEFAULT_LIMIT, cache_path: pathlib.Path | None = None) -> list[dict]

   Fetch Thoth books by search query and cache results locally.

   On the first run the function calls the Thoth GraphQL API and writes the
   raw book records to *cache_path*.  Subsequent calls read from the cache so
   that the network is not hit again.

   Args:
       query:      Search term passed to the Thoth ``books`` endpoint.
       limit:      Maximum number of results to fetch from the API.
       cache_path: Path for the local JSON cache.  Defaults to
                   ``thoth_python_books.json`` next to this file.

   Returns:
       A list of serialised :class:`~server.plugins.ome_plugin.EducationResource`
       dicts.


.. py:data:: here