libbbf 0.2.4__cp312-cp312-win32.whl

libbbf-0.2.4.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.2
+Name: libbbf
+Version: 0.2.4
+Summary: Bound Book Format (BBF) tools and bindings
+Home-page: https://github.com/ef1500/libbbf
+Author: EF1500
+Author-email: rosemilovelockofficial@proton.me
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# libbbf-python: Bound Book Format (BBF) Tools & Python Bindings
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/libbbf.svg)](https://pypi.org/project/libbbf/)
+[![PyPI](https://img.shields.io/pypi/v/libbbf.svg)](https://pypi.org/project/libbbf/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Project Overview
+
+`libbbf-python` provides Python bindings and command-line tools for the Bound Book Format (BBF). The Bound Book Format is an archive format designed for digital books and comics. This package allows Python developers to programmatically create and read `.bbf` files, and provides convenient command-line utilities to convert between common archive formats (like CBZ/CBX) and BBF.
+
+The core of `libbbf-python` is a `pybind11` wrapper around the high-performance C++ `libbbf` library, ensuring speed and native integration.
+
+## Features
+
+*   **`libbbf` Python Bindings**: Access the full `BBFBuilder` (for creating BBF files) and `BBFReader` (for reading and extracting BBF files) functionality directly in Python.
+*   **`cbx2bbf` Command-Line Tool**: Convert one or more CBZ/CBX archives (or directories of images) into a single `.bbf` file. Supports advanced features like custom page ordering, section markers (chapters, volumes), and metadata.
+*   **`bbf2cbx` Command-Line Tool**: Extract the contents of a `.bbf` file back into a `.cbz` archive or an image directory. Supports integrity verification, section-specific extraction, and range extraction using keywords.
+*   **High Performance**: Leverages C++ for core operations (file I/O, hashing, memory mapping) for optimal speed.
+*   **Integrity Checks**: Built-in XXH3 hashing for robust data verification during creation and extraction.
+
+## Installation
+
+You can install `libbbf-python` directly from PyPI:
+
+```bash
+pip install libbbf
+```
+
+**Note on C++ Compiler:**
+For platforms where pre-built binary wheels are not available (e.g., specific Linux distributions or older Python versions), `pip` will attempt to build the package from source. This requires a C++ compiler (like GCC/Clang on Linux/macOS or MSVC on Windows) to be installed on your system.
+
+## Command-Line Tools Usage
+
+Once installed, two command-line tools will be available globally: `cbx2bbf` and `bbf2cbx`.
+
+### `cbx2bbf`: Create BBF Files from CBZ/Images
+
+**Usage:**
+```cbx2bbf <inputs...> [options] --output <output.bbf>
+```
+
+**Inputs:**
+Can be individual image files (`.png`, `.avif`, `.jpg`), directories containing images, or `.cbz`/`.cbx` archives.
+
+**Options:**
+*   `--output <output.bbf>`, `-o <output.bbf>`: **Required.** Specifies the output BBF filename.
+*   `--order <path.txt>`: Use a text file to define page order. Format: `filename:index` (e.g., `cover.png:1`, `credits.png:-1` for last page).
+*   `--sections <path.txt>`: Use a text file to define multiple sections. Format: `Name:Target[:Parent]`.
+*   `--section "Name:Target[:Parent]"`: Add a single section marker. Target can be a 1-based page index or a filename. Example: `--section "Chapter 1:001.png"` or `--section "Volume 1:my_comic.cbx:Series"`.
+*   `--meta "Key:Value"`: Add archival metadata (e.g., `--meta "Title:Akira"`).
+
+**Examples:**
+
+1.  **Basic Conversion:**
+    ```bash
+    cbx2bbf my_comic.cbz -o output.bbf
+    ```
+
+2.  **Converting Multiple CBZs with Sections and Metadata:**
+    ```bash
+    cbx2bbf vol1.cbz vol2.cbz \
+        --section "Volume 1:vol1.cbz" \
+        --section "Volume 2:vol2.cbz" \
+        --meta "Title:My Awesome Series" \
+        --meta "Author:Me" \
+        -o series.bbf
+    ```
+    *(Note: `vol1.cbz` and `vol2.cbz` as targets will automatically map to the first page of those archives after sorting)*
+
+3.  **Converting a Directory of Images with a Custom Order File:**
+    ```bash
+    # pages.txt content:
+    # cover.png:1
+    # page001.png:2
+    # ...
+    # credits.png:-1
+
+    cbx2bbf ./my_pages_folder/ --order pages.txt -o my_book.bbf
+    ```
+
+### `bbf2cbx`: Extract BBF Files
+
+**Usage:**
+```
+bbf2cbx <input.bbf> [options] --output <output.cbz_or_dir>
+```
+
+**Options:**
+*   `--output <output_path>`, `-o <output_path>`: **Required.** Output `.cbz` file or directory name.
+*   `--dir`: Extract to a directory instead of a `.cbz` archive.
+*   `--section "Name"`: Extract only a specific section defined in the BBF.
+*   `--rangekey "String"`: When extracting a section, find the end of extraction by matching this string against the *next* section's title. Useful for extracting "Vol 1" until "Vol 2" begins.
+*   `--verify`: Perform a full XXH3 integrity check on all assets and the directory hash before extraction.
+*   `--info`: Display book structure and metadata without extracting.
+
+**Examples:**
+
+1.  **Extract entire BBF to CBZ with Verification:**
+    ```bash
+    bbf2cbx my_book.bbf -o my_book_extracted.cbz --verify
+    ```
+
+2.  **Extract a specific section to a folder:**
+    ```bash
+    bbf2cbx series.bbf --section "Volume 1" --dir -o ./output/vol1/
+    ```
+
+3.  **Extract a range using `rangekey`:**
+    ```bash
+    bbf2cbx series.bbf --section "Volume 1" --rangekey "Volume 2" -o vol1_only.cbz
+    ```
+
+4.  **Display BBF Information:**
+    ```bash
+    bbf2cbx series.bbf --info
+    ```
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome! For libbbf, free to check the [issues page](https://github.com/ef1500/libbbf/issues) (or create one if it doesn't exist yet).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---

libbbf-0.2.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+libbbf.cp312-win32.pyd,sha256=NMLCloFzmYQc4OkOJtHVBjlBOJ2p5gX6fZo_-T6iP0M,240640
+libbbf_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libbbf_tools/bbf2cbx.py,sha256=HbPmcVOUSTgVnkPpXEJCTRYesIhcYnn0rA91oGC9XKI,4314
+libbbf_tools/cbx2bbf.py,sha256=n9qsPojUqnm_2yFyBWB4q5_4J71_lZjVdz9L8LIYLTQ,8107
+libbbf-0.2.4.dist-info/METADATA,sha256=WBPIrNkDde5UEM3JEJ8uWA-0TYRIrH8Fcfa5Re8NDR4,6123
+libbbf-0.2.4.dist-info/WHEEL,sha256=3-JGBxlfJ7cpG1EEEM2PrRJYpl2Lix3zyWKiPlGiWWY,97
+libbbf-0.2.4.dist-info/entry_points.txt,sha256=7qX-_x7iM2ygeZmkpL_bLEuJY1TlifTetaprHlK39hA,90
+libbbf-0.2.4.dist-info/top_level.txt,sha256=DM4mwVaAZp8aBb8KOwCvyYCev1_RMhsj3lXjBWDnbJc,20
+libbbf-0.2.4.dist-info/RECORD,,

libbbf-0.2.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.1.0)
+Root-Is-Purelib: false
+Tag: cp312-cp312-win32
+

libbbf-0.2.4.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bbf2cbx = libbbf_tools.bbf2cbx:main
+cbx2bbf = libbbf_tools.cbx2bbf:main

libbbf-0.2.4.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+libbbf
+libbbf_tools

libbbf_tools/bbf2cbx.py

@@ -0,0 +1,130 @@
+import argparse
+import zipfile
+import libbbf
+import sys
+import os
+
+def find_section_end(sections, page_count, current_idx, range_key):
+    start_page = sections[current_idx]['startPage']
+    
+    # Iterate through subsequent sections
+    for j in range(current_idx + 1, len(sections)):
+        next_sec = sections[j]
+        title = next_sec['title']
+        
+        if not range_key:
+            if next_sec['startPage'] > start_page:
+                return next_sec['startPage']
+        else:
+            if range_key in title:
+                return next_sec['startPage']
+                
+    return page_count
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract BBF to CBZ/Folder")
+    parser.add_argument("input_bbf", help="Input .bbf file")
+    parser.add_argument("--output", "-o", help="Output .cbz file (or directory if --dir)")
+    parser.add_argument("--extract", action="store_true", help="Enable extraction mode (legacy flag support)")
+    parser.add_argument("--dir", action="store_true", help="Extract to directory instead of CBZ")
+    parser.add_argument("--section", help="Extract only specific section by name")
+    parser.add_argument("--rangekey", help="String to match for end of range (e.g. 'Vol 2')")
+    parser.add_argument("--verify", action="store_true", help="Verify integrity before extraction")
+    parser.add_argument("--info", action="store_true", help="Show info and exit")
+    
+    args = parser.parse_args()
+    
+    reader = libbbf.BBFReader(args.input_bbf)
+    if not reader.is_valid:
+        print("Error: Invalid or corrupt BBF file.")
+        sys.exit(1)
+
+    # Info Mode
+    if args.info:
+        print(f"BBF Version: 1")
+        print(f"Pages:  {reader.get_page_count()}")
+        print(f"Assets: {reader.get_asset_count()}")
+        print("\n[Sections]")
+        secs = reader.get_sections()
+        if not secs: print(" None.")
+        for s in secs:
+            print(f" - {s['title']:<20} (Start: {s['startPage']+1})")
+        print("\n[Metadata]")
+        for k, v in reader.get_metadata():
+            print(f" - {k}: {v}")
+        return
+
+    # Verify Mode
+    if args.verify:
+        print("Verifying assets (XXH3)...")
+        if reader.verify():
+            print("Integrity OK.")
+        else:
+            print("Integrity Check FAILED.")
+            sys.exit(1)
+            
+    # Extraction Mode
+    if not args.output:
+        print("Error: Output filename required (-o)")
+        sys.exit(1)
+
+    sections = reader.get_sections()
+    total_pages = reader.get_page_count()
+    
+    start_idx = 0
+    end_idx = total_pages
+    
+    # Calculate Range
+    if args.section:
+        found_sec_idx = -1
+        for i, s in enumerate(sections):
+            if s['title'] == args.section:
+                found_sec_idx = i
+                break
+        
+        if found_sec_idx == -1:
+            print(f"Error: Section '{args.section}' not found.")
+            sys.exit(1)
+            
+        start_idx = sections[found_sec_idx]['startPage']
+        end_idx = find_section_end(sections, total_pages, found_sec_idx, args.rangekey)
+        
+        print(f"Extracting Section: '{args.section}' (Pages {start_idx+1}-{end_idx})")
+
+    # Perform Extraction
+    is_zip = not args.dir
+    
+    if is_zip:
+        zf = zipfile.ZipFile(args.output, 'w', zipfile.ZIP_DEFLATED)
+    else:
+        if not os.path.exists(args.output):
+            os.makedirs(args.output)
+
+    pad_len = len(str(total_pages))
+    
+    count = 0
+    for i in range(start_idx, end_idx):
+        info = reader.get_page_info(i)
+        data = reader.get_page_data(i)
+        
+        ext = ".png"
+        if info['type'] == 1: ext = ".avif"
+        elif info['type'] == 3: ext = ".jpg"
+        
+        fname = f"p{str(i+1).zfill(pad_len)}{ext}"
+        
+        if is_zip:
+            zf.writestr(fname, data)
+        else:
+            with open(os.path.join(args.output, fname), 'wb') as f:
+                f.write(data)
+        
+        count += 1
+        if count % 10 == 0:
+            print(f"\rExtracted {count} pages...", end="")
+
+    if is_zip: zf.close()
+    print(f"\nDone. Extracted {count} pages.")
+
+if __name__ == "__main__":
+    main()

libbbf_tools/cbx2bbf.py

@@ -0,0 +1,209 @@
+import argparse
+import os
+import zipfile
+import shutil
+import tempfile
+import libbbf
+import re
+import sys
+
+
+class PagePlan:
+    def __init__(self, path, filename, order=0):
+        self.path = path
+        self.filename = filename
+        self.order = order # 0=unspecified, >0=start, <0=end
+
+def compare_pages(a):
+    if a.order > 0:
+        return (0, a.order) 
+    elif a.order == 0:
+        return (1, a.filename) 
+    else:
+        return (2, a.order)
+
+def trim_quotes(s):
+    if not s: return ""
+    if len(s) >= 2 and s.startswith('"') and s.endswith('"'):
+        return s[1:-1]
+    return s
+
+def main():
+    parser = argparse.ArgumentParser(description="Mux CBZ/images to BBF (bbfenc compatible)")
+    parser.add_argument("inputs", nargs="+", help="Input files (.cbz, images) or directories")
+    parser.add_argument("--output", "-o", help="Output .bbf file", default="out.bbf")
+    
+    # Matching bbfenc options
+    parser.add_argument("--order", help="Text file defining page order (filename:index)")
+    parser.add_argument("--sections", help="Text file defining sections")
+    parser.add_argument("--section", action="append", help="Add section 'Name:Target[:Parent]'")
+    parser.add_argument("--meta", action="append", help="Add metadata 'Key:Value'")
+    
+    args = parser.parse_args()
+
+    # 1. Parse Order File
+    order_map = {}
+    if args.order and os.path.exists(args.order):
+        with open(args.order, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                if not line: continue
+                if ':' in line:
+                    fname, val = line.rsplit(':', 1)
+                    order_map[trim_quotes(fname)] = int(val)
+                else:
+                    order_map[trim_quotes(line)] = 0
+
+    manifest = []
+    
+    # We need to extract CBZs to temp to get individual file paths for the Builder
+    # bbfenc processes directories and images. Since Python zipfile needs extraction 
+    # to pass a path to the C++ fstream, we extract everything to a temp dir.
+    temp_dir = tempfile.mkdtemp(prefix="bbfmux_")
+    
+    try:
+        print("Gathering inputs...")
+        for inp in args.inputs:
+            inp = trim_quotes(inp)
+            
+            if os.path.isdir(inp):
+                # Directory input
+                for root, dirs, files in os.walk(inp):
+                    for f in files:
+                        if f.lower().endswith(('.png', '.avif', '.jpg', '.jpeg')):
+                            full_path = os.path.join(root, f)
+                            p = PagePlan(full_path, f)
+                            if f in order_map: p.order = order_map[f]
+                            manifest.append(p)
+                            
+            elif zipfile.is_zipfile(inp):
+                # CBZ input
+                print(f"Extracting {os.path.basename(inp)}...")
+                with zipfile.ZipFile(inp, 'r') as zf:
+                    # Extract all valid images
+                    for name in zf.namelist():
+                        if name.lower().endswith(('.png', '.avif', '.jpg', '.jpeg')):
+                            
+                            extracted_path = zf.extract(name, temp_dir)
+                            fname = os.path.basename(name)
+                            
+                            p = PagePlan(extracted_path, fname)
+                            
+                            if fname in order_map: p.order = order_map[fname]
+                            
+                            # Also check if the ZIP name itself has an order (less likely for pages)
+                            zip_name = os.path.basename(inp)
+                            if zip_name in order_map and len(manifest) == 0: 
+                                # TODO: I'll figure this out LATER!
+                                pass 
+                                
+                            manifest.append(p)
+            else:
+                #Single image file
+                fname = os.path.basename(inp)
+                p = PagePlan(inp, fname)
+                if fname in order_map: p.order = order_map[fname]
+                manifest.append(p)
+
+        #Sort Manifest
+        print(f"Sorting {len(manifest)} pages...")
+        manifest.sort(key=compare_pages)
+
+        file_to_page = {}
+        #allow --section="Vol 1":"chapter1.cbx" to work
+        input_file_start_map = {} # TODO: DO THIS LATER!
+        
+        for idx, p in enumerate(manifest):
+            file_to_page[p.filename] = idx
+            # For now, we rely on exact filename matching as per bbfenc.
+
+        # Structure: Name:Target[:Parent]
+        sec_reqs = []
+        
+        # From file
+        if args.sections and os.path.exists(args.sections):
+            with open(args.sections, 'r', encoding='utf-8') as f:
+                for line in f:
+                    if not line.strip(): continue
+                    parts = [trim_quotes(x) for x in line.strip().split(':')]
+                    if len(parts) >= 2:
+                        sec_reqs.append({
+                            'name': parts[0],
+                            'target': parts[1],
+                            'parent': parts[2] if len(parts) > 2 else None
+                        })
+
+        # From args
+        if args.section:
+            for s in args.section:
+                # Naive split on colon, might break if titles have colons, 
+                # but bbfenc does simplistic parsing too.
+                parts = [trim_quotes(x) for x in s.split(':')]
+                if len(parts) >= 2:
+                    sec_reqs.append({
+                        'name': parts[0],
+                        'target': parts[1],
+                        'parent': parts[2] if len(parts) > 2 else None
+                    })
+
+        #Initialize Builder
+        builder = libbbf.BBFBuilder(args.output)
+        
+        # Write Pages
+        print("Writing pages to BBF...")
+        for p in manifest:
+            ext = os.path.splitext(p.filename)[1].lower()
+            ftype = 2 # PNG default
+            if ext == '.avif': ftype = 1
+            elif ext in ['.jpg', '.jpeg']: ftype = 3
+            
+            if not builder.add_page(p.path, ftype):
+                print(f"Failed to add page: {p.path}")
+                sys.exit(1)
+
+        # Write Sections
+        section_name_to_idx = {}
+        # We need to process sections in order to resolve parents correctly if they refer to
+        # sections defined earlier in the list.
+        
+        for i, req in enumerate(sec_reqs):
+            target = req['target']
+            name = req['name']
+            parent_name = req['parent']
+            
+            page_index = 0
+            
+            # Is target a number?
+            if target.lstrip('-').isdigit():
+                val = int(target)
+                page_index = max(0, val - 1) # 1-based to 0-based
+            else:
+                # It's a filename
+                if target in file_to_page:
+                    page_index = file_to_page[target]
+                else:
+                    print(f"Warning: Section target '{target}' not found in manifest. Defaulting to Pg 1.")
+            
+            parent_idx = 0xFFFFFFFF
+            if parent_name and parent_name in section_name_to_idx:
+                parent_idx = section_name_to_idx[parent_name]
+                
+            builder.add_section(name, page_index, parent_idx)
+            section_name_to_idx[name] = i # bbfenc uses index in the vector
+
+        # Write Metadata
+        if args.meta:
+            for m in args.meta:
+                if ':' in m:
+                    k, v = m.split(':', 1)
+                    builder.add_metadata(trim_quotes(k), trim_quotes(v))
+
+        print("Finalizing...")
+        builder.finalize()
+        print(f"Created {args.output}")
+
+    finally:
+        shutil.rmtree(temp_dir)
+
+if __name__ == "__main__":
+    main()