db.importer
===========

.. py:module:: db.importer

.. autoapi-nested-parse::

   Importer workflow for metadata JSON + ZIP package pairs.



Functions
---------

.. autoapisummary::

   db.importer.load_metadata_json
   db.importer.read_txt_rows
   db.importer.import_package_pair


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

.. py:function:: load_metadata_json(metadata_path)

   Load metadata JSON and enforce object-root structure.

   :param metadata_path: Path to metadata JSON file.

   :returns: Parsed JSON object.

   :raises ValueError: If the root JSON value is not an object.


.. py:function:: read_txt_rows(archive, entry_name)

   Read one txt entry and return ``(line_number, value)`` tuples.

   Empty and whitespace-only lines are skipped during import so DB tables only
   store meaningful values.


.. py:function:: import_package_pair(conn, *, metadata_path, zip_path)

   Import one metadata+zip pair and create one SQLite table per ``*.txt``.

   The importer ignores JSON files inside the archive. It uses metadata
   ``files_included`` (when provided) to limit which ``*.txt`` entries are
   imported.

   :param conn: Open SQLite connection.
   :param metadata_path: Path to ``*_metadata.json`` file.
   :param zip_path: Path to package zip file.

   :returns: API-style summary payload describing imported package and created tables.

   :raises FileNotFoundError: If metadata or zip path does not exist.
   :raises ValueError: For invalid metadata, duplicate imports, or zip format/data
       issues.