python-dwca-reader 0.16.4__py3-none-any.whl → 0.17.0__py3-none-any.whl

dwca/test/test_datafile.py

@@ -1,3 +1,4 @@
+import os
 import unittest
 import xml.etree.ElementTree as ET
 from array import array
@@ -35,6 +36,9 @@ class TestCSVDataFile(unittest.TestCase):
             description_txt = extension_files[0]
             vernacular_txt = extension_files[1]
 
+            # coreid_index values are array("L") rather than lists. This is documented in the
+            # property docstring and DwCAReader.orphaned_extension_rows() relies on it via
+            # .tolist(), so it is part of the contract, not an implementation detail.
             expected_core = {
                 "1": array("L", [0]),
                 "2": array("L", [1]),
@@ -49,9 +53,6 @@ class TestCSVDataFile(unittest.TestCase):
             expected_description = {"1": array("L", [0, 1]), "4": array("L", [2])}
             assert description_txt.coreid_index == expected_description
 
-            with pytest.raises(AttributeError):
-                dwca.corefile.coreid_index
-
     def test_file_descriptor_attribute(self):
         """The instance of DataFileDescriptor passed to the constructor is available in .file_descriptor"""
 
@@ -160,3 +161,285 @@ class TestCSVDataFile(unittest.TestCase):
 
         for row in data_file:
             assert isinstance(row, str)
+
+
+class TestStreamingIteration(unittest.TestCase):
+    def test_iter_rows_yields_every_row_in_order(self):
+        with DwCAReader(sample_data_path("dwca-ids.zip")) as dwca:
+            rows = list(dwca.core_file.iter_rows())
+
+        # Row IDs appear in the core file in this order: 4-1-3-2
+        assert ["4", "1", "3", "2"] == [row.id for row in rows]
+        assert [0, 1, 2, 3] == [row.position for row in rows]
+
+    def test_iter_rows_agrees_with_random_access(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            for data_file in [dwca.core_file] + dwca.extension_files:
+                streamed = list(data_file.iter_rows())
+                seeked = [
+                    data_file.get_row_by_position(i) for i in range(len(streamed))
+                ]
+
+                assert [r.data for r in streamed] == [r.data for r in seeked]
+                assert [r.raw_fields for r in streamed] == [
+                    r.raw_fields for r in seeked
+                ]
+
+    def test_iter_rows_can_be_nested(self):
+        """Each call gets its own stream, so concurrent passes do not interfere."""
+        with DwCAReader(sample_data_path("dwca-ids.zip")) as dwca:
+            pairs = [
+                (outer.id, inner.id)
+                for outer in dwca.core_file.iter_rows()
+                for inner in dwca.core_file.iter_rows()
+            ]
+
+        assert 16 == len(pairs)
+
+    def test_iter_rows_on_a_quoted_archive(self):
+        with DwCAReader(sample_data_path("dwca-csv-quote-dir")) as dwca:
+            rows = list(dwca.core_file.iter_rows())
+
+        assert 2 == len(rows)
+
+    def test_raw_line_iteration_skips_every_header_line(self):
+        """readlines() takes a byte-size hint, not a line count, so with two header lines
+        the second used to leak through as data."""
+        from .archive_builder import build_archive, temp_archive_dir
+
+        path = build_archive(
+            temp_archive_dir(self),
+            rows=[["1", "Borneo"], ["2", "Mumbai"]],
+            ignore_header_lines=2,
+            header_rows=[["idA", "locA"], ["idB", "locB"]],
+        )
+        with DwCAReader(path) as dwca:
+            lines = list(dwca.core_file)
+
+            assert 2 == len(lines)
+            assert lines[0].startswith("1\t")
+            assert lines[1].startswith("2\t")
+
+
+class TestLineOffsets(unittest.TestCase):
+    def test_opening_an_archive_does_not_build_the_index(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            assert dwca.core_file._line_offsets is None
+
+            dwca.core_file.get_row_by_position(0)
+
+            assert dwca.core_file._line_offsets is not None
+
+    def test_offsets_survive_an_undecodable_byte(self):
+        from .archive_builder import build_archive, temp_archive_dir
+
+        path = build_archive(
+            temp_archive_dir(self),
+            rows=[],
+            columns=2,
+            raw_payload=b"1\tcaf\xe9\n2\tMumbai\n3\tBorneo\n",
+        )
+        with DwCAReader(path) as dwca:
+            term = "http://rs.tdwg.org/dwc/terms/term1"
+
+            assert "Mumbai" == dwca.core_file.get_row_by_position(1).data[term]
+            assert "Borneo" == dwca.core_file.get_row_by_position(2).data[term]
+
+    def test_offsets_with_dos_line_endings(self):
+        from .archive_builder import build_archive, temp_archive_dir
+
+        path = build_archive(
+            temp_archive_dir(self),
+            rows=[["1", "Borneo"], ["2", "Mumbai"]],
+            lines_terminated_by="\r\n",
+        )
+        with DwCAReader(path) as dwca:
+            term = "http://rs.tdwg.org/dwc/terms/term1"
+
+            assert "Borneo" == dwca.core_file.get_row_by_position(0).data[term]
+            assert "Mumbai" == dwca.core_file.get_row_by_position(1).data[term]
+
+    def test_offsets_are_correct_across_a_chunk_boundary(self):
+        """The scanner reads in chunks, so a terminator can straddle two reads."""
+        from dwca.files import _build_line_offsets
+        from .archive_builder import build_archive, temp_archive_dir
+
+        rows = [[str(i), "locality-" + str(i)] for i in range(5000)]
+        path = build_archive(temp_archive_dir(self), rows=rows)
+
+        data_path = os.path.join(path, "occurrence.txt")
+        reference = _build_line_offsets(data_path, "utf-8", "\n")
+        chunked = _build_line_offsets(data_path, "utf-8", "\n", chunk_size=7)
+
+        assert 5000 == len(reference)
+        assert list(reference) == list(chunked)
+
+    def test_a_zero_byte_core_file_has_no_rows(self):
+        """A zero-byte file must report no lines at all, not one spurious empty line."""
+        from .archive_builder import build_archive, temp_archive_dir
+
+        path = build_archive(
+            temp_archive_dir(self), rows=[], columns=2, raw_payload=b""
+        )
+        with DwCAReader(path) as dwca:
+            with pytest.raises(IndexError):
+                dwca.core_file.get_row_by_position(0)
+
+    def test_multibyte_utf8_and_an_embedded_newline_in_the_same_file(self):
+        """_read_record() must use a byte-accurate read.
+
+        offsets are byte offsets, but a text stream's read(n) counts characters, so a
+        naive `self._file_stream.read(next_offset - start)` would desync as soon as the
+        file contains a character that takes more than one byte in UTF-8 - truncating or
+        over-reading the record. This archive puts multi-byte characters (which make
+        byte count and character count diverge) and a quoted embedded newline (which
+        makes a record span more than one physical line) in the same file, so both
+        failure modes would have to hold simultaneously to pass.
+        """
+        from .archive_builder import build_archive, temp_archive_dir
+
+        # ACCENTED_E is a 2-byte UTF-8 character, SNOWMAN a 3-byte one: both make byte
+        # count and character count diverge. Row 2's third field is quoted and contains
+        # an embedded newline, so that record spans two physical lines.
+        ACCENTED_E = "\xe9"
+        SNOWMAN = "\u2603"
+        payload = (
+            "1,caf" + ACCENTED_E + "," + SNOWMAN + "\n"
+            '2,"multi\nline",' + SNOWMAN + ACCENTED_E + "\n"
+            "3," + ACCENTED_E * 3 + ",end\n"
+        ).encode("utf-8")
+        path = build_archive(
+            temp_archive_dir(self),
+            rows=[],
+            columns=3,
+            raw_payload=payload,
+            fields_terminated_by=",",
+            fields_enclosed_by='"',
+        )
+
+        with DwCAReader(path) as dwca:
+            streamed = [row.raw_fields for row in dwca]
+            seeked = [
+                dwca.core_file.get_row_by_position(i).raw_fields
+                for i in range(len(streamed))
+            ]
+
+        assert [
+            ["1", "caf" + ACCENTED_E, SNOWMAN],
+            ["2", "multi\nline", SNOWMAN + ACCENTED_E],
+            ["3", ACCENTED_E * 3, "end"],
+        ] == streamed
+        assert streamed == seeked
+
+
+class TestIterTerms(unittest.TestCase):
+    def test_matches_the_row_api(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            terms = sorted(dwca.core_file.file_descriptor.terms)
+
+            via_rows = [tuple(row.data[t] for t in terms) for row in dwca]
+            via_terms = list(dwca.core_file.iter_terms(terms))
+
+        assert via_rows == via_terms
+
+    def test_works_on_an_extension_file(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            extension = dwca.extension_files[0]
+            terms = sorted(extension.file_descriptor.terms)
+
+            via_rows = [tuple(r.data[t] for t in terms) for r in extension.iter_rows()]
+            via_terms = list(extension.iter_terms(terms))
+
+        assert via_rows == via_terms
+
+    def test_subset_of_columns(self):
+        with DwCAReader(sample_data_path("dwca-simple-test-archive.zip")) as dwca:
+            values = list(
+                dwca.core_file.iter_terms(["http://rs.tdwg.org/dwc/terms/locality"])
+            )
+
+        assert [("Borneo",), ("Mumbai",)] == values
+
+    def test_unknown_term_raises_before_reading_anything(self):
+        with DwCAReader(sample_data_path("dwca-simple-test-archive.zip")) as dwca:
+            with pytest.raises(ValueError):
+                dwca.core_file.iter_terms(["http://rs.tdwg.org/dwc/terms/nope"])
+
+    def test_default_only_term(self):
+        with DwCAReader(sample_data_path("dwca-test-default.zip")) as dwca:
+            values = list(
+                dwca.core_file.iter_terms(["http://rs.tdwg.org/dwc/terms/country"])
+            )
+
+        assert [("Belgium",), ("Belgium",)] == values
+
+    def test_can_be_nested(self):
+        with DwCAReader(sample_data_path("dwca-ids.zip")) as dwca:
+            term = ["http://rs.tdwg.org/dwc/terms/family"]
+            pairs = [
+                (a, b)
+                for a in dwca.core_file.iter_terms(term)
+                for b in dwca.core_file.iter_terms(term)
+            ]
+
+        assert 16 == len(pairs)
+
+
+class TestIterTermsKeyColumns(unittest.TestCase):
+    def test_core_id_is_reachable(self):
+        """dwca-ids.zip declares no <field> for its id column."""
+        with DwCAReader(sample_data_path("dwca-ids.zip")) as dwca:
+            from_rows = [row.id for row in dwca]
+            from_terms = [values[0] for values in dwca.iter_terms(["id"])]
+
+        assert ["4", "1", "3", "2"] == from_rows
+        assert from_rows == from_terms
+
+    def test_extension_coreid_is_reachable(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            extension = dwca.extension_files[0]
+
+            from_rows = [row.core_id for row in extension.iter_rows()]
+            from_terms = [values[0] for values in extension.iter_terms(["coreid"])]
+
+        assert from_rows == from_terms
+
+    def test_key_column_mixes_with_real_terms_in_the_requested_order(self):
+        order = "http://rs.tdwg.org/dwc/terms/order"
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            got = list(dwca.iter_terms([order, "id"]))
+            expected = [(row.data[order], row.id) for row in dwca]
+
+        assert expected == got
+
+    def test_id_is_still_unknown_when_the_file_has_no_id_column(self):
+        """A metafile-less archive has no id column, so the name must not resolve."""
+        with DwCAReader(sample_data_path("dwca-simple-csv.zip")) as dwca:
+            with pytest.raises(ValueError):
+                dwca.iter_terms(["id"])
+
+    def test_coreid_is_unknown_on_a_core_file(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            with pytest.raises(ValueError):
+                dwca.iter_terms(["coreid"])
+
+
+class TestClosedFileGuarantee(unittest.TestCase):
+    def test_iteration_after_close_raises(self):
+        """close() documents that content is not accessible in any way afterwards."""
+        with DwCAReader(sample_data_path("dwca-simple-dir")) as dwca:
+            data_file = dwca.core_file
+
+            assert list(data_file.iter_rows())  # works while open
+            data_file.close()
+
+            with pytest.raises(ValueError):
+                list(data_file.iter_rows())
+
+    def test_reader_iteration_after_close_raises(self):
+        dwca = DwCAReader(sample_data_path("dwca-simple-dir"))
+        assert list(dwca)
+        dwca.close()
+
+        with pytest.raises(ValueError):
+            list(dwca)

dwca/test/test_descriptors.py

@@ -3,8 +3,11 @@ import unittest
 import xml.etree.ElementTree as ET
 import zipfile
 
+import pytest
+
 from dwca.darwincore.utils import qualname as qn
 from dwca.descriptors import DataFileDescriptor, ArchiveDescriptor
+from dwca.exceptions import InvalidArchive
 from dwca.read import DwCAReader
 from .helpers import sample_data_path
 
@@ -455,6 +458,102 @@ class TestDataFileDescriptor(unittest.TestCase):
             assert fields == descriptor.core.terms
 
 
+class TestDataFileDescriptorEquality(unittest.TestCase):
+    """Unit tests for DataFileDescriptor equality and hashing.
+
+    Descriptors compare by value (the data file layout they describe) rather than by object
+    identity, so descriptors built twice from the same archive - by two DwCAReader instances,
+    for example - compare equal.
+    """
+
+    CORE_SECTION = """
+    <core encoding="utf-8" fieldsTerminatedBy="\t" linesTerminatedBy="\n" fieldsEnclosedBy=""
+    ignoreHeaderLines="0" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
+        <files>
+            <location>occurrence.txt</location>
+        </files>
+        <id index="0" />
+        <field index="1" term="http://rs.tdwg.org/dwc/terms/scientificName"/>
+        <field default="Belgium" term="http://rs.tdwg.org/dwc/terms/country"/>
+    </core>
+    """
+
+    def _make(self, section=None):
+        return DataFileDescriptor.make_from_metafile_section(
+            ET.fromstring(section if section is not None else self.CORE_SECTION)
+        )
+
+    def test_descriptors_from_identical_sections_are_equal(self):
+        one = self._make()
+        two = self._make()
+
+        assert one is not two
+        # raw_element is an ET.Element, which compares by identity: these two are distinct
+        # objects, so equality can only hold if raw_element is left out of the comparison.
+        assert one.raw_element is not two.raw_element
+        assert one == two
+        assert not (one != two)
+        assert hash(one) == hash(two)
+        assert len({one, two}) == 1
+
+    def test_descriptors_of_the_same_archive_read_twice_are_equal(self):
+        path = sample_data_path("dwca-2extensions.zip")
+
+        with DwCAReader(path) as one, DwCAReader(path) as two:
+            assert one.descriptor.core == two.descriptor.core
+
+            for ext_one, ext_two in zip(
+                one.descriptor.extensions, two.descriptor.extensions
+            ):
+                assert ext_one == ext_two
+
+    def test_core_and_extension_descriptors_differ(self):
+        with DwCAReader(sample_data_path("dwca-2extensions.zip")) as dwca:
+            core = dwca.descriptor.core
+
+            for extension in dwca.descriptor.extensions:
+                assert core != extension
+
+    def test_descriptors_differing_by_ignored_header_lines_differ(self):
+        one = self._make()
+        two = self._make(
+            self.CORE_SECTION.replace('ignoreHeaderLines="0"', 'ignoreHeaderLines="1"')
+        )
+
+        # Everything but the number of header lines to skip is identical here. That number
+        # lives in raw_element, which is excluded from the comparison, so it's only taken into
+        # account through the lines_to_ignore property.
+        assert one.lines_to_ignore != two.lines_to_ignore
+        assert one != two
+
+    def test_descriptors_differing_by_fields_differ(self):
+        one = self._make()
+        two = self._make(
+            self.CORE_SECTION.replace(
+                'term="http://rs.tdwg.org/dwc/terms/scientificName"',
+                'term="http://rs.tdwg.org/dwc/terms/locality"',
+            )
+        )
+
+        assert one != two
+
+    def test_descriptors_differing_by_file_location_differ(self):
+        one = self._make()
+        two = self._make(
+            self.CORE_SECTION.replace("occurrence.txt", "other_occurrences.txt")
+        )
+
+        assert one != two
+
+    def test_comparison_with_other_types_returns_false(self):
+        descriptor = self._make()
+
+        assert descriptor != "not a descriptor"
+        assert descriptor != 42
+        assert descriptor != None  # noqa: E711 - we're testing __eq__, not identity
+        assert not (descriptor == "not a descriptor")
+
+
 class TestArchiveDescriptor(unittest.TestCase):
     """Unit tests for ArchiveDescriptor class."""
 
@@ -594,3 +693,235 @@ class TestArchiveDescriptor(unittest.TestCase):
             descriptor = dwca.descriptor
 
             assert descriptor.metadata_filename == "eml.xml"
+
+
+class TestHeadersIndexZero(unittest.TestCase):
+    def test_column_at_index_zero_is_not_dropped(self):
+        """A metafile-less archive has no id_index, so column 0 comes only from fields."""
+        with DwCAReader(sample_data_path("dwca-simple-csv.zip")) as dwca:
+            descriptor = dwca.core_file.file_descriptor
+
+            assert len(descriptor.fields) == len(descriptor.headers)
+            assert "gbifid" == descriptor.headers[0]
+
+
+class TestFieldPlan(unittest.TestCase):
+    def _descriptor(self, fields_xml, tag="core", id_tag='<id index="0" />'):
+        section = """
+        <{tag} encoding="utf-8" fieldsTerminatedBy="\\t" linesTerminatedBy="\\n" \
+fieldsEnclosedBy="" ignoreHeaderLines="0" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
+            <files><location>occurrence.txt</location></files>
+            {id_tag}
+            {fields}
+        </{tag}>
+        """.format(
+            tag=tag, id_tag=id_tag, fields=fields_xml
+        )
+        return DataFileDescriptor.make_from_metafile_section(ET.fromstring(section))
+
+    def test_contiguous_columns(self):
+        descriptor = self._descriptor(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b"/>'
+        )
+
+        assert {"http://x/a": "1", "http://x/b": "Borneo"} == (
+            descriptor.field_plan.build_data(["1", "Borneo"])
+        )
+
+    def test_columns_out_of_order_and_with_gaps(self):
+        descriptor = self._descriptor(
+            '<field index="2" term="http://x/a"/>'
+            '<field index="0" term="http://x/b"/>'
+        )
+
+        assert {"http://x/a": "third", "http://x/b": "first"} == (
+            descriptor.field_plan.build_data(["first", "second", "third"])
+        )
+
+    def test_single_column(self):
+        descriptor = self._descriptor('<field index="1" term="http://x/a"/>')
+
+        assert {"http://x/a": "Borneo"} == descriptor.field_plan.build_data(
+            ["1", "Borneo"]
+        )
+
+    def test_default_only_field_has_no_column(self):
+        descriptor = self._descriptor(
+            '<field index="0" term="http://x/a"/>'
+            '<field term="http://x/country" default="Belgium"/>'
+        )
+
+        assert {"http://x/a": "1", "http://x/country": "Belgium"} == (
+            descriptor.field_plan.build_data(["1"])
+        )
+
+    def test_default_fills_an_empty_cell(self):
+        """A field can have both a column and a default (issue #80)."""
+        descriptor = self._descriptor(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b" default="fallback"/>'
+        )
+
+        assert "Borneo" == descriptor.field_plan.build_data(["1", "Borneo"])["http://x/b"]
+        assert "fallback" == descriptor.field_plan.build_data(["1", ""])["http://x/b"]
+
+    def test_missing_value_without_default_becomes_empty_string(self):
+        descriptor = self._descriptor(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b"/>'
+        )
+
+        assert "" == descriptor.field_plan.build_data(["1", ""])["http://x/b"]
+
+    def test_key_order_follows_the_metafile(self):
+        """Row.data key order is visible through str(row), so it must not drift."""
+        descriptor = self._descriptor(
+            '<field index="0" term="http://x/a"/>'
+            '<field term="http://x/country" default="Belgium"/>'
+            '<field index="1" term="http://x/b"/>'
+        )
+
+        assert ["http://x/a", "http://x/country", "http://x/b"] == list(
+            descriptor.field_plan.build_data(["1", "Borneo"])
+        )
+
+    def test_row_with_too_few_columns_raises(self):
+        descriptor = self._descriptor('<field index="3" term="http://x/a"/>')
+
+        with pytest.raises(InvalidArchive):
+            descriptor.field_plan.build_data(["1", "Borneo"])
+
+    def test_the_plan_is_cached(self):
+        descriptor = self._descriptor('<field index="0" term="http://x/a"/>')
+
+        assert descriptor.field_plan is descriptor.field_plan
+
+
+class TestTermGetter(unittest.TestCase):
+    def _plan(self, fields_xml):
+        section = """
+        <core encoding="utf-8" fieldsTerminatedBy="\\t" linesTerminatedBy="\\n" fieldsEnclosedBy="" ignoreHeaderLines="0" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
+            <files><location>occurrence.txt</location></files>
+            <id index="0" />
+            {fields}
+        </core>
+        """.format(
+            fields=fields_xml
+        )
+        descriptor = DataFileDescriptor.make_from_metafile_section(
+            ET.fromstring(section)
+        )
+        return descriptor.field_plan
+
+    def test_returns_values_in_the_requested_order(self):
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b"/>'
+            '<field index="2" term="http://x/c"/>'
+        )
+        getter = plan.term_getter(["http://x/c", "http://x/a"])
+
+        assert ("third", "first") == getter(["first", "second", "third"])
+
+    def test_a_single_term_still_yields_a_tuple(self):
+        plan = self._plan('<field index="1" term="http://x/b"/>')
+        getter = plan.term_getter(["http://x/b"])
+
+        assert ("second",) == getter(["first", "second"])
+
+    def test_no_terms(self):
+        plan = self._plan('<field index="0" term="http://x/a"/>')
+        getter = plan.term_getter([])
+
+        assert () == getter(["first"])
+
+    def test_a_term_may_be_requested_twice(self):
+        plan = self._plan('<field index="0" term="http://x/a"/>')
+        getter = plan.term_getter(["http://x/a", "http://x/a"])
+
+        assert ("first", "first") == getter(["first"])
+
+    def test_default_only_term_yields_the_constant(self):
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field term="http://x/country" default="Belgium"/>'
+        )
+        getter = plan.term_getter(["http://x/country", "http://x/a"])
+
+        assert ("Belgium", "first") == getter(["first"])
+
+    def test_default_fills_an_empty_cell(self):
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b" default="fallback"/>'
+        )
+        getter = plan.term_getter(["http://x/b"])
+
+        assert ("value",) == getter(["first", "value"])
+        assert ("fallback",) == getter(["first", ""])
+
+    def test_missing_value_without_default_becomes_empty_string(self):
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b" default=""/>'
+        )
+        getter = plan.term_getter(["http://x/b"])
+
+        assert ("",) == getter(["first", ""])
+
+    def test_unknown_terms_are_named_in_the_error(self):
+        plan = self._plan('<field index="0" term="http://x/a"/>')
+
+        with pytest.raises(ValueError) as excinfo:
+            plan.term_getter(["http://x/missing", "http://x/a", "http://x/gone"])
+
+        message = str(excinfo.value)
+        assert "http://x/missing" in message
+        assert "http://x/gone" in message
+        assert "http://x/a" not in message
+
+    def test_short_row_raises_invalid_archive(self):
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="4" term="http://x/e"/>'
+        )
+        getter = plan.term_getter(["http://x/e"])
+
+        with pytest.raises(InvalidArchive):
+            getter(["first", "second"])
+
+    def test_terms_may_be_a_one_shot_iterable(self):
+        # term_getter() used to iterate `terms` three times internally (missing, indexes,
+        # defaults). A generator is exhausted after the first pass, which silently made
+        # every later pass - and therefore every returned tuple - empty.
+        plan = self._plan(
+            '<field index="0" term="http://x/a"/>'
+            '<field index="1" term="http://x/b"/>'
+        )
+        expected = ("second", "first")
+
+        terms_list = ["http://x/b", "http://x/a"]
+        assert expected == plan.term_getter(t for t in terms_list)(["first", "second"])
+
+        # A tuple and a set of a single term must still work (the normalisation must not
+        # break non-list iterables that already worked before).
+        assert expected == plan.term_getter(tuple(terms_list))(["first", "second"])
+        assert ("second",) == plan.term_getter({"http://x/b"})(["first", "second"])
+
+    def test_a_declared_term_named_id_wins_over_the_key_column(self):
+        """Terms in metafile-less archives are raw header names, so one can be "id".
+
+        The declared term wins, which is what row.data["id"] already returns.
+        """
+        section = """
+        <core encoding="utf-8" fieldsTerminatedBy="," linesTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="0" rowType="http://rs.tdwg.org/dwc/terms/Occurrence">
+            <files><location>occurrence.txt</location></files>
+            <id index="0" />
+            <field index="1" term="id"/>
+        </core>
+        """
+        descriptor = DataFileDescriptor.make_from_metafile_section(ET.fromstring(section))
+        getter = descriptor.field_plan.term_getter(["id"])
+
+        assert ("declared",) == getter(["key", "declared"])