lenslet 0.2.1__py3-none-any.whl

lenslet/__init__.py

@@ -0,0 +1,7 @@
+"""Lenslet: A lightweight image gallery server."""
+__version__ = "0.1.0"
+
+from .api import launch
+
+__all__ = ["launch", "__version__"]
+

lenslet/api.py

@@ -0,0 +1,157 @@
+"""Programmatic API for launching lenslet from Python/notebooks."""
+from __future__ import annotations
+import sys
+import subprocess
+import multiprocessing as mp
+from typing import Any
+
+
+def launch(
+    datasets: dict[str, list[str]],
+    blocking: bool = False,
+    port: int = 7070,
+    host: str = "127.0.0.1",
+    thumb_size: int = 256,
+    thumb_quality: int = 70,
+    verbose: bool = False,
+) -> None:
+    """
+    Launch lenslet with in-memory datasets.
+    
+    Args:
+        datasets: Dict of {dataset_name: [list of image paths/URIs]}
+                 Supports both local file paths and S3 URIs (s3://...)
+        blocking: If False (default), launches in subprocess. If True, runs in current process.
+        port: Port to listen on (default: 7070)
+        host: Host to bind to (default: 127.0.0.1)
+        thumb_size: Thumbnail short edge size in pixels (default: 256)
+        thumb_quality: Thumbnail WEBP quality 1-100 (default: 70)
+        verbose: If True, show all server logs. If False (default), only show errors.
+    
+    Example:
+        >>> import lenslet
+        >>> datasets = {
+        ...     "my_images": ["/path/to/img1.jpg", "/path/to/img2.png"],
+        ...     "s3_images": ["s3://bucket/image1.jpg", "s3://bucket/image2.jpg"],
+        ... }
+        >>> lenslet.launch(datasets, blocking=False, port=7070)
+    """
+    if not datasets:
+        raise ValueError("datasets cannot be empty")
+    
+    if blocking:
+        # Run in current process
+        _launch_blocking(
+            datasets=datasets,
+            port=port,
+            host=host,
+            thumb_size=thumb_size,
+            thumb_quality=thumb_quality,
+            verbose=verbose,
+        )
+    else:
+        # Launch in subprocess
+        _launch_subprocess(
+            datasets=datasets,
+            port=port,
+            host=host,
+            thumb_size=thumb_size,
+            thumb_quality=thumb_quality,
+            verbose=verbose,
+        )
+
+
+def _launch_blocking(
+    datasets: dict[str, list[str]],
+    port: int,
+    host: str,
+    thumb_size: int,
+    thumb_quality: int,
+    verbose: bool,
+) -> None:
+    """Launch in current process (blocking)."""
+    import uvicorn
+    from .server import create_app_from_datasets
+    
+    # Print startup banner
+    total_images = sum(len(paths) for paths in datasets.values())
+    dataset_list = ", ".join(datasets.keys())
+    
+    print(f"""
+┌─────────────────────────────────────────────────┐
+│                   🔍 Lenslet                    │
+│         Lightweight Image Gallery Server        │
+├─────────────────────────────────────────────────┤
+│  Datasets:  {dataset_list[:35]:<35} │
+│  Images:    {total_images:<35} │
+│  Server:    http://{host}:{port:<24} │
+│  Mode:      In-memory (programmatic API)        │
+└─────────────────────────────────────────────────┘
+""")
+    
+    app = create_app_from_datasets(
+        datasets=datasets,
+        thumb_size=thumb_size,
+        thumb_quality=thumb_quality,
+    )
+    
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_level="info" if verbose else "warning",
+    )
+
+
+def _launch_subprocess(
+    datasets: dict[str, list[str]],
+    port: int,
+    host: str,
+    thumb_size: int,
+    thumb_quality: int,
+    verbose: bool,
+) -> None:
+    """Launch in subprocess (non-blocking)."""
+    # We'll use multiprocessing to launch in a separate process
+    # This allows it to work in notebooks without blocking
+    
+    def _worker():
+        # Don't print banner in worker - parent process will print it
+        import uvicorn
+        from .server import create_app_from_datasets
+        
+        app = create_app_from_datasets(
+            datasets=datasets,
+            thumb_size=thumb_size,
+            thumb_quality=thumb_quality,
+        )
+        
+        uvicorn.run(
+            app,
+            host=host,
+            port=port,
+            log_level="info" if verbose else "warning",
+        )
+    
+    process = mp.Process(target=_worker, daemon=False)
+    process.start()
+    
+    # Print single info message in parent process
+    total_images = sum(len(paths) for paths in datasets.values())
+    dataset_list = ", ".join(datasets.keys())
+    
+    print(f"""
+┌─────────────────────────────────────────────────┐
+│                   🔍 Lenslet                    │
+│         Lightweight Image Gallery Server        │
+├─────────────────────────────────────────────────┤
+│  Datasets:  {dataset_list[:35]:<35} │
+│  Images:    {total_images:<35} │
+│  Server:    http://{host}:{port:<24} │
+│  Mode:      Subprocess (non-blocking)           │
+│  PID:       {process.pid:<35} │
+└─────────────────────────────────────────────────┘
+
+Gallery running at: http://{host}:{port}
+""")
+

