oercommons.bulk_import
======================

.. py:module:: oercommons.bulk_import

.. autoapi-nested-parse::

   Bulk-import metadata from OER Commons.

   Uses the OER Commons search API to fetch Open Educational Resources and
   translate them into standardised OME ``EducationResource`` cards.
   Results are cached locally to avoid repeated API calls.



Attributes
----------

.. autoapisummary::

   oercommons.bulk_import.OERCOMMONS_SEARCH_URL
   oercommons.bulk_import.DEFAULT_SEARCH_QUERY
   oercommons.bulk_import.DEFAULT_BATCH_SIZE
   oercommons.bulk_import.logger
   oercommons.bulk_import._plugin
   oercommons.bulk_import.here


Functions
---------

.. autoapisummary::

   oercommons.bulk_import.fetch_materials
   oercommons.bulk_import.bulk_translate
   oercommons.bulk_import.bulk_import


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

.. py:data:: OERCOMMONS_SEARCH_URL
   :value: 'https://oercommons.org/api/v1/materials/search'


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


.. py:data:: DEFAULT_BATCH_SIZE
   :value: 20


.. py:data:: logger

.. py:data:: _plugin

.. py:function:: fetch_materials(query: str = DEFAULT_SEARCH_QUERY, batch_size: int = DEFAULT_BATCH_SIZE) -> list[dict]

   Search OER Commons and return raw search-hit dicts.

   Each returned dict has the same shape as :class:`Model` (i.e. it contains
   ``_index``, ``_type``, ``_id``, ``_score``, ``_source``) so that it can be
   passed directly to :meth:`OERCommonsPlugin.make_metadata_card_from_json`.

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

   Returns:
       A list of raw search-hit dicts.


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

   Translate raw OER Commons search-hit dicts to OME EducationResource cards.

   Each dict should have the same shape as :class:`Model` (``_index``,
   ``_type``, ``_id``, ``_score``, ``_source``), matching the format returned
   by the search API and cached by :func:`bulk_import`.


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

   Fetch OER Commons materials 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"``).
       batch_size: Maximum number of results to return (default: 20).
       cache_path: Path to the local JSON cache file.  If ``None``, defaults
                   to ``oercommons_python_materials.json`` next to this module.

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


.. py:data:: here