enkan 2.0.2__tar.gz

enkan-2.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Sullivan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

enkan-2.0.2/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: enkan
+Version: 2.0.2
+Summary: A not-so-simple slideshow application
+Author-email: John Sullivan <benzo8@gmail.com>
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.10.5
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: python-vlc>=3.0.21203
+Requires-Dist: tqdm>=4.67.1
+Dynamic: license-file

enkan-2.0.2/README.md

@@ -0,0 +1,185 @@
+# enkan
+
+A not-so-simple slideshow application for building rich, weighted photo and video playlists that you can drive with a lean Tkinter UI. enkan reads structured text input, builds a tree of sources, and serves images (and optional video) according to the weighting rules you specify.
+
+Of course, enkan can show you images completely at random, but its real power comes as you delve deeper into weighting and grafting, giving you complete control over the balance of images you see.
+
+## Requirements
+
+- Python ≥3.11
+- Pillow
+- python-vlc (for video support)
+- matplotlib (for tree visualization)
+- tqdm (progress bars)
+
+Optional:
+
+- customtkinter (enhanced GUI appearance)
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install enkan
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/enkan.git
+cd enkan
+pip install -e .
+```
+
+If you install into a fresh environment, remember to install VLC separately so that `python-vlc` can find the native libraries.
+
+## Features
+
+- Weighted and balanced image selection modes
+- Tree-based directory organization with grafting
+- EXIF orientation support
+- Image caching for performance
+- Video playback support (via VLC)
+- Interactive GUI with zoom/pan
+- Rotation persistence to EXIF
+
+## Quick Start
+
+1. Collect your image (and optional video) folders.
+2. Create a text file (for example `shows/summer-show.txt`) that lists the folders you want to include. You can mix folders, individual files, nested `.txt` files, and inline weighting rules.
+3. Launch enkan and point it at the file:
+
+```bash
+enkan --input_file shows/summer-show.txt --run
+```
+
+enkan will parse the file, build an in-memory tree, and open the slideshow window. Use the keyboard or on-screen controls to navigate. Add `--auto 8` to advance every eight seconds, or `--random` to drop into completely random mode.
+
+## `.txt` Input Files
+
+Text files let you describe complex shows declaratively. General rules:
+
+- One path per non-empty line. Lines starting with `#` are comments.
+- Windows paths can use `\\` or `/`. Surround a path with quotes if it contains spaces or commas.
+- You can reference other `.txt`, `.lst`, or `.tree` files. enkan resolves them recursively.
+- Place any number of square-bracket modifiers before the path to alter weighting, grouping, or behaviour.
+- "Level" refers to the tree depth, which mirrors the folder depth (unless grafted), starting from root = 1
+
+### Common Modifiers
+
+| Syntax | Meaning |
+| --- | --- |
+| `[r]` | Set the entire show to run in fully random mode. |
+| `[+]keyword` | Only include files whose path contains `keyword`. Repeat for multiple must-match terms. |
+| `[-]keyword` | Exclude any path containing `keyword`. If you give an absolute file or folder, that path is skipped entirely. |
+| `[NN%]` | Multiply a branch's weight by `NN%` relative to its siblings (e.g. `[150%]` gives that branch 1.5x the default share). |
+| `[NN]` | For individual images, repeat the image `NN` times in the weighted pool. Useful for spotlighting a favourite shot. |
+| `[%NN%]` | Reserve `NN%` of the parent branch's share for this node and divide the remainder among siblings. |
+| `[bN]` | Switch the weighting mode at `level "N"` to balanced (`b`). Example: `[b2]` keeps siblings at level 2 evenly balanced. |
+| `[wN[,slope]]` | Switch the weighting mode at `level "N"` to weighted (`w`), using descendant counts to apportion remaining percentage. Negative slopes favour smaller folders, positive slopes flatten toward balanced. |
+| `[gN]` | Graft this branch up to tree level `N`, letting you bubble deep folders to a shallower menu. |
+| `[>group-name]` | Assign the line to a named group so you can share grafting, proportion, or mode changes. Combine with a `*` line to define the group (see below). |
+| `[f]` | Treat a directory as a flat bucket: gather every image under it into one node instead of mirroring the folder hierarchy. |
+| `[v]` / `[nv]` | Force-enable or disable video for this branch (overrides the default or CLI flag). |
+| `[m]` / `[nm]` | Force the slideshow to mute or unmute when media from this branch plays. |
+| `[/]` | Do not recurse beyond this directory; only its direct files are considered. |
+
+Modifiers can appear in any order so long as they precede the path, for example:
+
+``` bash
+[%40%][b3]D:\Media\Family Archive
+[150%][v]E:\Clips\Action Cams
+[>portraits][g3]F:\Photos\Portrait Sessions
+```
+
+### Global Defaults and Groups
+
+Use a line whose path is just `*` to define global or group-level behaviour:
+
+``` bash
+[b1w2]*                                     # Balanced top level, weighted from level 2 downward
+[v][nm]*                                    # Default to video enabled and audio unmuted
+[>portraits][g3][%30%][w4,-20]*             # Define the "portraits" group once
+[>portraits]F:\Photos\Portrait Sessions     # Apply the group to a folder
+```
+
+A group definition stores graft level, proportion, and mode modifiers. Any line tagged with the same `[>group]` inherits those settings.
+
+### Nesting Other Files
+
+- Pointing at another `.txt` file in a line imports everything from that file at the current position. (Only the Global Defaults from the top-level file are honoured.)
+- `.lst` files are either:
+  - plain CSV lines (`absolute\path\to\image.jpg,weight`). They are useful when you already have a hand-curated weighted list
+  - new-line delimited lists of files (`absolute\path\to\image.jpg`), as produced by irfanView, et al
+- `.tree` files are binary snapshots produced by `--outputtree`. enkan reuses them if the embedded version matches; otherwise it falls back to the sibling `.txt` / `.lst` source.
+
+## CLI Reference
+
+| Option | Purpose |
+| --- | --- |
+| `-i`, `--input_file` | One or more `.txt`, `.lst` or `.tree` files, or folder and/or file paths (including [modifiers] if desired) to process. |
+| `--run` | Explicitly launch the slideshow (optional when you omit `--output*`). |
+| `--outputlist` | Write a `.lst` file next to the inputs instead of launching the GUI. |
+| `--outputtree` | Persist the computed tree to a `.tree` file for fast reloads. |
+| `--mode` | Provide a global mode string such as `b1w2` to override file defaults. |
+| `--random` | Start in fully random mode (same as `[r]` in a file). |
+| `--auto N` | Advance automatically every `N` seconds. |
+| `--no-recurse` | Treat every supplied folder as non-recursive. |
+| `--ignore-below-bottom` | Ignore files in folders below lowest balance level. |
+| `--video` / `--no-video` | Force-enable or disable video globally. |
+| `--no-mute` | Keep audio tracks unmuted (video default is muted). |
+| `--quiet` | Suppress progress output. |
+| `--no-background` | Run loaders in the foreground (useful when debugging). |
+| `--test N` | Run `N` randomised draws and report the observed distribution. Combine with `--histo` for a matplotlib histogram. |
+| `--printtree` | Emit a text representation of the computed tree. |
+| `--testdepth`, `--histo`, `--debug` | Extra diagnostics for tuning your weighting setup. |
+
+## Hotkeys (active during slideshow)
+
+| Key | Function |
+| --- | --- |
+| Space | Next image |
+| Left | Back through history |
+| Right | Forward through history |
+| Up | Next sequential image |
+| Down | Previous sequential image |
+| N | Toggle information line |
+| C | Toggle Random Mode - overrides weightings |
+| S | Toggle Slideshow Mode - limit slideshow to subfolder containing current image |
+| N | Toggle Navigation Mode - switch between Branch and Folder. See below for details on Navigation Mode and Parent Mode|
+| P | Enter Parent Mode - move up tree and limit slideshow to images in folders below current parent |
+| I | Step backwards through Parent Mode (if possible) |
+| U | Reset Parent Mode |
+| W | Select Weighted/Balanced mode |
+| B | Select Folder Burst Mode - pick 5 images from the current folder, then randomly select the next folder and repeat |
+| L | Select Liner / Sequential Mode |
+| Ctrl-B | Reset Folder Burst Mode - pick a new folder and begin Folder Burst mode again |
+| R | Rotate image clockwise by 90 degrees |
+| Ctrl-R | Try to write current orientation to image EXIF data |
+| = / + / - | Zoom image |
+| 0 | Reset Zoom |
+| Shift-Cursor | Move viewport around zoomed image |
+| A | Toggle Auto-Advance (Timed) Mode |
+
+## Navigation and Parent Mode
+
+enkan can navigate in two modes:
+
+- Branch - Parent Mode moves up and down the branches of the tree
+- Folder - Parent Mode moves up and down the folder structure of the disk. If the folder you move to is not in the tree, enkan will need to read all the files below the current folder, whether they are in you input files or not. This can take a lot of time.
+
+## Working With Lists and Trees
+
+- Run `enkan -i show.txt --outputlist` to capture the fully expanded list (including virtual nodes and weights) into `show.lst`.
+- Run `enkan -i show.txt --outputtree` to produce `show.tree`, a binary cache you can ship with a release for faster loading.
+- Combine `--printtree` and `--test` while iterating on your `.txt` files to confirm that proportions and grafting behave the way you expect.
+
+## Tips
+
+- Keep your `.txt` files in source control alongside the media curations—they capture the intent of the show far better than flat lists.
+- Use groups to coordinate related folders (for example all portrait shoots) without repeating the same graft and mode modifiers on every line.
+- When emphasising a single standout image, prefer an absolute modifier like `[25]` on the image line instead of inflating nearby branches.
+- Large libraries benefit from building a `.tree` once and reusing it until the folder structure changes; enkan automatically regenerates it if the pickle version does not match.
+
+Have fun!

enkan-2.0.2/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-2.0.2/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-2.0.2/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-2.0.2/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-2.0.2/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)})"