Звіт про помилку загубленого об’єкта PyMuPDF, кого не вистачає?

Якщо ви використовуєте PyMuPDF для обробки PDF, ви можете зустріти RuntimeError: orphaned object: parent is None після виконання delete_page(), insert_pdf() або select(), а потім використання об’єкта page, отриманого раніше. Ця стаття написана для розробників, які пишуть сценарії автоматизації PDF і потребують видаляти сторінки або переставляти сторінки пакетами. Прочитавши це, ви дізнаєтеся, що викликає цю помилку, як безпечно повторно отримати сторінки та в яких випадках вона не застосовується.

Ця помилка не вказує на витік пам’яті чи пошкодження файлу. Це механізм захисту, який активно запускає PyMuPDF: дочірні об’єкти, такі як Сторінка, Посилання та Анотація, залежать від життєвого циклу батьківського Документа. Після зміни структури документа попередні посилання стануть недійсними.

Висновок одним реченням

Після зміни структури не використовуйте повторно старий об’єкт Page. Замість цього використовуйте doc[n], щоб повторно отримати сторінку, і спочатку зберіть номери сторінок під час пакетних операцій.

Чому сторінка не може існувати незалежно від документа

PyMuPDF — це прив’язка Python для бібліотеки C MuPDF, яка об’єднує дворівневу модель пам’яті через SWIG. Об’єкти Python — це просто дескриптори для структур C, а дані сторінок, списки анотацій і дерева посилань — усі вони розміщені в купі C.

Документ і сторінка мають міцний зв’язок власності один до багатьох, а не слабку посилання. Під час виклику delete_page(), insert_pdf(), select() та інших методів, які змінюють структуру, MuPDF перебудує внутрішнє дерево сторінок, і початковий покажчик сторінки рівня C буде звільнено відповідно. SWIG не може автоматично виявити цю каскадну помилку, тому PyMuPDF встановить атрибут parent існуючої сторінки та її підоб’єктів на None на рівні Python і створить виняток під час наступного доступу, щоб уникнути помилок сегментів, спричинених висячими покажчиками.

Це означає, що кожна структурна модифікація є «глобальним перезавантаженням». Навіть якщо ви видалите лише сторінку 5, попередньо кешований об’єкт сторінки 1 більше не дійсний. Це проектний контракт, а не помилка: життєвим циклом дочірнього об’єкта повністю керує батьківський об’єкт, і він не може пережити структурні зміни.

Слід зазначити, що цей механізм застосовується лише до об’єктів, прив’язаних до рівня C. Список каталогів, який повертає doc.get_toc(), є чистим об’єктом Python і не підлягає цьому обмеженню, але вам потрібно самостійно забезпечити синхронізацію даних. Офіційні інструкції щодо узгодженості об’єктів див. у PyMuPDF Додаток 3: Забезпечення узгодженості важливих об’єктів; для методичних інструкцій, пов’язаних зі структурою документа, зверніться до Методи структури документа PyMuPDF.

Синтетичний приклад: правильний пошук і типові помилки меж

Вхідні дані нижче є синтетичною конструкцією, яка не покладається на справжній PDF-файл і використовується для демонстрації правил життєвого циклу.

Правильний підхід: після зміни структури повторно отримайте об’єкт сторінки через doc[n]. Новий об’єкт вказує на новий екземпляр рівня C, parent дійсний.

Типова помилка: продовження використання старого посилання на page після delete_page() або видалення сторінок під час проходження в циклі. Перше безпосередньо ініціює виняток, що залишився без змін; останнє може спричинити логічні помилки через зсув індексу або спричинити повторні помилки сторінки.

Принцип обробки: не використовуйте повторно старі змінні сторінки після зміни структури. Якщо потрібні пакетні операції, спочатку зберіть номери сторінок для обробки, а потім повторно витягніть сторінки після завершення структурних змін. Анотації та посилання однакові. Вони прикріплені до сторінки. Якщо сторінка зазнає невдачі, вони також зазнають невдачі.

Цей приклад лише ілюструє правила життєвого циклу об’єкта і не представляє повної бізнес-логіки. Перед фактичним використанням запустіть його у своєму власному середовищі із заблокованими версіями залежностей і підготуйте легальні PDF-файли як вхідні дані.

Приклад сторінки безпеки на Python

