tencentcloud-sdk-python-tmt unpinned dependency breaks import (TextTranslateRequest removed in 3.1.x)

Author: jx888-maxCreated Jul 13, 2026Updated Jul 26, 2026

Description

Fresh install fails at import time regardless of which translation -s engine is selected, because pdf2zh/translator.py unconditionally imports TextTranslateRequest/TextTranslateResponse from tencentcloud.tmt.v20180321.models at module load. pyproject.toml declares tencentcloud-sdk-python-tmt with no version constraint, so a fresh install pulls the latest release (currently 3.1.129), which no longer contains these classes (only BoundingBox, Coord, ImageTranslateLLMRequest/Response, RotateParagraphRect, TransDetail remain).

Steps to reproduce

  1. uv tool install pdf2zh (or pip install pdf2zh) on a clean environment
  2. pdf2zh document.pdf -lo zh
  3. Crash before any translation happens:
ImportError: cannot import name 'TextTranslateRequest' from 'tencentcloud.tmt.v20180321.models'

Happens even with the default Google engine, since the Tencent import is unconditional.

Environment

  • pdf2zh 1.9.11 (installed via uv tool install -e . from main)
  • Python 3.12.13, macOS 15 (Darwin 24.3.0), arm64
  • tencentcloud-sdk-python-tmt 3.1.129 (latest at install time)

Workaround

Pin tencentcloud-sdk-python-tmt==3.0.1257 (last version that still has TextTranslateRequest/TextTranslateResponse).

Suggested fix

Add an upper bound for tencentcloud-sdk-python-tmt in pyproject.toml (e.g. <3.1), or make the Tencent import lazy so an incompatible/missing Tencent SDK doesn't break unrelated translation engines.

Source: PDFMathTranslate/PDFMathTranslate