enkan 2.0.2__py3-none-any.whl

enkan/__main__.py

@@ -0,0 +1,43 @@
+# -----------------------------------------------------------------------------
+# # A Python script to create a slideshow from a list of files, with various
+# modes and features including weighted, balanced, and random selection.
+#
+# Author:      John Sullivan
+# Created:     2023-2025
+# License:     MIT License
+# Copyright:   (c) 2023-2025 John Sullivan
+#
+# Description:
+#   This script builds a slideshow from directories or lists of images,
+#   supporting advanced weighting, folder balancing, and navigation features.
+#   It uses Tkinter for the GUI and Pillow for image handling.
+#
+# Usage:
+#   enkan --input_file <file_or_folder> [options]
+# 
+# Dependencies:
+#   - Python 3.8+
+#   - Pillow
+#   - tqdm
+#
+# -----------------------------------------------------------------------------
+
+import logging
+from enkan.utils.argparse_setup import get_arg_parser
+from enkan.utils.logging import configure_logging
+from enkan.cli import main_with_args
+
+def main() -> None:
+    """Console script / module entry point."""
+    args = get_arg_parser().parse_args()
+    configure_logging(debug=getattr(args, "debug", False), quiet=getattr(args, "quiet", False))
+    try:
+        main_with_args(args)
+    except Exception as e:
+        logging.getLogger("enkan").error("Fatal: %s", e)
+        # No traceback shown unless debug enabled
+        if getattr(args, "debug", False):
+            raise
+
+if __name__ == "__main__":
+    main()

enkan/cache/HistoryManager.py

@@ -0,0 +1,71 @@
+from collections import deque
+from enkan import constants
+
+class HistoryManager:
+    """
+    A single-line history manager with back/forward navigation.
+    Maintains a deque of visited paths with a current index pointer.
+    """
+
+    def __init__(self, max_length=constants.HISTORY_QUEUE_LENGTH):
+        self.history = deque(maxlen=max_length)
+        self.current_index = -1  # -1 = no current item
+        self.max_length = max_length
+
+    def add(self, path):
+        """
+        Add a new path. Clears forward history if the user
+        has navigated backward and is now moving forward naturally.
+        """
+        # Remove everything after the current index (future)
+        while len(self.history) - 1 > self.current_index:
+            self.history.pop()
+
+        # Add new path
+        self.history.append(path)
+        self.current_index = len(self.history) - 1
+        
+    def remove(self, path):
+        """
+        Remove a path from history, adjusting current_index if needed.
+        If the current item is removed, current_index is moved to the previous item.
+        """
+        try:
+            idx = self.history.index(path)
+        except ValueError:
+            return  # Path not in history
+
+        self.history.remove(path)
+
+        # Adjust current_index
+        if idx < self.current_index:
+            self.current_index -= 1
+        elif idx == self.current_index:
+            # Move to the previous item, or -1 if none exist
+            self.current_index = max(0, self.current_index - 1) if self.history else -1
+
+    def back(self):
+        if self.current_index > 0:
+            self.current_index -= 1
+            return self.history[self.current_index]
+        return None
+
+    def forward_step(self):
+        if self.current_index < len(self.history) - 1:
+            self.current_index += 1
+            return self.history[self.current_index]
+        return None
+
+    def current(self):
+        """Return the current item (or None if empty)."""
+        if self.current_index == -1:
+            return None
+        return self.history[self.current_index]
+
+    def clear(self):
+        self.history.clear()
+        self.current_index = -1
+
+    def __repr__(self):
+        line = list(self.history)
+        return f"HistoryManager(line={line}, current_index={self.current_index})"

enkan/cache/ImageCacheManager.py

