ebk 0.1.0__py3-none-any.whl

ebk/config.py

@@ -0,0 +1,35 @@
+import configparser
+import os
+
+def load_ebkrc_config():
+    """
+    Loads configuration from ~/.btkrc.
+
+    If using LLM interface, expects a section [llm] with at least 'endpoint' and 'api_key'.
+    If using cloud interface (for generating complex networks), the section [cloud] may be used to specify various parameters.
+    """
+    config_path = os.path.expanduser("~/.ebkrc")
+    parser = configparser.ConfigParser()
+
+    if not os.path.exists(config_path):
+        raise FileNotFoundError(f"Could not find config file at {config_path}")
+
+    parser.read(config_path)
+
+    if "llm" not in parser:
+        raise ValueError(
+            "Config file ~/.btkrc is missing the [llm] section. "
+            "Please add it with 'endpoint' and 'api_key' keys."
+        )
+
+    endpoint = parser["llm"].get("endpoint", "")
+    api_key = parser["llm"].get("api_key", "")
+    model = parser["llm"].get("model", "gpt-3.5-turbo")
+
+    if not endpoint or not api_key or not model:
+        raise ValueError(
+            "Please make sure your [llm] section in ~/.btkrc "
+            "includes 'endpoint', 'api_key', and 'model' keys."
+        )
+    
+    return endpoint, api_key, model

ebk/exports/hugo.py

@@ -0,0 +1,55 @@
+import os
+import json
+from pathlib import Path
+from typing import List
+import logging
+
+logger = logging.getLogger(__name__)
+
+def export_hugo(lib_dir, hugo_dir):
+    """
+    Export ebk library to Hugo-compatible Markdown files.
+
+    Args:
+        lib_dir (str): Path to the ebk library directory to export (contains `metadata.json` and ebook-related files)
+        hugo_dir (str): Path to the Hugo site directory
+    """
+
+    lib_dir = Path(lib_dir)
+    with open(lib_dir / "metadata.json", "r") as f:
+        books = json.load(f)
+
+    hugo_dir = Path(hugo_dir)
+
+    content_dir = hugo_dir / "content" / "library"
+    static_dir = hugo_dir / "static" / "ebooks"
+    content_dir.mkdir(parents=True, exist_ok=True)
+    static_dir.mkdir(parents=True, exist_ok=True)
+
+    for book in books:
+        slug = book['title'].replace(" ", "-").lower()
+        md_file = content_dir / f"{slug}.md"
+
+        with open(md_file, "w") as md:
+            md.write("---\n")
+            md.write(f"title: {book['title']}\n")
+            md.write(f"creators: [{', '.join(book['creators'])}]\n")
+            md.write(f"subjects: [{', '.join(book['subjects'])}]\n")
+            md.write(f"description: {book['description']}\n")
+            md.write(f"date: {book['date']}\n")
+            md.write(f"tags: [{', '.join(book['Tags'].split(', '))}]\n")
+            md.write(f"ebook_file: /ebooks/{Path(book['file_path']).name}\n")
+            md.write(f"cover_image: /ebooks/{Path(book['Cover Path']).name if book['Cover Path'] else ''}\n")
+            md.write("---\n\n")
+            md.write(f"# {book['Title']}\n\n")
+            md.write(f"Author: {book['Author']}\n\n")
+            md.write(f"[Download eBook](/ebooks/{Path(book['File Path']).name})\n")
+
+        # Copy eBook and cover to static directory
+        if book["File Path"]:
+            os.system(f"cp '{book['File Path']}' '{static_dir}'")
+        if book["Cover Path"]:
+            os.system(f"cp '{book['Cover Path']}' '{static_dir}'")
+
+    logger.debug(f"Exported {len(books)} books to Hugo site at '{hugo_dir}'")
+

ebk/exports/zip.py

