open_education_network.bulk_import
==================================

.. py:module:: open_education_network.bulk_import


Attributes
----------

.. autoapisummary::

   open_education_network.bulk_import.OEN_BASE_URL
   open_education_network.bulk_import.OEN_TEXTBOOKS_API_URL
   open_education_network.bulk_import.logger
   open_education_network.bulk_import.plugin
   open_education_network.bulk_import.here


Functions
---------

.. autoapisummary::

   open_education_network.bulk_import._parse_records
   open_education_network.bulk_import.fetch_textbooks
   open_education_network.bulk_import.bulk_translate
   open_education_network.bulk_import.bulk_import


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

.. py:data:: OEN_BASE_URL
   :value: 'https://open.umn.edu/opentextbooks'


.. py:data:: OEN_TEXTBOOKS_API_URL
   :value: 'https://open.umn.edu/opentextbooks/textbooks.json'


.. py:data:: logger

.. py:data:: plugin

.. py:function:: _parse_records(items: list) -> list[server.plugins.open_education_network.open_education_network_models.OENTextbook]

   Validate raw API items into OENTextbook 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_textbooks(*, subject: str = '', formats: list[str] | None = None) -> list[server.plugins.open_education_network.open_education_network_models.OENTextbook]

   Fetch textbooks from the Open Education Network API.

   Args:
       subject: Subject keyword to search for (e.g., ``"Python"``).
       formats: List of format names to filter by (e.g., ``["eBook", "PDF"]``).
                Passed to the API as repeated ``format[]`` query parameters.

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


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

   Translate a list of raw OEN textbook dicts to OME EducationResource cards.


.. py:function:: bulk_import(subject: str = 'Python', formats: list[str] | None = None, cache_path: pathlib.Path | None = None) -> list[dict]

   Fetch Open Education Network textbooks and return serialised OME records.

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

   Args:
       subject: Subject keyword to filter by (default: ``"Python"``).
       formats: Format names to filter by (default: ``["eBook", "PDF"]``).
       cache_path: Path to the local JSON cache file. If ``None``, a default
                   path next to this module is used.

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


.. py:data:: here