fix: replace removed BitStream with BitArray to support bitstring 5.x

GG
14d ago
+17-17

Fixes #626

bitstring 5.0.0 (released 2026-10-11) removed the old stream classes (BitStream / ConstBitStream). The dependency is declared as bitstring>=4.3.0 with no upper bound, so every fresh install now resolves to 5.x and crashes at import:

babeldoc/format/pdf/document_il/backend/pdf_creater.py", line 16, in <module>
    from bitstring import BitStream
ImportError: cannot import name 'BitStream' from 'bitstring'

Repo CI didn't catch this because it installs from uv.lock (still pinned to 4.x).

Fix

BitStream → BitArray in pdf_creater.py (17 references, single file):

  • The file only uses the write-side .append() semantics — no pos / read / peek read-position API anywhere.
  • In 4.x BitStream is a subclass of BitArray (MRO: BitStream → ConstBitStream → BitArray → Bits), so the swap is behavior-identical there.
  • In 5.x BitArray is the mutable class, i.e. the forward-compatible spelling.

No version pin needed; compatible with both 4.x and 5.x.

Verification

Editable install of this branch, then the exact no-secret E2E from checks.yml:

babeldoc --openai --openai-api-key ci-dummy-key \
  --files examples/ci/test.pdf \
  --only-parse-generate-pdf --skip-scanned-detection
  • bitstring 5.0.0: ✅ test.zh.dual.pdf / test.zh.mono.pdf generated
  • bitstring 4.4.0: ✅ same
  • ruff check on the changed file: clean

🤖 Generated with Claude Code

Summary by cubic

Fixes the import crash on fresh installs caused by bitstring 5.0.0 removing BitStream. The filed only uses .append() write semantics, and since 4.x BitStream is a subclass of BitArray, the swap is behavior-identical on both versions. CI didn't catch this because uv.lock still pins 4.x.