@@ -0,0 +1,25 @@
+import os
+import zipfile
+from pathlib import Path
+import logging
+
+logger = logging.getLogger(__name__)
+
+def export_zipfile(lib_dir, zip_file):
+    """
+    Export ebk library to a ZIP archive.
+
+    Args:
+        lib_dir (str): Path to the ebk library directory to export (contains `metadata.json` and ebook-related files)
+        zip_file (str): Path to the output ZIP file
+    """
+    lib_dir = Path(lib_dir)
+
+    # just want to take the entire directory and zip it
+
+    with zipfile.ZipFile(zip_file, "w") as z:
+        for root, _, files in os.walk(lib_dir):
+            for file in files:
+                file_path = Path(root) / file
+                logging.debug(f"Adding file to zip: {file_path}")
+                z.write(file_path, arcname=file_path.relative_to(lib_dir))

ebk/extract_metadata.py

@@ -0,0 +1,273 @@
+import os
+import xmltodict
+from typing import Dict, Optional
+from slugify import slugify
+import PyPDF2
+from ebooklib import epub
+
+def extract_metadata_from_opf(opf_file: str) -> Dict:
+    """
+    Parse a Calibre OPF file into a simplified dictionary structure (Dublin Core).
+    Returns a dict with keys:
+      - title
+      - creators
+      - subjects
+      - description
+      - language
+      - date
+      - identifiers
+      - publisher
+    """
+    try:
+        with open(opf_file, "r", encoding="utf-8") as f:
+            opf_dict = xmltodict.parse(f.read(), process_namespaces=False)
+    except Exception as e:
+        print(f"[extract_metadata_from_opf] Error reading '{opf_file}': {e}")
+        return {}
+
+    package = opf_dict.get("package", {})
+    metadata = package.get("metadata", {})
+
+    # Prepare simplified structure
+    simplified = {
+        "title": metadata.get("dc:title", metadata.get("title")),
+        "creators": None,
+        "subjects": None,
+        "description": metadata.get("dc:description", metadata.get("description")),
+        "language": metadata.get("dc:language", metadata.get("language")),
+        "date": metadata.get("dc:date", metadata.get("date")),
+        "publisher": metadata.get("dc:publisher", metadata.get("publisher")),
+        "identifiers": None
+    }
+
+    # -- Creators
+    creators = metadata.get("dc:creator", metadata.get("creator"))
+    if isinstance(creators, list):
+        simplified["creators"] = [
+            c.get("#text", "").strip() if isinstance(c, dict) else c
+            for c in creators
+        ]
+    elif isinstance(creators, dict):
+        simplified["creators"] = [creators.get("#text", "").strip()]
+    elif isinstance(creators, str):
+        simplified["creators"] = [creators.strip()]
+
+    # -- Subjects
+    subjects = metadata.get("dc:subject", metadata.get("subject"))
+    if isinstance(subjects, list):
+        simplified["subjects"] = [s.strip() for s in subjects]
+    elif isinstance(subjects, str):
+        simplified["subjects"] = [subjects.strip()]
+
+    # -- Identifiers
+    identifiers = metadata.get("dc:identifier", metadata.get("identifier"))
+    if isinstance(identifiers, list):
+        simplified["identifiers"] = {}
+        for identifier in identifiers:
+            if isinstance(identifier, dict):
+                scheme = identifier.get("@opf:scheme", "unknown")
+                text = identifier.get("#text", "").strip()
+                simplified["identifiers"][scheme] = text
+            else:
+                simplified["identifiers"]["unknown"] = identifier
+    elif isinstance(identifiers, dict):
+        scheme = identifiers.get("@opf:scheme", "unknown")
+        text = identifiers.get("#text", "").strip()
+        simplified["identifiers"][scheme] = text
+
+    return simplified
+
+
+def extract_metadata_from_pdf(pdf_path: str) -> Dict:
+    """
+    Extract metadata from a PDF file using PyPDF2.
+    Returns a dictionary with the same keys as the OPF-based dict.
+    """
+
+    metadata = {
+        "title": None,
+        "creators": None,
+        "subjects": None,
+        "description": None,
+        "language": None,
+        "date": None,
+        "publisher": None,
+        "identifiers": None,
+        "keywords": None,
+    }
+
+    try:
+        with open(pdf_path, "rb") as f:
+            reader = PyPDF2.PdfReader(f)
+            info = reader.metadata or {}
+
+        # NOTE: Depending on PyPDF2 version, metadata keys can differ
+        # e.g. info.title vs info.get('/Title')
+        pdf_title = info.get("/Title", None) or info.get("title", None)
+        pdf_author = info.get("/Author", None) or info.get("author", None)
+        pdf_subject = info.get("/Subject", None) or info.get("subject", None)
+        pdf_keywords = info.get("/Keywords", None) or info.get("keywords", None)
+        pdf_publisher = info.get("/Producer", None) or info.get("producer", None) or info.get("/Publisher", None) or info.get("publisher", None)
+        pdf_creation_date = info.get("/CreationDate", None)
+
+        if pdf_title:
+            metadata["title"] = pdf_title.strip()
+        if pdf_author:
+            metadata["creators"] = [pdf_author.strip()]
+        if pdf_subject:
+            metadata["subjects"] = [sub.strip() for sub in pdf_subject.split(",")]
+            metadata["description"] = pdf_subject.strip()
+
+        if pdf_creation_date and len(pdf_creation_date) >= 10:
+            # Format: 'D:YYYYMMDDhhmmss'
+            # We'll extract 'YYYY-MM-DD'
+            date_str = pdf_creation_date[2:10]  # e.g., 20210101
+            metadata["date"] = f"{date_str[:4]}-{date_str[4:6]}-{date_str[6:]}"
+        # Language not typically stored in PDF metadata
+        metadata["language"] = "unknown-language"
+
+        # For an "identifier," we don't really have a built-in PDF field, so it's optional
+        metadata["identifiers"] = {"pdf:identifier": pdf_path}
+
+        if pdf_keywords:
+            metadata["keywords"] = [kw.strip() for kw in pdf_keywords.split(",")]
+
+        if pdf_publisher:
+            metadata["publisher"] = pdf_publisher.strip()
+
+        metadata["file_paths"] = [pdf_path]
+
+
+    except Exception as e:
+        print(f"[extract_metadata_from_pdf] Error reading '{pdf_path}': {e}")
+
+    return metadata
+
+
+def extract_metadata_from_epub(epub_path: str) -> Dict:
+    """
+    Extract metadata from an EPUB file using ebooklib.
+    Returns a dictionary with the same keys as the OPF-based dict.
+    """
+    metadata = {
+        "title": None,
+        "creators": [],
+        "subjects": [],
+        "description": None,
+        "language": None,
+        "date": None,
+        "identifiers": {},
+    }
+
+    try:
+        book = epub.read_epub(epub_path)
+
+        # Title
+        dc_title = book.get_metadata("DC", "title")
+        if dc_title:
+            metadata["title"] = dc_title[0][0]
+
+        # Creators
+        dc_creators = book.get_metadata("DC", "creator")
+        if dc_creators:
+            metadata["creators"] = [c[0] for c in dc_creators]
+
+        # Subjects
+        dc_subjects = book.get_metadata("DC", "subject")
+        if dc_subjects:
+            metadata["subjects"] = [s[0] for s in dc_subjects]
+
+        # Description
+        dc_description = book.get_metadata("DC", "description")
+        if dc_description:
+            metadata["description"] = dc_description[0][0]
+
+        # Language
+        dc_language = book.get_metadata("DC", "language")
+        if dc_language:
+            metadata["language"] = dc_language[0][0]
+
+        # Date
+        dc_date = book.get_metadata("DC", "date")
+        if dc_date:
+            metadata["date"] = dc_date[0][0]
+
+        # Identifiers
+        identifiers = book.get_metadata("DC", "identifier")
+        if identifiers:
+            for identifier in identifiers:
+                # identifier is a tuple: (value, { 'scheme': '...' })
+                ident_value, ident_attrs = identifier
+                scheme = ident_attrs.get("scheme", "unknown")
+                metadata["identifiers"][scheme] = ident_value
+    except Exception as e:
+        print(f"[extract_metadata_from_epub] Error reading '{epub_path}': {e}")
+
+    return metadata
+
+
+def extract_metadata_from_path(file_path: str) -> Dict:
+    """
+    Fallback metadata extraction by interpreting the path as <...>/<author>/<title>.
+    Slugify them to remove invalid characters.
+    """
+    metadata = {
+        "title": None,
+        "creators": [],
+        "subjects": [],
+        "description": "",
+        "language": "unknown-language",
+        "date": "unknown-date",
+        "identifiers": {}
+    }
+
+    try:
+        path_parts = file_path.split(os.sep)
+        # path_parts: ['base_dir', 'author_dir', 'title', 'title - author.ext'] ]
+        title = path_parts[-2]
+        creators = path_parts[1].split(",")
+        metadata["title"] = title
+        metadata["creators"] = creators
+    except Exception as e:
+        print(f"[extract_metadata_from_path] Error with '{file_path}': {e}")
+
+    return metadata
+
+def extract_metadata(ebook_file: str, opf_file: Optional[str] = None) -> Dict:
+    """
+    High-level function to extract metadata from either:
+      - OPF file (if provided)
+      - The ebook_file (PDF, EPUB, or fallback from path)
+    Then merges them, giving priority to OPF data.
+    
+    Returns a final merged dictionary with keys:
+      - title
+      - creators
+      - subjects
+      - description
+      - language
+      - date
+      - identifiers
+      - cover_path
+      - file_paths
+      - virtual_libs
+      - unique_id
+    """
+
+    # 1. Extract from OPF if we have it
+    opf_metadata = {}
+    if opf_file and os.path.isfile(opf_file):
+        opf_metadata = extract_metadata_from_opf(opf_file)
+
+    _, ext = os.path.splitext(ebook_file.lower())
+    if ext == ".pdf":
+        ebook_metadata = extract_metadata_from_pdf(ebook_file)
+    elif ext == ".epub":
+        ebook_metadata = extract_metadata_from_epub(ebook_file)
+
+    path_metadata = extract_metadata_from_path(ebook_file)
+
+    metadata = {key: opf_metadata.get(key) or ebook_metadata.get(key) or value for key, value in ebook_metadata.items()}
+    metadata = {key: metadata.get(key) or value for key, value in path_metadata.items()}
+    return metadata
+

