qubes.bulk_import
=================

.. py:module:: qubes.bulk_import

.. autoapi-nested-parse::

   Bulk-import publication metadata from QUBES Hub via the OAI-PMH API.

   QUBES Hub exposes an OAI-PMH (Open Archives Initiative Protocol for Metadata
   Harvesting) endpoint.  This module reads from the locally cached
   ``qubes_records.json`` file (generated by ``convert_qubes_xml_to_json.py``)
   and translates each record into a standardised OME ``EducationResource`` card.



Attributes
----------

.. autoapisummary::

   qubes.bulk_import.QUBES_OAI_URL
   qubes.bulk_import.QUBES_BASE_URL
   qubes.bulk_import.logger
   qubes.bulk_import.plugin
   qubes.bulk_import.here


Functions
---------

.. autoapisummary::

   qubes.bulk_import._parse_records
   qubes.bulk_import.bulk_translate
   qubes.bulk_import.bulk_import


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

.. py:data:: QUBES_OAI_URL
   :value: 'https://qubeshub.org/oaipmh/?verb=ListRecords&metadataPrefix=oai_dc&set=publications'


.. py:data:: QUBES_BASE_URL
   :value: 'https://qubeshub.org'


.. py:data:: logger

.. py:data:: plugin

.. py:function:: _parse_records(items: list) -> list[server.plugins.qubes.qubes_models.ModelItem]

   Validate raw record dicts into :class:`ModelItem` objects.

   Uses a Python 3.13+ ExceptionGroup to collect all validation errors
   and report them together while returning valid records to the caller.


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

   Translate raw QUBES record dicts to OME EducationResource cards.


.. py:function:: bulk_import(cache_path: pathlib.Path | None = None) -> list[dict]

   Load QUBES records from the local cache and return serialised OME records.

   The cache file ``qubes_records.json`` is generated by
   ``convert_qubes_xml_to_json.py`` from the OAI-PMH XML export.  Run that
   script first if the cache does not yet exist.

   Args:
       cache_path: Path to ``qubes_records.json``.  If ``None``, defaults
                   to the file next to this module.

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

   Raises:
       FileNotFoundError: If ``qubes_records.json`` does not exist.


.. py:data:: here