epub-translator 0.1.4__tar.gz → 0.1.5__tar.gz

{epub_translator-0.1.4 → epub_translator-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-translator
-Version: 0.1.4
+Version: 0.1.5
 Summary: Translate the epub book using LLM. The translated book will retain the original text and list the translated text side by side with the original text.
 License: MIT
 Keywords: epub,llm,translation,translator
@@ -238,16 +238,17 @@ translate(
 
 ### Error Handling with `on_fill_failed`
 
-Monitor and handle translation errors using the `on_fill_failed` callback:
+Monitor translation errors using the `on_fill_failed` callback. The system automatically retries failed translations up to `max_retries` times (default: 5). Most errors are recovered during retries and don't affect the final output.
 
 ```python
 from epub_translator import FillFailedEvent
 
 def handle_fill_error(event: FillFailedEvent):
-    print(f"Translation error (attempt {event.retried_count}):")
-    print(f"  {event.error_message}")
+    # Only log critical errors that will affect the final EPUB
     if event.over_maximum_retries:
-        print("  Maximum retries exceeded!")
+        print(f"Critical error after {event.retried_count} attempts:")
+        print(f"  {event.error_message}")
+        print("  This error will be present in the final EPUB file!")
 
 translate(
     source_path="source.epub",
@@ -259,10 +260,32 @@ translate(
 )
 ```
 
+**Understanding Error Severity:**
+
 The `FillFailedEvent` contains:
 - `error_message: str` - Description of the error
-- `retried_count: int` - Current retry attempt number
-- `over_maximum_retries: bool` - Whether max retries has been exceeded
+- `retried_count: int` - Current retry attempt number (1 to max_retries)
+- `over_maximum_retries: bool` - Whether the error is critical
+
+**Error Categories:**
+
+- **Recoverable errors** (`over_maximum_retries=False`): Errors during retry attempts. The system will continue retrying and may resolve these automatically. Safe to ignore in most cases.
+
+- **Critical errors** (`over_maximum_retries=True`): Errors that persist after all retry attempts. These will appear in the final EPUB file and should be investigated.
+
+**Advanced Usage:**
+
+For verbose logging during translation debugging:
+
+```python
+def handle_fill_error(event: FillFailedEvent):
+    if event.over_maximum_retries:
+        # Critical: affects final output
+        print(f"❌ CRITICAL: {event.error_message}")
+    else:
+        # Informational: system is retrying
+        print(f"⚠️  Retry {event.retried_count}: {event.error_message}")
+```
 
 ### Dual-LLM Architecture
 

{epub_translator-0.1.4 → epub_translator-0.1.5}/README.md

@@ -205,16 +205,17 @@ translate(
 
 ### Error Handling with `on_fill_failed`
 
-Monitor and handle translation errors using the `on_fill_failed` callback:
+Monitor translation errors using the `on_fill_failed` callback. The system automatically retries failed translations up to `max_retries` times (default: 5). Most errors are recovered during retries and don't affect the final output.
 
 ```python
 from epub_translator import FillFailedEvent
 
 def handle_fill_error(event: FillFailedEvent):
-    print(f"Translation error (attempt {event.retried_count}):")
-    print(f"  {event.error_message}")
+    # Only log critical errors that will affect the final EPUB
     if event.over_maximum_retries:
-        print("  Maximum retries exceeded!")
+        print(f"Critical error after {event.retried_count} attempts:")
+        print(f"  {event.error_message}")
+        print("  This error will be present in the final EPUB file!")
 
 translate(
     source_path="source.epub",
@@ -226,10 +227,32 @@ translate(
 )
 ```
 
+**Understanding Error Severity:**
+
 The `FillFailedEvent` contains:
 - `error_message: str` - Description of the error
-- `retried_count: int` - Current retry attempt number
-- `over_maximum_retries: bool` - Whether max retries has been exceeded
+- `retried_count: int` - Current retry attempt number (1 to max_retries)
+- `over_maximum_retries: bool` - Whether the error is critical
+
+**Error Categories:**
+
+- **Recoverable errors** (`over_maximum_retries=False`): Errors during retry attempts. The system will continue retrying and may resolve these automatically. Safe to ignore in most cases.
+
+- **Critical errors** (`over_maximum_retries=True`): Errors that persist after all retry attempts. These will appear in the final EPUB file and should be investigated.
+
+**Advanced Usage:**
+
+For verbose logging during translation debugging:
+
+```python
+def handle_fill_error(event: FillFailedEvent):
+    if event.over_maximum_retries:
+        # Critical: affects final output
+        print(f"❌ CRITICAL: {event.error_message}")
+    else:
+        # Informational: system is retrying
+        print(f"⚠️  Retry {event.retried_count}: {event.error_message}")
+```
 
 ### Dual-LLM Architecture
 

{epub_translator-0.1.4 → epub_translator-0.1.5}/epub_translator/xml_translator/submitter.py

@@ -122,11 +122,17 @@ class _Submitter:
                 last_tail_element = child_element
 
         for text_segments, child_node in node.items:
-            tail_element = tail_elements.get(id(child_node.raw_element), None)
+            anchor_element = _find_anchor_in_parent(node.raw_element, child_node.raw_element)
+            if anchor_element is None:
+                # 防御性编程：理论上 anchor_element 不应该为 None，
+                #           因为 _nest_nodes 已经通过 _check_includes 验证了包含关系。
+                continue
+
+            tail_element = tail_elements.get(id(anchor_element), None)
             items_preserved_elements: list[Element] = []
 
             if self._action == SubmitKind.REPLACE:
-                end_index = index_of_parent(node.raw_element, child_node.raw_element)
+                end_index = index_of_parent(node.raw_element, anchor_element)
                 items_preserved_elements = self._remove_elements_after_tail(
                     node_element=node.raw_element,
                     tail_element=tail_element,
@@ -137,11 +143,11 @@ class _Submitter:
                 node_element=node.raw_element,
                 text_segments=text_segments,
                 tail_element=tail_element,
+                anchor_element=anchor_element,
                 append_to_end=False,
-                ref_element=child_node.raw_element,
             )
             if items_preserved_elements:
-                insert_position = index_of_parent(node.raw_element, child_node.raw_element)
+                insert_position = index_of_parent(node.raw_element, anchor_element)
                 for i, elem in enumerate(items_preserved_elements):
                     node.raw_element.insert(insert_position + i, elem)
 
@@ -166,7 +172,7 @@ class _Submitter:
             node_element=node.raw_element,
             text_segments=node.tail_text_segments,
             tail_element=last_tail_element,
-            ref_element=None,
+            anchor_element=None,
             append_to_end=True,
         )
         if tail_preserved_elements:
@@ -208,7 +214,7 @@ class _Submitter:
         node_element: Element,
         text_segments: list[TextSegment],
         tail_element: Element | None,
-        ref_element: Element | None,
+        anchor_element: Element | None,
         append_to_end: bool,
     ) -> None:
         combined = self._combine_text_segments(text_segments)
@@ -225,14 +231,14 @@ class _Submitter:
                     append_text=combined.text,
                     will_inject_space=will_inject_space,
                 )
