pressbooks.bulk_import
======================

.. py:module:: pressbooks.bulk_import


Attributes
----------

.. autoapisummary::

   pressbooks.bulk_import.PRESSBOOKS_DIRECTORY_URL
   pressbooks.bulk_import.BOOKS_API_URL
   pressbooks.bulk_import.DEFAULT_PER_PAGE
   pressbooks.bulk_import.logger
   pressbooks.bulk_import.plugin
   pressbooks.bulk_import.here


Functions
---------

.. autoapisummary::

   pressbooks.bulk_import._parse_page
   pressbooks.bulk_import._fetch_page
   pressbooks.bulk_import.fetch_all_books
   pressbooks.bulk_import.bulk_translate
   pressbooks.bulk_import.bulk_import_search
   pressbooks.bulk_import.bulk_import_institution


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

.. py:data:: PRESSBOOKS_DIRECTORY_URL
   :value: 'https://pressbooks.directory'


.. py:data:: BOOKS_API_URL
   :value: 'https://pressbooks.directory/wp-json/pressbooks/v2/books'


.. py:data:: DEFAULT_PER_PAGE
   :value: 100


.. py:data:: logger

.. py:data:: plugin

.. py:function:: _parse_page(items: list) -> list[server.plugins.pressbooks.pressbooks_models.PressbooksBook]

   Validate raw API items into PressbooksBook records.

   Uses a Python 3.13+ ExceptionGroup to gather and report all validation
   errors at once rather than stopping at the first malformed record.
   Valid records are returned even when some items fail validation.


.. py:function:: _fetch_page(client: httpx.AsyncClient, params: dict[str, str | int]) -> list[server.plugins.pressbooks.pressbooks_models.PressbooksBook]
   :async:


   Fetch and parse a single page of books from the Pressbooks Directory API.


.. py:function:: fetch_all_books(*, search: str = '', institution: str = '', per_page: int = DEFAULT_PER_PAGE) -> list[server.plugins.pressbooks.pressbooks_models.PressbooksBook]
   :async:


   Fetch all matching books from the Pressbooks Directory.

   Fetches the first page to discover the total page count from the
   ``X-WP-TotalPages`` response header, then gathers all remaining pages
   concurrently using :func:`asyncio.gather`.

   Args:
       search: Full-text search query (maps to the ``?q=`` UI parameter).
       institution: Institution name filter (maps to the ``?inst=`` UI parameter).
                    Multiple institutions can be joined with ``&&``
                    (e.g. ``"University at Buffalo&&University of Rochester"``).
       per_page: Number of results per page (max 100).

   Returns:
       A flat list of all :class:`PressbooksBook` records.


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

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


.. py:function:: bulk_import_search(search: str, cache_path: pathlib.Path) -> list[dict]

   Fetch Pressbooks books by search query and cache results locally.

   Args:
       search: Search term to pass to the API.
       cache_path: Path to the local JSON cache file.

   Returns:
       A list of serialised EducationResource dicts.


.. py:function:: bulk_import_institution(institution: str, cache_path: pathlib.Path) -> list[dict]

   Fetch Pressbooks books by institution filter and cache results locally.

   Args:
       institution: Institution name(s) joined with ``&&``.
       cache_path: Path to the local JSON cache file.

   Returns:
       A list of serialised EducationResource dicts.


.. py:data:: here