@@ -0,0 +1,203 @@
+import threading
+import logging
+
+from PIL import Image
+
+from .LRUCache import LRUCache
+from .PreloadQueue import PreloadQueue
+from .HistoryManager import HistoryManager
+from enkan.plugables.ImageLoaders import ImageLoaders
+from enkan.utils.utils import is_videofile
+from enkan import constants
+
+logger: logging.Logger = logging.getLogger("enkan.cache")     
+
+class ImageCacheManager:
+    """
+    Combines LRUCache, PreloadQueue, and HistoryManager
+    to manage images and videos for the slideshow.
+    Supports background preloading of images.
+    """
+
+    def __init__(self, image_provider, current_image_index, background_preload=True):
+        self.lru_cache = LRUCache(constants.CACHE_SIZE)
+        self.preload_queue = PreloadQueue(constants.PRELOAD_QUEUE_LENGTH)
+        self.history_manager = HistoryManager(constants.HISTORY_QUEUE_LENGTH)
+        self.image_provider = image_provider
+        self.image_loader = ImageLoaders()
+        self.current_image_index = current_image_index
+        self.background_preload = background_preload
+
+        self._lock = threading.Lock()
+        self._refill_thread = None
+        self._provider_lock = threading.Lock()
+
+        # Initial preload (async if background=True)
+        if self.background_preload:
+            self._background_refill()
+        else:
+            self._preload_refill()
+
+    # -----------------------
+    # Preload
+    # -----------------------
+
+    def _provider_next(self) -> str:
+        """Thread-safe wrapper around the image provider."""
+        with self._provider_lock:
+            return next(self.image_provider)
+
+    def _preload_refill(self) -> None:
+        """Fill preload queue fully."""
+        while len(self.preload_queue) < self.preload_queue.max_size:
+            try:
+                image_path: str = self._provider_next()
+            except StopIteration:
+                break  # For linear/sequential provider; random providers never stop
+            if image_path is None:
+                break
+            if image_path in self.preload_queue:
+                continue
+            image_obj: Image.Image = self._load_image(image_path)
+            self.preload_queue.push(image_path, image_obj)
+            logger.debug(f"Preloaded: {image_path}")
+
+    def _background_refill(self):
+        """Start a background refill thread if not already running."""
+        with self._lock:
+            if self._refill_thread and self._refill_thread.is_alive():
+                logger.debug("Background refill aborted. Already refilling.")
+                return  # Already refilling
+            self._refill_thread = threading.Thread(
+                target=self._preload_refill, daemon=True
+            )
+            self._refill_thread.start()
+            logger.debug("Background refill started.")
+
+    # -----------------------
+    # Image Loading
+    # -----------------------
+
+    def _load_image(self, image_path: str) -> Image.Image | None:
+        if is_videofile(image_path):
+            return None
+        image_obj: Image.Image = self.lru_cache.get(image_path)
+        if image_obj is None:
+            logger.debug(f"Loading from Disk: {image_path}")
+            image_obj: Image.Image = self.image_loader.load_image(image_path)
+            self.lru_cache.put(image_path, image_obj)
+        else:
+            logger.debug(f"Loaded from LRUCache: {image_path}")
+        return image_obj
+
+    # -----------------------
+    # Public API
+    # -----------------------
+
+    def get_next(
+        self, 
+        image_path: str = None, 
+        record_history: bool = True
+    ) -> tuple[str | None, Image.Image | None]:
+        """
+        Retrieve the next (image_path, image_obj).
+        If image_path is None, pop from PreloadQueue.
+        Updates history if record_history=True.
+        """
+        image_obj: Image.Image = None
+        source: str = None
+
+        # Step 1: Pop from preload if no explicit path is given
+        if image_path is None:
+            popped = self.preload_queue.pop()
+            if popped:
+                image_path, image_obj = next(iter(popped.items()))
+                source = "PreloadQueue"
+            else:
+                try:
+                    image_path = self._provider_next()
+                except StopIteration:
+                    logger.debug("No image provided (empty provider).")
+                    return None, None
+                image_obj = self._load_image(image_path)
+                source = "Disk"
+        else:
+            image_obj = self.lru_cache.get(image_path)
+            if image_obj:
+                source = "LRUCache"
+            else:
+                image_obj = self._load_image(image_path)
+                source = "Disk"
+
+        # Step 2: Conditionally update history
+        if record_history:
+            self.history_manager.add(image_path)
+
+        # Step 3: Refill preload (in background if enabled)
+        if self.background_preload:
+            self._background_refill()
+        else:
+            self._preload_refill()
+
+        # Step 4: Debug output
+        logger.debug(f"Loaded: {image_path} (from {source})")
+
+        return image_path, image_obj
+
+    def back(self):
+        path = self.history_manager.back()
+        if path is None:
+            return None, None
+        return path, self._load_image(path)
+
+    def forward(self):
+        path = self.history_manager.forward_step()
+        if path is None:
+            return None, None
+        return path, self._load_image(path)
+
+    def current(self):
+        path = self.history_manager.current()
+        if path is None:
+            return None, None
+        return path, self._load_image(path)
+
+    def reset(self):
+        """Clear all caches and history."""
+        self.lru_cache.clear()
+        self.preload_queue.clear()
+        self.history_manager.clear()
+        logger.debug("Cache, preload queue, and history cleared.")
+
+        if self.background_preload:
+            self._background_refill()
+        else:
+            self._preload_refill()
+
+    def reset_provider(self) -> bool:
+        """Reset provider-specific state and clear pending preloads."""
+        reset_callable = getattr(self.image_provider, "reset_burst", None)
+        if not callable(reset_callable):
+            return False
+        with self._provider_lock:
+            reset_callable()
+        self.preload_queue.clear()
+        if self.background_preload:
+            self._background_refill()
+        else:
+            self._preload_refill()
+        logger.debug("Provider state reset; preload queue cleared.")
+        return True
+
+    def invalidate(self, image_path: str) -> None:
+        """Remove a specific path from caches and preload queue."""
+        self.lru_cache.pop(image_path)
+        self.preload_queue.discard(image_path)
+
+    def __repr__(self):
+        return (
+            f"ImageCacheManager("
+            f"cache={self.lru_cache}, "
+            f"preload={self.preload_queue}, "
+            f"history={self.history_manager})"
+        )