-            elif ref_element is None:
+            elif anchor_element is None:
                 node_element.text = self._append_text_in_element(
                     origin_text=node_element.text,
                     append_text=combined.text,
                     will_inject_space=will_inject_space,
                 )
             else:
-                ref_index = index_of_parent(node_element, ref_element)
+                ref_index = index_of_parent(node_element, anchor_element)
                 if ref_index > 0:
                     # 添加到前一个元素的 tail
                     prev_element = node_element[ref_index - 1]
@@ -253,10 +259,10 @@ class _Submitter:
             insert_position = index_of_parent(node_element, tail_element) + 1
         elif append_to_end:
             insert_position = len(node_element)
-        elif ref_element is not None:
+        elif anchor_element is not None:
             # 使用 ref_element 来定位插入位置
             # 如果文本被添加到前一个元素的 tail，则在前一个元素之后插入
-            ref_index = index_of_parent(node_element, ref_element)
+            ref_index = index_of_parent(node_element, anchor_element)
             if ref_index > 0:
                 # 在前一个元素之后插入
                 insert_position = ref_index
@@ -346,6 +352,18 @@ def _nest_nodes(mappings: list[InlineSegmentMapping]) -> Generator[_Node, None,
             yield child_node
 
 
+def _find_anchor_in_parent(parent: Element, descendant: Element) -> Element | None:
+    for child in parent:
+        if child is descendant:
+            return descendant
+
+    for child in parent:
+        if _check_includes(child, descendant):
+            return child
+
+    return None
+
+
 def _fold_top_of_stack(stack: list[_Node]):
     child_node = stack.pop()
     if not stack:

{epub_translator-0.1.4 → epub_translator-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "epub-translator"
-version = "0.1.4"
+version = "0.1.5"
 description = "Translate the epub book using LLM. The translated book will retain the original text and list the translated text side by side with the original text."
 keywords = ["epub", "llm", "translation", "translator"]
 authors = [