ebk/ident.py

@@ -0,0 +1,96 @@
+import hashlib
+import re
+from typing import List, Dict
+import uuid
+
+def canonicalize_text(text: str) -> str:
+    """
+    Canonicalize text by converting to lowercase, removing punctuation,
+    stripping whitespace, and replacing spaces with underscores.
+    """
+    text = text.lower()
+    # Remove punctuation using regex
+    text = re.sub(r'[^\w\s]', '', text)
+    # Replace multiple spaces with a single space
+    text = re.sub(r'\s+', ' ', text)
+    # Strip leading and trailing whitespace
+    text = text.strip()
+    # Replace spaces with underscores
+    text = text.replace(' ', '_')
+    return text
+
+def canonicalize_creators(creators: List[str]) -> str:
+    """
+    Canonicalize a list of creators (authors) by sorting them,
+    canonicalizing each name, and joining with underscores.
+    """
+    # Sort creators alphabetically for consistency
+    sorted_creators = sorted(creators)
+    canonical_creators = [canonicalize_text(creator) for creator in sorted_creators]
+    # Join multiple creators with underscores
+    return '_'.join(canonical_creators)
+
+def generate_composite_string(entry: Dict) -> str:
+    """
+    Generate a composite string by concatenating canonicalized values
+    of ISBN, date, language, publisher, creators, and title.
+    
+    The order is important for consistency.
+    """
+    identifiers = entry.get('identifiers', {})
+    #isbn = identifiers.get('ISBN', '').strip()
+    #date = entry.get('date', '').strip()
+    language = entry.get('language', '').strip()
+    #publisher = entry.get('publisher', '').strip()
+    creators = entry.get('creators', [])
+    title = entry.get('title', '').strip()
+    
+    # Canonicalize each field
+    #isbn_c = canonicalize_text(isbn) if isbn else 'no_isbn'
+    #date_c = canonicalize_text(date) if date else 'no_date'
+    language_c = canonicalize_text(language) if language else 'no_language'
+    #publisher_c = canonicalize_text(publisher) if publisher else 'no_publisher'
+    creators_c = canonicalize_creators(creators) if creators else 'no_creators'
+    title_c = canonicalize_text(title) if title else 'no_title'
+
+    if language_c == 'no_language' and creators_c == 'no_creators' and title_c == 'no_title':
+        return None
+    
+    # Concatenate fields with double underscores as delimiters
+    composite_string = f"{language_c}__{creators_c}__{title_c}"
+    return composite_string
+
+def generate_hash_id(entry: Dict) -> str:
+    """
+    Generate a unique hash ID for an eBook entry by hashing the composite string.
+    
+    Args:
+        entry (Dict): The eBook entry metadata.
+    
+    Returns:
+        str: The SHA-256 hash hexadecimal string.
+    """
+    composite_string = generate_composite_string(entry)
+    if composite_string:
+        composite_bytes = composite_string.encode('utf-8')
+    else:
+        composite_bytes = str(uuid.uuid4()).encode('utf-8')
+
+    # Create SHA-256 hash
+    hash_obj = hashlib.sha256(composite_bytes)
+    hash_hex = hash_obj.hexdigest()
+    return hash_hex
+
+def add_unique_id(entry: Dict) -> Dict:
+    """
+    Add a unique hash ID to the eBook entry.
+    
+    Args:
+        entry (Dict): The original eBook entry metadata.
+    
+    Returns:
+        Dict: The eBook entry with an added 'unique_id' field.
+    """
+    unique_id = generate_hash_id(entry)
+    entry['unique_id'] = unique_id
+    return entry

