openlibrary.bulk_import
=======================

.. py:module:: openlibrary.bulk_import

.. autoapi-nested-parse::

   Bulk-import book metadata from the Open Library search API.

   Open Library exposes a free public search API that returns structured JSON.
   This module fetches books matching a search query and translates them into
   standardised OME ``EducationResource`` cards.



Attributes
----------

.. autoapisummary::

   openlibrary.bulk_import.OPENLIBRARY_SEARCH_URL
   openlibrary.bulk_import.OPENLIBRARY_BASE_URL
   openlibrary.bulk_import.DEFAULT_SEARCH_QUERY
   openlibrary.bulk_import.DEFAULT_LIMIT
   openlibrary.bulk_import.logger
   openlibrary.bulk_import.plugin
   openlibrary.bulk_import.here


Functions
---------

.. autoapisummary::

   openlibrary.bulk_import.fetch_books
   openlibrary.bulk_import.bulk_translate
   openlibrary.bulk_import.bulk_import


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

.. py:data:: OPENLIBRARY_SEARCH_URL
   :value: 'https://openlibrary.org/search.json'


.. py:data:: OPENLIBRARY_BASE_URL
   :value: 'https://openlibrary.org'


.. py:data:: DEFAULT_SEARCH_QUERY
   :value: 'python programming'


.. py:data:: DEFAULT_LIMIT
   :value: 20


.. py:data:: logger

.. py:data:: plugin

.. py:function:: fetch_books(query: str = DEFAULT_SEARCH_QUERY, limit: int = DEFAULT_LIMIT) -> list[dict]

   Search Open Library and return a list of raw book dicts.

   Args:
       query: Search query string.
       limit: Maximum number of results to return.

   Returns:
       A list of raw book dicts from the Open Library search API.


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

   Translate raw Open Library search result 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 Open Library books and return serialised OME records.

   Results are cached locally so that repeated runs do not re-fetch the API.

   Args:
       query: Search query string (default: ``"python programming"``).
       limit: Maximum number of results (default: 20).
       cache_path: Path to the local JSON cache file.  If ``None``, defaults
                   to ``openlibrary_python_books.json`` next to this module.

   Returns:
       A list of serialised :class:`EducationResource` dicts.


.. py:data:: here