enkan/cache/LRUCache.py

@@ -0,0 +1,54 @@
+from collections import OrderedDict
+
+class LRUCache:
+    """
+    A simple LRU (Least Recently Used) cache implemented using OrderedDict.
+    Keys are promoted to the front on access or insertion.
+    """
+
+    def __init__(self, max_size: int):
+        self.cache = OrderedDict()
+        self.max_size = max_size
+
+    def put(self, key, value):
+        if key in self.cache:
+            # Update and promote
+            self.cache.move_to_end(key, last=False)
+            self.cache[key] = value
+        else:
+            self.cache[key] = value
+            self.cache.move_to_end(key, last=False)
+            if len(self.cache) > self.max_size:
+                self.cache.popitem(last=True)  # Remove oldest
+
+    def get(self, key):
+        if key not in self.cache:
+            return None
+        self.cache.move_to_end(key, last=False)
+        return self.cache[key]
+
+    def pop(self, key):
+        return self.cache.pop(key, None)
+    
+    def clear(self):
+        """Remove all items from the cache."""
+        self.cache.clear()
+
+    def __contains__(self, key):
+        return key in self.cache
+
+    def __getitem__(self, key):
+        return self.get(key)
+
+    def __setitem__(self, key, value):
+        self.put(key, value)
+
+    def items(self):
+        """Return items in most-recently-used order."""
+        return list(self.cache.items())
+
+    def __len__(self):
+        return len(self.cache)
+
+    def __repr__(self):
+        return f"LRUCache({list(self.cache.items())})"

enkan/cache/PreloadQueue.py

@@ -0,0 +1,73 @@
+from collections import deque
+
+class PreloadQueue:
+    """
+    A FIFO queue of preloaded images with a maximum size.
+    Each element is a {path: image_obj} dict.
+    """
+
+    def __init__(self, max_size: int):
+        self.queue = deque(maxlen=max_size)
+        self.lookup = set()  # For fast membership checks
+        self.max_size = max_size
+
+    def push(self, path, image_obj):
+        """
+        Push a new (path, image_obj) to the bottom of the queue.
+        If the queue is full, the oldest item is automatically dropped.
+        """
+        if path in self.lookup:
+            return False  # Avoid duplicates
+
+        # If queue is full, remove oldest
+        if len(self.queue) == self.max_size:
+            oldest = self.queue.popleft()
+            self.lookup.difference_update(oldest.keys())
+
+        self.queue.append({path: image_obj})
+        self.lookup.add(path)
+        return True
+
+    def pop(self):
+        """
+        Pop and return the top (oldest) item in the queue.
+        Returns None if the queue is empty.
+        """
+        if not self.queue:
+            return None
+        item = self.queue.popleft()
+        self.lookup.difference_update(item.keys())
+        return item
+    
+    def discard(self, path):
+        """
+        Remove a specific path from the queue if present.
+        Returns True if the path was removed, else False.
+        """
+        if path not in self.lookup:
+            return False
+        self.lookup.discard(path)
+        new_queue = deque(maxlen=self.max_size)
+        for item in self.queue:
+            if path not in item:
+                new_queue.append(item)
+        self.queue = new_queue
+        return True
+    
+    def clear(self):
+        """Remove all items from the queue."""
+        self.queue.clear()
+        self.lookup.clear()
+
+    def __contains__(self, path):
+        return path in self.lookup
+
+    def __len__(self):
+        return len(self.queue)
+
+    def items(self):
+        """Return a list of all queued items in order."""
+        return list(self.queue)
+
+    def __repr__(self):
+        return f"PreloadQueue({list(self.queue)})"

