oapen_books.bulk_import
=======================

.. py:module:: oapen_books.bulk_import


Attributes
----------

.. autoapisummary::

   oapen_books.bulk_import.OAPEN_REST_URL
   oapen_books.bulk_import.DEFAULT_LIMIT
   oapen_books.bulk_import.logger
   oapen_books.bulk_import.plugin
   oapen_books.bulk_import.here


Functions
---------

.. autoapisummary::

   oapen_books.bulk_import.fetch_books
   oapen_books.bulk_import.bulk_translate
   oapen_books.bulk_import.bulk_import


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

.. py:data:: OAPEN_REST_URL
   :value: 'https://library.oapen.org/rest/search'


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


.. py:data:: logger

.. py:data:: plugin

.. py:function:: fetch_books(query: str, limit: int = DEFAULT_LIMIT, offset: int = 0) -> list[server.plugins.oapen_books.oapen_models.OapenItem]
   :async:


   Fetch open-access books from the OAPEN Library REST API.

   Args:
       query: Search query string (e.g. ``"python programming"``).
       limit: Maximum number of results to return (default 50).
       offset: Pagination offset (default 0).

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

   Raises:
       RuntimeError: If the API request fails.


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

   Translate a list of raw OAPEN item dicts to OME EducationResource cards.


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

   Fetch OAPEN books by search query and cache results locally.

   On the first run the function calls the OAPEN REST API and writes the
   results to *cache_path*.  Subsequent calls read from the cache so that
   the network is not hit again.

   Args:
       query: Search query passed to the OAPEN REST API.
       limit: Maximum number of results to fetch from the API.
       cache_path: Path for the local JSON cache.  Defaults to
           ``oapen_python_books.json`` next to this file.

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


.. py:data:: here