ebk/imports/calibre.py

@@ -0,0 +1,144 @@
+import os
+import shutil
+import json
+from slugify import slugify
+from typing import Dict
+import logging
+from ..extract_metadata import extract_metadata
+from ..ident import add_unique_id
+from ..utils import get_unique_filename
+
+logger = logging.getLogger(__name__)
+
+ebook_exts = (".pdf", ".epub", ".mobi", ".azw3", ".txt", ".docx", ".odt",
+              ".html", ".rtf", ".md", ".fb2", ".cbz", ".cbr", ".djvu",
+              ".xps", ".ibooks", ".azw", ".lit", ".pdb", ".prc", ".lrf",
+              ".pdb", ".pml", ".rb", ".snb", ".tcr", ".txtz", ".azw1")                
+
+def import_calibre(calibre_dir: str,
+                   output_dir: str,
+                   ebook_exts: tuple = ebook_exts):
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    metadata_list = []
+
+    for root, _, files in os.walk(calibre_dir):
+        # Look for OPF
+        opf_file_path = os.path.join(root, "metadata.opf")
+
+        # Gather valid ebook files
+        ebook_files = [f for f in files if f.lower().endswith(ebook_exts)]
+        
+        if not ebook_files:
+            logger.debug(f"No recognized ebook files found in {root}. Skipping.")
+            continue  # skip if no recognized ebook files
+
+        # Pick the "primary" ebook file. This is arbitrary and can be changed.
+        primary_ebook_file = ebook_files[0]
+        ebook_full_path = os.path.join(root, primary_ebook_file)
+
+        # Extract metadata
+        if os.path.exists(opf_file_path):
+            logger.debug(f"Found metadata.opf in {root}. Extracting metadata from OPF.")
+            metadata = extract_metadata(ebook_full_path, opf_file_path)
+        else:
+            logger.warning(f"No metadata.opf found in {root}. Inferring metadata from ebook files.")
+            metadata = extract_metadata(ebook_full_path)  # Only ebook file path is provided
+
+        # Extract metadata (OPF + ebook)
+        metadata = extract_metadata(ebook_full_path, opf_file_path)
+        metadata["root"] = root
+        metadata["source_folder"] = calibre_dir
+        metadata["output_folder"] = output_dir
+        metadata["imported_from"] = "calibre"
+        metadata["virtual_libs"] = [slugify(output_dir)]
+
+        # Generate base name
+        title_slug = slugify(metadata.get("title", "unknown_title"))
+        creator_slug = slugify(
+            metadata["creators"][0]) if metadata.get("creators") else "unknown_creator"
+
+        base_name = f"{title_slug}__{creator_slug}"
+
+        # Copy ebooks
+        file_paths = []
+        for ebook_file in ebook_files:
+            _, ext = os.path.splitext(ebook_file)
+            src = os.path.join(root, ebook_file)
+            dst = os.path.join(output_dir, f"{base_name}{ext}")
+            dst = get_unique_filename(dst)
+            shutil.copy(src, dst)
+            file_paths.append(os.path.relpath(dst, output_dir))
+
+        # Optionally handle cover.jpg
+        if "cover.jpg" in files:
+            cover_src = os.path.join(root, "cover.jpg")
+            cover_dst = os.path.join(output_dir, f"{base_name}_cover.jpg")
+            shutil.copy(cover_src, cover_dst)
+            metadata["cover_path"] = os.path.relpath(cover_dst, output_dir)
+
+        # Store relative paths in metadata
+        metadata["file_paths"] = file_paths
+        metadata_list.append(metadata)
+
+    for entry in metadata_list:
+        add_unique_id(entry)
+
+    # Write out metadata.json
+    output_json = os.path.join(output_dir, "metadata.json")
+    with open(output_json, "w", encoding="utf-8") as f:
+        json.dump(metadata_list, f, indent=2, ensure_ascii=False)
+
+
+def ensure_metadata_completeness(metadata: Dict) -> Dict:
+    """
+    Ensure that all required metadata fields are present.
+    If a field is missing or empty, attempt to infer or set default values.
+    
+    Args:
+        metadata (Dict): The metadata dictionary extracted from OPF or inferred.
+    
+    Returns:
+        Dict: The updated metadata dictionary with all necessary fields.
+    """
+    required_fields = ["title", "creators",
+                       "subjects", "description",
+                       "language", "date", "identifiers",
+                       "file_paths", "cover_path", "unique_id",
+                       "source_folder", "output_folder",
+                       "imported_from", "virtual_libs"]
+    for field in required_fields:
+        if field not in metadata:
+            if field == "creators":
+                metadata[field] = ["Unknown Author"]
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "subjects":
+                metadata[field] = []
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "description":
+                metadata[field] = "No description available."
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "language":
+                metadata[field] = "en"  # Default to English
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "date":
+                metadata[field] = None  # Unknown date
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "title":
+                metadata[field] = "Unknown Title"
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "identifiers":
+                metadata[field] = {}
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "file_paths":
+                metadata[field] = []
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "cover_path":
+                metadata[field] = None
+                logger.debug(f"Set default value for '{field}'.")
+            elif field == "unique_id":
+                metadata[field] = None
+                logger.debug(f"Set default value for '{field}'.")
+    
+    return metadata