mrrc 0.9.1

"""
Queue-Based State Machine for __next__() Method

Tests verify that PyMARCReader.__next__() correctly uses the queue-based
state machine in BatchedReader:
- STATE 1 (CHECK_QUEUE_NON_EMPTY): If the queue has records, pop and return
- STATE 2 (CHECK_EOF_STATE): If EOF reached, return None idempotently
- STATE 3 (FILL_BATCH): Otherwise, read and parse a batch (up to 200
  records / 300 KB)

This test suite confirms:
1. Queue is consulted before I/O (O(1) operation on subsequent calls)
2. EOF is idempotent (repeated calls return None without I/O)
3. A batch is read under one GIL hold and parsed in a single GIL release,
   so the GIL is cycled once per batch rather than once per record
"""

import io

import pytest

from mrrc import MARCReader, MARCWriter


class TestQueueStateMachine:
    """Test the queue-based state machine in __next__()"""

    def test_first_call_reads_batch(self, fixture_1k):
        """First __next__() call should read full batch (100 records)"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # First call triggers read_batch()
        rec1 = next(reader)
        assert rec1 is not None
        assert rec1.leader is not None

    def test_subsequent_calls_use_queue(self, fixture_1k):
        """Subsequent calls should pop from queue without I/O"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # First call reads batch of 100
        rec1 = next(reader)
        assert rec1 is not None

        # Next 99 calls should come from queue (no batch read)
        for i in range(99):
            rec = next(reader)
            assert rec is not None
            # Verify we got different records
            if i > 0:
                # Just verify record structure is valid
                assert rec.leader is not None

    def test_eof_idempotence(self, fixture_1k):
        """After EOF, repeated calls should return None idempotently"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Consume all records
        records = list(reader)
        assert len(records) > 0

        # Repeated calls should still return None (StopIteration)
        for _ in range(5):
            with pytest.raises(StopIteration):
                next(reader)

    def test_iteration_semantic_unchanged(self, fixture_1k):
        """Iterator protocol should work unchanged (yield all records)"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        records = list(reader)
        assert len(records) == 1000

        # Verify all records are valid
        for rec in records:
            assert rec.leader is not None

    def test_queue_reduces_gil_pressure(self, fixture_10k):
        """
        With batching, GIL is acquired ~100 times for 1000 records instead of 1000.
        This test verifies the structure supports this but actual GIL measurement
        is done in test_batch_reading_c1.py
        """
        reader = MARCReader(io.BytesIO(fixture_10k))

        # Consume 100 records - should be mostly from queue after first batch read
        records = []
        for i, rec in enumerate(reader):
            records.append(rec)
            if i >= 99:  # First 100 records
                break

        assert len(records) == 100

        # Continue with next 100 - will trigger next batch read
        for i, rec in enumerate(reader):
            records.append(rec)
            if i >= 99:  # Next 100 records
                break

        assert len(records) == 200

    def test_first_batch_boundary(self, fixture_1k):
        """Test reading exactly to batch boundary (100 records)"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Read exactly 100 records
        records = []
        for i, rec in enumerate(reader):
            records.append(rec)
            if i >= 99:  # First 100 records (batch size)
                break

        assert len(records) == 100

        # Next read should continue from queue (records 101-200 from same batch)
        next_rec = next(reader)
        assert next_rec is not None

    def test_queue_ordering_preserved(self, fixture_1k):
        """Records should be returned in file order from queue"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Collect first 100 records
        records = []
        for i, rec in enumerate(reader):
            records.append(rec)
            if i >= 99:
                break

        # Each record should have sequential IDs (if present)
        # At minimum, verify structure consistency
        assert len(records) == 100
        for rec in records:
            leader = rec.leader
            assert leader is not None
            # Leader is 24 characters as per MARC standard
            assert len(str(leader)) > 0

    def test_read_record_legacy_api_uses_queue(self, fixture_1k):
        """Legacy read_record() method should also use queue state machine"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Legacy API
        rec1 = reader.read_record()
        assert rec1 is not None

        rec2 = reader.read_record()
        assert rec2 is not None

        # Both records should be different
        # (they come from same batch, just different records)

    def test_mixed_iteration_and_read_record(self, fixture_1k):
        """Can mix __next__ and read_record calls"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Use __next__
        rec1 = next(reader)
        assert rec1 is not None

        # Use read_record (legacy)
        rec2 = reader.read_record()
        assert rec2 is not None

        # Back to __next__
        rec3 = next(reader)
        assert rec3 is not None

    def test_reader_repr_reflects_state(self, fixture_1k):
        """Reader repr should indicate reader state"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Just verify repr doesn't crash
        repr_str = repr(reader)
        assert repr_str is not None
        assert "MARCReader" in repr_str

        # Consume all
        list(reader)

        # Repr should still work after consumption
        repr_str2 = repr(reader)
        assert repr_str2 is not None


class TestQueueEdgeCases:
    """Test edge cases in queue-based state machine"""

    def test_batch_boundary_1000_records(self, fixture_1k):
        """File with 1000 records (10 batches of 100)"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        records = list(reader)
        assert len(records) == 1000

        # EOF on next call
        with pytest.raises(StopIteration):
            next(reader)

    def test_batch_boundary_10000_records(self, fixture_10k):
        """File with 10000 records (100 batches of 100)"""
        reader = MARCReader(io.BytesIO(fixture_10k))

        records = list(reader)
        assert len(records) == 10000

    def test_batch_boundary_10000_records_alt(self, fixture_10k):
        """File with 10000 records (100 batches of 100) - verifies same path as larger files"""
        reader = MARCReader(io.BytesIO(fixture_10k))

        records = list(reader)
        assert len(records) == 10000

    def test_queue_empty_check(self, fixture_1k):
        """Queue should be checked before EOF check"""
        reader = MARCReader(io.BytesIO(fixture_1k))

        # Reading all should work correctly even as queue empties
        count = 0
        for rec in reader:
            count += 1
            assert rec is not None

        assert count == 1000

    def test_empty_input_yields_no_records(self):
        """Empty input hits EOF before the first batch fills: zero
        records, no exception."""
        reader = MARCReader(io.BytesIO(b""))

        records = list(reader)
        assert len(records) == 0

    def test_single_record_file(self, fixture_small):
        """A file holding exactly one record fills a partial batch of
        one and then EOFs cleanly."""
        # Build a single-record file from the first fixture record.
        source = MARCReader(io.BytesIO(fixture_small))
        rec = next(source)

        output = io.BytesIO()
        writer = MARCWriter(output)
        writer.write_record(rec)
        writer.close()

        reader = MARCReader(io.BytesIO(output.getvalue()))
        records = list(reader)
        assert len(records) == 1
        with pytest.raises(StopIteration):
            next(reader)

    def test_batch_boundary_201_crosses_hard_cap(self, fixture_1k):
        """Reading one record past the 200-record batch hard cap must
        deliver record 201 from a fresh batch with nothing lost."""
        reader = MARCReader(io.BytesIO(fixture_1k))

        records = []
        for i, rec in enumerate(reader):
            records.append(rec)
            if i >= 200:
                break

        assert len(records) == 201
        assert all(rec is not None for rec in records)