shellscripts 0.23.1__py3-none-any.whl → 0.24.0__py3-none-any.whl

shell_scripts/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.23.1"
+__version__ = "0.24.0"
 
 from .core import main  # noqa: F401
 

shell_scripts/commands/pdf_split_by_format.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
+import errno
 import os
 import re
+import shutil
 import subprocess
 import tempfile
 
@@ -102,7 +104,48 @@ def _extract_toc_for_range(data_file, start, end):
     return "\n".join(result)
 
 
+def _promote_temp_output(temp_output, output_file):
+    """
+    @brief Promote one pdftk-produced temporary artifact onto the final output path.
+    @details Attempts same-device atomic replacement via `os.replace`. On
+      `OSError` with `errno.EXDEV` (temporary directory and output directory
+      located on different filesystems), falls back to `shutil.move`, which
+      copies the artifact content and removes the temporary source. All other
+      `OSError` values propagate unchanged to preserve pre-existing failure
+      semantics. Time complexity O(1) for same-device renames, O(n) over file
+      size for the cross-device copy fallback.
+    @param temp_output {str} Temporary artifact path produced by the external tool chain.
+    @param output_file {str} Final chunk path that must receive the artifact content.
+    @return {None} Applies destination filesystem mutation.
+    @throws {OSError} Propagated for non-EXDEV replacement failures.
+    @satisfies REQ-031, REQ-032
+    """
+    try:
+        os.replace(temp_output, output_file)
+    except OSError as error:
+        if error.errno != errno.EXDEV:
+            raise
+        shutil.move(temp_output, output_file)
+
+
 def _apply_toc(output_file, toc_content):
+    """
+    @brief Reapply in-range TOC data to one generated chunk file.
+    @details Writes `toc_content` into a temporary `.info` payload, prepares
+      temporary PDF artifacts, strips object streams from `output_file` via
+      `qpdf`, rebuilds the chunk with TOC metadata via `pdftk update_info`,
+      and promotes the artifact onto `output_file` through
+      `_promote_temp_output` so a temporary directory on a different
+      filesystem cannot silently drop the chunk TOC. Tool-chain failures are
+      contained without aborting the split loop. Time complexity O(m) over
+      TOC content size plus external process latency.
+    @param output_file {str} Generated chunk path receiving the TOC metadata.
+    @param toc_content {str} Range-filtered pdftk dump-data bookmark payload.
+    @return {None} Mutates `output_file` content on success.
+    @throws {OSError} Propagated when temporary payload creation, unlink, or
+      non-EXDEV promotion fails.
+    @satisfies REQ-032
+    """
     if not toc_content.strip():
         return
     with tempfile.NamedTemporaryFile(mode="w", suffix=".info", delete=False) as f:
@@ -124,7 +167,7 @@ def _apply_toc(output_file, toc_content):
                 capture_output=True,
             )
             if r2.returncode == 0:
-                os.replace(with_toc, output_file)
+                _promote_temp_output(with_toc, output_file)
             else:
                 os.unlink(with_toc)
                 print(f"   [!] Warning: unable to update TOC for '{output_file}'.")

shell_scripts/commands/pdf_split_by_toc.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
+import errno
 import os
 import re
+import shutil
 import subprocess
 import tempfile
 
@@ -76,7 +78,48 @@ def _sanitize_title(title):
     return safe.strip("-")
 
 
+def _promote_temp_output(temp_output, output_file):
+    """
+    @brief Promote one pdftk-produced temporary artifact onto the final output path.
+    @details Attempts same-device atomic replacement via `os.replace`. On
+      `OSError` with `errno.EXDEV` (temporary directory and output directory
+      located on different filesystems), falls back to `shutil.move`, which
+      copies the artifact content and removes the temporary source. All other
+      `OSError` values propagate unchanged to preserve pre-existing failure
+      semantics. Time complexity O(1) for same-device renames, O(n) over file
+      size for the cross-device copy fallback.
+    @param temp_output {str} Temporary artifact path produced by the external tool chain.
+    @param output_file {str} Final chunk path that must receive the artifact content.
+    @return {None} Applies destination filesystem mutation.
+    @throws {OSError} Propagated for non-EXDEV replacement failures.
+    @satisfies REQ-031, REQ-032
+    """
+    try:
+        os.replace(temp_output, output_file)
+    except OSError as error:
+        if error.errno != errno.EXDEV:
+            raise
+        shutil.move(temp_output, output_file)
+
+
 def _apply_toc_to_file(output_file, toc_content):
+    """
+    @brief Reapply rebased TOC data to one generated chunk file.
+    @details Writes `toc_content` into a temporary `.info` payload, strips
+      object streams from `output_file` via `qpdf`, rebuilds the chunk with
+      TOC metadata via `pdftk update_info`, and promotes the artifact onto
+      `output_file` through `_promote_temp_output` so a temporary directory
+      on a different filesystem cannot crash chunk generation. Emits a
+      warning and keeps the original chunk when the tool chain fails.
+      Time complexity O(m) over TOC content size plus external process
+      latency.
+    @param output_file {str} Generated chunk path receiving the TOC metadata.
+    @param toc_content {str} Rebased pdftk dump-data bookmark payload.
+    @return {None} Mutates `output_file` content on success.
+    @throws {OSError} Propagated when temporary payload creation, unlink, or
+      non-EXDEV promotion fails.
+    @satisfies REQ-031
+    """
     if not toc_content.strip():
         return
     with tempfile.NamedTemporaryFile(mode="w", suffix=".info", delete=False) as f:
