project_gutenberg.bulk_import
=============================

.. py:module:: project_gutenberg.bulk_import


Attributes
----------

.. autoapisummary::

   project_gutenberg.bulk_import.GUTENDEX_BOOKS_URL
   project_gutenberg.bulk_import.DEFAULT_SEARCH_QUERY
   project_gutenberg.bulk_import.DEFAULT_LIMIT
   project_gutenberg.bulk_import.API_TIMEOUT_SECONDS
   project_gutenberg.bulk_import.logger
   project_gutenberg.bulk_import.plugin
   project_gutenberg.bulk_import.here


Functions
---------

.. autoapisummary::

   project_gutenberg.bulk_import.fetch_books
   project_gutenberg.bulk_import.bulk_translate
   project_gutenberg.bulk_import.bulk_import


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

.. py:data:: GUTENDEX_BOOKS_URL
   :value: 'https://gutendex.com/books/'


.. py:data:: DEFAULT_SEARCH_QUERY
   :value: 'Sherlock Holmes'


.. py:data:: DEFAULT_LIMIT
   :value: 32


.. py:data:: API_TIMEOUT_SECONDS
   :value: 30.0


.. py:data:: logger

.. py:data:: plugin

.. py:function:: fetch_books(query: str = DEFAULT_SEARCH_QUERY, limit: int = DEFAULT_LIMIT) -> list[server.plugins.project_gutenberg.gutenberg_models.GutenbergBook]
   :async:


   Fetch books from the Gutendex REST API matching *query*.

   Gutendex paginates in pages of 32 books.  This function fetches pages
   until *limit* books have been collected or no more pages are available.

   Args:
       query: Search query string (e.g. ``"Sherlock Holmes"``).
       limit: Maximum total number of books to return.

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

   Raises:
       RuntimeError: If an API request fails.


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

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


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

   Fetch Project Gutenberg books by search query and cache results locally.

   On the first run the function calls the Gutendex 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 Gutendex REST API.
       limit: Maximum number of books to fetch from the API.
       cache_path: Path for the local JSON cache.  Defaults to
           ``gutenberg_sherlock_holmes.json`` next to this file.

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


.. py:data:: here