enkan/cli.py

@@ -0,0 +1,90 @@
+# ——— Standard library ———
+import os
+import logging
+from typing import List
+from itertools import accumulate
+
+# ——— Local ———
+from enkan.utils.InputProcessor import InputProcessor
+from enkan.utils.Defaults import Defaults
+from enkan.utils.Filters import Filters
+from enkan.tree.tree_logic import (
+    build_tree,
+    extract_image_paths_and_weights_from_tree
+)
+
+logger = logging.getLogger("enkan.main")  
+
+def main_with_args(args) -> None:
+    
+    defaults: Defaults = Defaults(args=args)
+    filters: Filters = Filters()
+    filters.preprocess_ignored_files()
+    tree: Tree = None
+
+    # Normalize input_files to list
+    if not args.input_file:
+        input_files: List[str] = []
+    elif isinstance(args.input_file, str):
+        input_files = [args.input_file]
+    else:
+        input_files = list(args.input_file)
+
+    processor = InputProcessor(defaults, filters, args.quiet or False)
+    tree, image_dirs, specific_images, all_images, weights = processor.process_inputs(input_files)
+    if getattr(args, "ignore_below_bottom", False):
+        filters.configure_ignore_below_bottom(True, defaults.mode)
+
+    if not any([tree, image_dirs, specific_images, all_images, weights]):
+        raise ValueError("No images found in the provided input files.")
+
+    if image_dirs or specific_images or tree:
+        # Instantiate and build the tree
+        if not tree:
+            tree = build_tree(defaults, filters, image_dirs, specific_images, quiet=False)
+
+        # Print tree if requested
+        if args.printtree:
+            from enkan.utils.tests import print_tree
+            print_tree(defaults, tree.root, max_depth=args.testdepth or 9999)
+            return
+
+        if args.outputtree:
+            from enkan.utils.utils import write_tree_to_file
+            base_names = [os.path.splitext(os.path.basename(f))[0] for f in args.input_file]
+            output_name = "_".join(base_names) + ".tree"
+            output_path = os.path.join(os.getcwd(), output_name)
+            write_tree_to_file(tree, output_path)
+            logger.info("Tree written to %s", output_path)
+            return
+
+        # Extract paths and weights from the tree
+        extracted_images, extracted_weights = (
+            extract_image_paths_and_weights_from_tree(tree, test_iterations=args.test)
+        ) 
+        all_images.extend(extracted_images)
+        weights.extend(extracted_weights)
+        
+    cum_weights = list(accumulate(weights))
+
+    if args.outputlist:
+        from enkan.utils.utils import write_image_list
+        # Build output filename
+        base_names = [os.path.splitext(os.path.basename(f))[0] for f in args.input_file]
+        output_name = "_".join(base_names) + ".lst"
+        output_path = os.path.join(os.getcwd(), output_name)
+        write_image_list(all_images, weights, args.input_file, args.mode, output_path)
+        logger.info("Output written to %s", output_path)
+        return
+
+    # Test or start the slideshow
+    if args.test:
+        from enkan.utils.tests import test_distribution
+        test_distribution(all_images, cum_weights, args.test, args.testdepth, args.histo, defaults, args.quiet or False)
+        return
+    
+    from enkan.mySlideshow.start_slideshow import start_slideshow
+    if not tree:
+        from enkan.tree.Tree import Tree
+        tree = Tree(defaults, filters)
+    start_slideshow(tree, all_images, cum_weights, defaults, filters, args.quiet or False, args.interval)

enkan/constants.py

