Release: Pylette 5.0.0 (#95)

* Changelog and version update

* Add better examples

* Update documentation

* Remove new in 5.0

* Update changelog

* Update old CSV-test to check JSON output instead

Author: qTipTip

CHANGELOG.md

@@ -6,19 +6,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [Unreleased]
+# Released
+
+## 5.0.0 - 22/08/2025
 
 ### Added
-- JSON export functionality for palettes with `to_json()` method
-- General `export()` method supporting multiple formats (JSON, CSV) with JSON as default
-- CLI `--export-json` flag for JSON output instead of CSV to stdout
-- CLI `--output` parameter with auto-detection for individual vs combined file export
-- Smart file naming with prefix + index (`palette_001.json`) for directory exports
-- Support for combined JSON files containing multiple palettes
-- `hex` property on `Color` class, representing RGB-values in hexadecimal
-- Pylette JSON format with colorspace-specific field names (e.g., `rgb`, `hsv`, `hls`)
+- **JSON Export**: New `to_json()` method on `Palette` class for exporting palettes to JSON format
+- **Enhanced CLI Export**:
+  - `--export-json` flag for JSON output
+  - `--output` parameter supporting both individual files and combined export
+- **Batch Processing**: Process multiple images in a single CLI command with parallel processing
+- **Color Hex Representation**: `hex` property on `Color` class providing `#RRGGBB` format
+- **Palette Metadata**: Metadata including image source, extraction parameters, and processing statistics
+- **Enhanced Progress Display**: CLI shows recently extracted palettes with color previews
+- **Rich Table Output**: Clean, colorized table display for CLI showing hex values, RGB/HSV/HLS, and frequencies
+
+### Changed
+- **CLI Interface**: Removed `--filename` and `--image-url` parameters in favor of positional image arguments
+- **Batch Processing**: CLI now processes multiple image sources by default
+
+### Removed
+- **CSV Export**: Removed `to_csv()` method from `Palette` class - use JSON export instead
+
+### Breaking Changes
+- CLI parameter changes: `--filename` and `--image-url` removed
+- `Palette.to_csv()` method removed
 
-# Released
 
 ## 4.4.0 - 20/08/2025
 

Pylette/cmd.py

@@ -4,6 +4,8 @@
 from typing import Annotated, List
 
 import typer
+from rich.console import Console
+from rich.table import Table
 
 from Pylette.src.cli_utils import PyletteProgress
 from Pylette.src.color_extraction import batch_extract_colors
@@ -52,8 +54,6 @@ def main(
         typer.echo("Error: --output is required when using --export-json", err=True)
         raise typer.Exit(1)
 
-    output_file_path = str(out_filename) if out_filename is not None else None
-
     # Set up progress bar for CLI
     with PyletteProgress(palette_size=n) as progress:
         task_id = progress.add_task("Extracting colors...", total=len(image_sources))
@@ -84,11 +84,9 @@ def progress_callback(task_number: int, result: BatchResult):
 
     if export_json and output:
         handle_json_export(successful, output, colorspace)
-    else:
-        # Original CSV behavior
-        for success in successful:
-            if success.palette is not None:
-                success.palette.to_csv(filename=output_file_path, frequency=True, stdout=stdout, colorspace=colorspace)
+    elif stdout and successful:
+        # Show clean palette summary
+        display_palette_summary(successful, colorspace)
 
     # Display colors if requested
     if display_colors:
@@ -151,6 +149,62 @@ def handle_json_export(
         typer.echo(f"✓ Exported {len(successful_results)} palettes to {output_path}")
 
 
+def display_palette_summary(successful_results: list[BatchResult], colorspace: ColorSpace) -> None:
+    """Display a clean summary of extracted palettes."""
+    console = Console()
+
+    for result in successful_results:
+        if result.palette is not None:
+            palette = result.palette
+
+            # Show extraction success message
+            source = result.source
+            if isinstance(source, str) and len(source) > 50:
+                source = "..." + source[-47:]  # Truncate long paths
+
+            console.print(f"\n✓ Extracted {palette.number_of_colors} colors from [bold]{source}[/bold]")
+
+            # Create color table
+            table = Table(show_header=True, header_style="bold blue")
+            table.add_column("Hex", style="bold", width=8)
+
+            # Add colorspace-specific column
+            colorspace_label = colorspace.value.upper()
+            if colorspace == ColorSpace.RGB:
+                table.add_column(f"{colorspace_label}", width=15)
+            else:
+                table.add_column(f"{colorspace_label}", width=20)
+                table.add_column("RGB", width=15)
+
+            table.add_column("Frequency", width=8, justify="right")
+
+            # Add color rows
+            for color in palette.colors:
+                hex_color = color.hex
+                frequency = f"{color.freq:.1%}"
+
+                # Get colorspace values
+                color_values = color.get_colors(colorspace)
+
+                if colorspace == ColorSpace.RGB:
+                    rgb_str = f"({int(color_values[0])}, {int(color_values[1])}, {int(color_values[2])})"
+                    table.add_row(f"[{hex_color}]{hex_color}[/{hex_color}]", rgb_str, frequency)
+                else:
+                    # For HSV/HLS, show both the colorspace values and RGB reference
+                    if colorspace == ColorSpace.HSV:
+                        cs_str = f"({color_values[0]:.2f}, {color_values[1]:.2f}, {color_values[2]:.2f})"
+                    else:  # HLS
+                        cs_str = f"({color_values[0]:.2f}, {color_values[1]:.2f}, {color_values[2]:.2f})"
+
+                    rgb_str = f"({color.rgb[0]}, {color.rgb[1]}, {color.rgb[2]})"
+                    table.add_row(f"[{hex_color}]{hex_color}[/{hex_color}]", cs_str, rgb_str, frequency)
+
+            console.print(table)
+
+    # Show helpful usage message
+    console.print("\n[dim]Use --export-json for structured data or --no-stdout to suppress output.[/dim]")
+
+
 def print_extraction_summary(successful: list[BatchResult], failed: list[BatchResult]):
     total = len(successful) + len(failed)
 

Pylette/src/palette.py

@@ -1,5 +1,4 @@
 import json
-from typing import Literal
 
 import numpy as np
 from PIL import Image
@@ -89,36 +88,6 @@ def __getitem__(self, item: int) -> Color:
     def __len__(self) -> int:
         return self.number_of_colors
 
-    def to_csv(
-        self,
-        filename: str | None = None,
-        frequency: bool = True,
-        colorspace: ColorSpace = ColorSpace.RGB,
-        stdout: bool = True,
-    ):
-        """
-        Dumps the palette to stdout. Saves to file if filename is specified.
-
-        Parameters:
-            filename (str | None): File to dump to.
-            frequency (bool): Whether to dump the corresponding frequency of each color.
-            colorspace (Literal["rgb", "hsv", "hls"]): Color space to use.
-            stdout (bool): Whether to dump to stdout.
-        """
-
-        if stdout:
-            print(self.metadata)
-            for color in self.colors:
-                print(",".join(map(str, color.get_colors(colorspace))))
-
-        if filename is not None:
-            with open(filename, "w") as palette_file:
-                for color in self.colors:
-                    palette_file.write(",".join(map(str, color.get_colors(colorspace))))
-                    if frequency:
-                        palette_file.write(",{}".format(color.freq))
-                    palette_file.write("\n")
-
     def random_color(self, N: int, mode: str = "frequency") -> list[Color]:
         """
         Returns N random colors from the palette, either using the frequency of each color, or choosing uniformly.
@@ -234,34 +203,25 @@ def to_json(
     def export(
         self,
         filename: str,
-        format: Literal["json", "csv"] = "json",
         colorspace: ColorSpace = ColorSpace.RGB,
-        include_frequency: bool = True,
         include_metadata: bool = True,
         stdout: bool = False,
     ) -> None:
         """
-        General export method that supports multiple formats with JSON as default.
+        Export palette to JSON format.
 
         Parameters:
-            filename (str): File to save to (extension will be added automatically).
-            format (Literal["json", "csv"]): Export format (default: json).
-            colorspace (Literal["rgb", "hsv", "hls"]): Color space to use.
-            include_frequency (bool): Whether to include frequency data.
-            include_metadata (bool): Whether to include metadata (JSON only).
+            filename (str): File to save to (extension will be added automatically if not present).
+            colorspace (ColorSpace): Color space to use.
+            include_metadata (bool): Whether to include metadata.
             stdout (bool): Whether to print to stdout.
         """
 
-        if format == "json":
-            json_filename = f"{filename}.json"
-            self.to_json(
-                filename=json_filename, colorspace=colorspace, include_metadata=include_metadata, stdout=stdout
-            )
-        elif format == "csv":
-            csv_filename = f"{filename}.csv"
-            self.to_csv(filename=csv_filename, frequency=include_frequency, colorspace=colorspace, stdout=stdout)
-        else:
-            raise ValueError(f"Unsupported format: {format}. Supported formats: 'json', 'csv'")
+        # Add .json extension if not present
+        if not filename.endswith(".json"):
+            filename = f"{filename}.json"
+
+        self.to_json(filename=filename, colorspace=colorspace, include_metadata=include_metadata, stdout=stdout)
 
     def __str__(self):
         return "".join(["({}, {}, {}, {}) \n".format(c.rgb[0], c.rgb[1], c.rgb[2], c.freq) for c in self.colors])