# 依赖: pymupdf >= 1.24.0（需自行确认版本兼容性）
# 本示例在内存中构造合成PDF，无需外部文件，仅用于演示生命周期规则
import pymupdf

# 构造含3页的合成文档（模拟真实文档结构）
doc = pymupdf.open()
for i in range(3):
    page = doc.new_page(width=200, height=300)
    page.insert_text((50, 100), f"page {i}")

# ❌ 错误示范（已注释以避免中断）:
# old_page = doc[0]
# doc.delete_page(1)
# print(old_page.rect)  # 触发 RuntimeError: orphaned object

# ✅ 正确做法：结构变更后必须重新取页
doc.delete_page(1)  # 删除中间页，触发文档结构重置
new_page = doc[0]   # 重新获取，此时parent指向当前doc
assert new_page.parent is not None, "Page must have valid parent"
assert len(doc) == 2, "Document should have 2 pages after deletion"

# 验证内容仍可读取（确认新对象有效）
text = new_page.get_text()
assert "page 0" in text, "Text content should persist in valid page"

# 清理资源
doc.close()

Цей код повністю самодостатній і використовує pymupdf.open() для створення документа в пам’яті та уникнення ризиків вводу/виведення файлів. Оператор assert перевіряє три ключові очікування: дійсність батьківського об’єкта, правильність номера сторінки та читабельність вмісту.

Якщо він не запускається у вашому середовищі, спочатку перевірте, чи версія PyMuPDF підтримує властивості new_page() і parent. Існують відмінності в API між різними версіями.

Таблиця рішень щодо прийняття та обробки винятків

Незастосовний діапазон: Ця таблиця охоплює лише несправності, пов'язані з життєвим циклом об'єкта. Якщо сам PDF зашифрований, пошкоджений або використовує нестандартні розширення, сиротовий механізм не буде активований, і потрібні інші діагностичні методи. Прийняття від кінця до кінця має поєднуватися з реальними зразками документації; приклади коду лише підтверджують контракти API.

📊 Порівняння ядра

🎯 Який метод тобі підходить?

Якщо потрібно видалити, вставити або переставити сторінки

Після кожної структурної зміни використовуйте doc[n] для повторного вибору сторінки; не зберігайте старі змінні.

Якщо хочеш пакетно видаляти кілька сторінок

Спочатку зберіть список номерів сторінок, а потім виконайте видалення рівномірно, щоб уникнути одночасного редагування під час перегляду.

Якщо ви працюєте над анотаціями або посиланнями

Перед використанням перевірте, чи є parent дійсним; анотації не створять помилок при невдачі анотації, тому необхідні явні перевірки.

Якщо ви маєте справу з зашифрованими, пошкодженими або нестандартними PDF-файлами

Сироті помилки можуть не допомогти знайти проблему і потребують комбінації з іншими діагностичними методами.

❓ Поширені запитання (FAQ)

1. Якщо сторінка не була видалена, чому попередній об'єкт сторінки також став недійсним?

Щоразу, коли структура документа змінюється, внутрішньое дерево сторінок відновлюється, і раніше кешовані об'єкти сторінки стають недійсними. Це контракт на дизайн, а не баг.

2. doc.get_toc(): Чи показує повернутий каталог також сироту помилку?

Ні. Список каталогів — це чистий об'єкт на Python, який не обмежений цим механізмом, але вам потрібно самостійно переконатися, що він синхронізується зі структурою документа.

3. Якщо виникає помилка, чи означає це, що файл пошкоджений?

Ні. Ця помилка свідчить про проблему життєвого циклу об'єкта і не означає, що файл пошкоджений або є витік пам'яті.

4. Як я можу переконатися, що анотації не були втрачені через недійсність сторінки?

Передопераційна перевірка annot.parent is not None. Таблиця рішень у статті також рекомендує автоматизувати цю перевірку.

📝 Резюме

Основна помилка сиротового об'єкта полягає в тому, що структурні зміни зроблять стару сторінку та її дочірні об'єкти недійсними, тому після зміни використовуйте doc[n] для отримання сторінки та збору номерів сторінок під час пакетних операцій. Приклади коду та таблиці рішень можуть допомогти відтворити правила, але ефект файлу все одно потрібно перевіряти пункт за елементом тривожними семплами.

Досвід зараз: завантажте документ, щоб почати переклад, зберігаючи оригінальне форматування