@@ -0,0 +1,33 @@
+import re
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+PACKAGE_NAME = "enkan"
+
+try:
+    VERSION = _pkg_version(PACKAGE_NAME)
+except PackageNotFoundError:
+    # Fallback during source-only situations (keep in sync with pyproject if used)
+    VERSION = "2.0.2"
+TOTAL_WEIGHT = 100
+PARENT_STACK_MAX = 5
+HISTORY_QUEUE_LENGTH = 25
+CACHE_SIZE = 10
+PRELOAD_QUEUE_LENGTH = 3
+IMAGE_FILES = (".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".tiff")
+VIDEO_FILES = (".mp4", ".mkv", ".webm", ".avi", ".mov", ".wmv")
+TEXT_FILES = (".txt", ".lst")
+CX_PATTERN = re.compile(r"^(?:[bw]\d+(?:,-?\d+)?(?:,-?\d+)?)+$", re.IGNORECASE)
+
+MODIFIER_PATTERN = re.compile(r"(\[.*?\])")
+WEIGHT_MODIFIER_PATTERN = re.compile(r"^\d+%?$")
+PROPORTION_PATTERN = re.compile(r"^%\d+%?$")
+MODE_PATTERN = CX_PATTERN
+GRAFT_PATTERN = re.compile(r"^g\d+$", re.IGNORECASE)
+GROUP_PATTERN = re.compile(r"^>.*", re.IGNORECASE)
+FLAT_PATTERN = re.compile(r"^f$", re.IGNORECASE)
+VIDEO_PATTERN = re.compile(r"^v$", re.IGNORECASE)
+NO_VIDEO_PATTERN = re.compile(r"^nv$", re.IGNORECASE)
+MUTE_PATTERN = re.compile(r"^m$", re.IGNORECASE)
+NO_MUTE_PATTERN = re.compile(r"^nm$", re.IGNORECASE)
+DONT_RECURSE_PATTERN = re.compile(r"^/$", re.IGNORECASE)
+IGNORE_BELOW_BOTTOM_PATTERN = re.compile(r"^ibb$", re.IGNORECASE)

enkan/mySlideshow/ProviderChoooseDialog.py

@@ -0,0 +1,56 @@
+import tkinter as tk
+from tkinter import simpledialog, messagebox
+
+class ProviderChooserDialog(simpledialog.Dialog):
+    def __init__(self, parent, provider_names, title="Choose Image Provider"):
+        self.provider_names = provider_names
+        self.selected_provider = provider_names[0]
+        self.extra_kwargs = {}
+        super().__init__(parent, title)
+
+    def body(self, master):
+        tk.Label(master, text="Select image provider:").pack(padx=10, pady=10)
+        self.var = tk.StringVar(value=self.provider_names[0])
+        self.dropdown = tk.OptionMenu(master, self.var, *self.provider_names, command=self.on_provider_change)
+        self.dropdown.pack(padx=10, pady=(0, 10))
+        # Placeholder for extra arg widgets
+        self.extra_frame = tk.Frame(master)
+        self.extra_frame.pack()
+        self.weight_entry = None
+        self.on_provider_change(self.provider_names[0])
+        return self.dropdown
+
+    def on_provider_change(self, selected):
+        # Remove any extra fields
+        for widget in self.extra_frame.winfo_children():
+            widget.destroy()
+        self.extra_kwargs.clear()
+
+        if selected == "weighted":
+            tk.Label(self.extra_frame, text="Weights (comma-separated):").pack(side=tk.LEFT)
+            self.weight_entry = tk.Entry(self.extra_frame)
+            self.weight_entry.pack(side=tk.LEFT)
+
+    def apply(self):
+        self.selected_provider = self.var.get()
+        if self.selected_provider == "weighted" and self.weight_entry:
+            weights_text = self.weight_entry.get()
+            try:
+                weights = [float(w.strip()) for w in weights_text.split(',') if w.strip()]
+                self.extra_kwargs['weights'] = weights
+            except Exception:
+                messagebox.showerror("Invalid Weights", "Weights must be a comma-separated list of numbers.")
+                self.extra_kwargs['weights'] = []
+        # Add more provider-specific arguments as needed
+
+def choose_and_set_provider(root, providers_instance, image_paths):
+    provider_names = list(providers_instance.providers.keys())
+    dlg = ProviderChooserDialog(root, provider_names)
+    chosen = dlg.selected_provider
+    kwargs = dlg.extra_kwargs
+    if chosen:
+        providers_instance.reset_manager(image_paths, provider_name=chosen, **kwargs)
+        tk.messagebox.showinfo("Provider Changed", f"Provider switched to: {chosen}")
+
+# Usage remains:
+# root.bind('<p>', lambda event: choose_and_set_provider(root, providers, image_paths))