Handle empty JSON Lines during header discovery

[umd0730]

fromjson(path, lines=True) raises RuntimeError: generator raised StopIteration for an empty file when no header is supplied. This also prevents reading the empty JSON Lines file produced by tojson([('id',)], path, lines=True).

Catch exhaustion during header discovery and yield an empty header tuple, matching an empty fromdicts([]) table. Explicit headers remain intact. Blank lines and malformed records still raise errors rather than being silently skipped.

Changes

• Handle empty input in iterjlines without changing the JSON array reader.
• Add six regression cases covering inferred/explicit headers, export/import of empty tables, repeat iteration, first-record preservation and invalid lines.
• Document empty JSON Lines behavior and add a changelog entry.

Validation

Windows / Python 3.12.14, current master 9a0b8448228b2575713dce93dacfc8451a4152b9:

• Before the fix: the inferred-header empty-input test fails with RuntimeError.
• After: python -m pytest petl -q --tb=short: 598 passed, 16 skipped.
• Optional integrations without dependencies/servers are skipped. There are five warnings, including unavailable database drivers and SQLite cursor-close warnings outside the JSON tests. No external database servers or full tox matrix were tested locally.

Checklist

• Includes regression tests, behavior documentation and changelog.
• Atomic, reversible fix; no unrelated source changes.
• Tested locally against current master.
• Upstream CI passed all 27 jobs for 643675d, including the OS/Python matrix and documentation tests. CodeQL and Read the Docs also passed.
• Coveralls reports 29/29 changed lines covered (100%) and no coverage regressions.
• Ready to review.

No new public function is introduced.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Handle empty JSON Lines during header discovery

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 10-20 Minutes

AI Description

• Return an empty-header table when header discovery encounters an empty JSON Lines file.
• Preserve explicit headers, valid first records, repeat iteration, and invalid-record errors.
• Document the behavior and add focused regression coverage.

Diagram

graph TD
  A["JSON Lines file"] --> B["fromjson"] --> C["JsonView iterator"] --> D{"Header supplied?"}
  D -->|No| E{"Input empty?"} -->|Yes| F["Empty header"] --> G["Table output"]
  D -->|Yes| G
  E -->|No| H["Infer header"] --> G

Loading

High-Level Assessment

The localized StopIteration handling in iterjlines is the best approach because it fixes only inferred-header JSON Lines processing. Changing iterpeek globally or pre-checking source size would broaden behavior unnecessarily, while the current implementation preserves explicit headers and malformed-record errors.

Files changed (3) +43 / -1

Bug fix (1) +8 / -1

json.pyHandle exhausted JSON Lines header discovery +8/-1

Handle exhausted JSON Lines header discovery

• Catches source exhaustion while peeking for an inferred header and yields an empty header tuple. Documents the resulting behavior without affecting explicit headers or JSON array processing.

petl/io/json.py

Tests (1) +32 / -0

test_json.pyCover empty and invalid JSON Lines behavior +32/-0

Cover empty and invalid JSON Lines behavior

• Adds regression coverage for inferred and explicit headers, empty export/import round trips, repeat iteration, first-record preservation, and malformed or blank records.

petl/test/io/test_json.py

Documentation (1) +3 / -0

changes.rstRecord empty JSON Lines fix in changelog +3/-0

Record empty JSON Lines fix in changelog

• Adds an unreleased changelog entry explaining that empty JSON Lines files now produce empty tables instead of raising RuntimeError during header discovery.

docs/changes.rst

[coveralls]

Coverage Report for CI Build 35119054967

Coverage increased (+0.02%) to 92.081%

Details

• Coverage increased (+0.02%) from the base build.
• Patch coverage: 29 of 29 lines across 2 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	15494
Covered Lines:	14267
Line Coverage:	92.08%
Coverage Strength:	0.92 hits per line

---

💛 - Coveralls