lenslet/cli.py

@@ -0,0 +1,121 @@
+"""CLI entry point for Lenslet."""
+from __future__ import annotations
+import argparse
+import sys
+import os
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="lenslet",
+        description="Lenslet - Lightweight image gallery server",
+        epilog="Example: lenslet ~/Pictures --port 7070",
+    )
+    parser.add_argument(
+        "directory",
+        type=str,
+        nargs="?",  # Make optional for --version/--help
+        help="Directory containing images to serve",
+    )
+    parser.add_argument(
+        "-p", "--port",
+        type=int,
+        default=7070,
+        help="Port to listen on (default: 7070)",
+    )
+    parser.add_argument(
+        "-H", "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--thumb-size",
+        type=int,
+        default=256,
+        help="Thumbnail short edge size in pixels (default: 256)",
+    )
+    parser.add_argument(
+        "--thumb-quality",
+        type=int,
+        default=70,
+        help="Thumbnail WEBP quality 1-100 (default: 70)",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development",
+    )
+    parser.add_argument(
+        "--no-write",
+        action="store_true",
+        help="Disable workspace writes (.lenslet/) for one-off sessions",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed server logs",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="store_true",
+        help="Show version and exit",
+    )
+
+    args = parser.parse_args()
+
+    if args.version:
+        from . import __version__
+        print(f"lenslet {__version__}")
+        sys.exit(0)
+
+    # Directory is required unless --version
+    if not args.directory:
+        parser.print_help()
+        sys.exit(1)
+
+    # Resolve and validate directory
+    directory = Path(args.directory).expanduser().resolve()
+    if not directory.is_dir():
+        print(f"Error: '{args.directory}' is not a valid directory", file=sys.stderr)
+        sys.exit(1)
+
+    # Print startup banner
+    has_parquet = (directory / "items.parquet").is_file()
+    mode_label = "Parquet dataset" if has_parquet else "In-memory (no files written)"
+
+    print(f"""
+┌─────────────────────────────────────────────────┐
+│                   🔍 Lenslet                    │
+│         Lightweight Image Gallery Server        │
+├─────────────────────────────────────────────────┤
+│  Directory: {str(directory)[:35]:<35} │
+│  Server:    http://{args.host}:{args.port:<24} │
+│  Mode:      {mode_label:<35} │
+│  No-write:  {"ON" if args.no_write else "off":<35} │
+└─────────────────────────────────────────────────┘
+""")
+
+    # Start server
+    import uvicorn
+    from .server import create_app
+
+    app = create_app(
+        root_path=str(directory),
+        thumb_size=args.thumb_size,
+        thumb_quality=args.thumb_quality,
+        no_write=args.no_write,
+    )
+
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level="info" if args.verbose else "warning",
+    )
+
+
+if __name__ == "__main__":
+    main()