@@ -95,7 +138,7 @@ def _apply_toc_to_file(output_file, toc_content):
                 capture_output=True,
             )
             if r2.returncode == 0:
-                os.replace(with_toc, output_file)
+                _promote_temp_output(with_toc, output_file)
             else:
                 if os.path.exists(with_toc):
                     os.unlink(with_toc)

{shellscripts-0.23.1.dist-info → shellscripts-0.24.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellscripts
-Version: 0.23.1
+Version: 0.24.0
 Summary: Execute useful shell scripts via an uvx-compatible CLI interface.
 Author: Francesco Rolando
 License-Expression: GPL-3.0-only
@@ -31,7 +31,7 @@ Dynamic: license-file
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# s/shellScripts (0.23.1)
+# s/shellScripts (0.24.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

{shellscripts-0.23.1.dist-info → shellscripts-0.24.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-shell_scripts/__init__.py,sha256=tcta0Vrn-w5n4wRkcb6xWB5jcyslWz3oKUyNDDU4ago,96
+shell_scripts/__init__.py,sha256=a6rN3qPobydw-A4eFoUNo6Srdf1OtkoPSloLLg3Yuic,96
 shell_scripts/__main__.py,sha256=-wEmwKTfeY5TphAH82E38XRPoB4KT5QDLDgRZz84PTs,83
 shell_scripts/config.py,sha256=YUs8QWsZ31lJPrMpFqvn7YLQdseQnlaiu7OXcXsKdEw,12640
 shell_scripts/core.py,sha256=rhgy9xduzkujsjD4NRL2AYvtNI3yTVnPThzEAzyMWUM,11204
@@ -22,8 +22,8 @@ shell_scripts/commands/kiro.py,sha256=NuD2Zx76azDQAWbJ8YcewshEogLmrd-Avu9feisqHy
 shell_scripts/commands/opencode.py,sha256=64I3IHrliAZ7C4jTU4WLxQcJHJohJcKex09yhegWUoc,1900
 shell_scripts/commands/pdf_crop.py,sha256=VliRAMHMjnSQK9mZhNoghftZAVGZeJG6xhrihcuuawQ,15135
 shell_scripts/commands/pdf_merge.py,sha256=vTTlUv8oVYUo9U45b4yUpK4x0unIwctgXV7g5exvihc,5996
-shell_scripts/commands/pdf_split_by_format.py,sha256=kWID9sadX9cf0jMWFqTyCFMRHwAFNZVmnp24IlcN1H8,7573
-shell_scripts/commands/pdf_split_by_toc.py,sha256=I027ldWXat8ODafn3KRD1X52yeUP2xez1PX-kFNptAg,6674
+shell_scripts/commands/pdf_split_by_format.py,sha256=yG4Vbv1oPaHEElMK-TUqDVoqM6G1O3UY0nVcO5RsqMY,9789
+shell_scripts/commands/pdf_split_by_toc.py,sha256=Q9VNqBoPQQOd4Dm14dm2S8W2JPc3I3WuhQYMxXKX55Q,8848
 shell_scripts/commands/pdf_tiler_090.py,sha256=1eLCw9rqGN8LELB5lBvx6xfaTYc4Kci5YDK2EvnHG6E,1781
 shell_scripts/commands/pdf_tiler_100.py,sha256=U-DlX_PJPHL2P2p0wvWMzb-XkxVYn5-Jb1vqlBzIAqA,1805
 shell_scripts/commands/pdf_toc_clean.py,sha256=7GroNjVbOoh184AbYoqXSVdK_RHqA3y5urjkZ4lcJbw,5907
@@ -37,9 +37,9 @@ shell_scripts/commands/video2h265.py,sha256=Sr_UWGz_V77x4anmuy8kiWZv5I_AOFlV0WDn
 shell_scripts/commands/view_cmd.py,sha256=qHEivQHZpZCTE3VSFP1ay2SuqgancQlEKxJcKtyeqNA,1827
 shell_scripts/commands/vscode_cmd.py,sha256=Rkcjt5A1HMzqJoh2Yz9VRGoLP-L3qpRO5hkcSrzOmvA,1461
 shell_scripts/commands/vsinsider_cmd.py,sha256=KTTv1cVpJO-u1ktxOE0W_o4AAmz20pAvkDtyhpU9XBg,1548
-shellscripts-0.23.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-shellscripts-0.23.1.dist-info/METADATA,sha256=BihFSRKVrmcCCAiiJLu0B5seR0Unkn0W2-WCrrgWo0A,10985
-shellscripts-0.23.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-shellscripts-0.23.1.dist-info/entry_points.txt,sha256=9ICAgH87fxHBzi3f6JXIVcsPWzAKsCh4_1xS8JThQ0M,85
-shellscripts-0.23.1.dist-info/top_level.txt,sha256=7bDVqjcR5CfCCArCP4X4e9gYJ-ua8z-GfQeHbAo8rCY,14
-shellscripts-0.23.1.dist-info/RECORD,,
+shellscripts-0.24.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+shellscripts-0.24.0.dist-info/METADATA,sha256=93w8nhYX9LfkcAQxSMCwdBYXNnkYdwjUgTjCG4HNIoo,10985
+shellscripts-0.24.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+shellscripts-0.24.0.dist-info/entry_points.txt,sha256=9ICAgH87fxHBzi3f6JXIVcsPWzAKsCh4_1xS8JThQ0M,85
+shellscripts-0.24.0.dist-info/top_level.txt,sha256=7bDVqjcR5CfCCArCP4X4e9gYJ-ua8z-GfQeHbAo8rCY,14
+shellscripts-0.24.0.dist-info/RECORD,,