xlsxturbo 0.8.0__tar.gz → 0.10.1__tar.gz

{xlsxturbo-0.8.0 → xlsxturbo-0.10.1}/CHANGELOG.md

@@ -5,6 +5,76 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [0.10.1] - 2026-01-16
+
+### Changed
+- **Benchmark suite reorganization** - Moved benchmarks to `benchmarks/` directory
+  - New `benchmarks/benchmark.py` - comprehensive comparison vs polars, pandas+openpyxl, pandas+xlsxwriter
+  - Moved `benchmark_parallel.py` to `benchmarks/`
+  - Removed obsolete `benchmark.py` (referenced old Rust binary)
+- **README Performance section** - Updated with reproducible benchmark methodology
+  - Changed performance claim from "~25x faster" to "~6x faster" (accurate for typical workloads)
+  - Added disclaimer that results vary by system
+  - Linked to Benchmarking section for running your own tests
+
+## [0.10.0] - 2026-01-16
+
+### Added
+- **Comments/Notes** - Add cell annotations with optional author
+  - Simple text: `comments={'A1': 'Note text'}`
+  - With author: `comments={'A1': {'text': 'Note', 'author': 'John'}}`
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+- **Data Validation** - Add dropdowns and constraints to columns
+  - List (dropdown): `validations={'Status': {'type': 'list', 'values': ['Open', 'Closed']}}`
+  - Whole number: `validations={'Score': {'type': 'whole_number', 'min': 0, 'max': 100}}`
+  - Decimal: `validations={'Price': {'type': 'decimal', 'min': 0.0, 'max': 999.99}}`
+  - Text length: `validations={'Code': {'type': 'text_length', 'min': 3, 'max': 10}}`
+  - Supports input/error messages: `input_title`, `input_message`, `error_title`, `error_message`
+  - Supports column patterns (like `column_formats`)
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+- **Rich Text** - Multiple formats within a single cell
+  - Format segments: `rich_text={'A1': [('Bold', {'bold': True}), ' normal text']}`
+  - Supports: `bold`, `italic`, `font_color`, `bg_color`, `font_size`, `underline`
+  - Mix formatted and plain text segments
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+- **Images** - Embed PNG, JPEG, GIF, BMP images in cells
+  - Simple path: `images={'B5': 'logo.png'}`
+  - With options: `images={'B5': {'path': 'logo.png', 'scale_width': 0.5, 'scale_height': 0.5}}`
+  - Options: `path`, `scale_width`, `scale_height`, `alt_text`
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+
+### Notes
+- All new features are disabled in `constant_memory` mode (they require random access)
+- Data validation list values are limited to 255 total characters (Excel limitation)
+
+## [0.9.0] - 2026-01-15
+
+### Added
+- **Conditional formatting** - Visual formatting based on cell values
+  - `2_color_scale`: Gradient from min_color to max_color
+  - `3_color_scale`: Three-color gradient with min/mid/max colors
+  - `data_bar`: In-cell bar chart with customizable color, direction, solid fill
+  - `icon_set`: Traffic lights, arrows, flags (3/4/5 icons), with reverse and icons_only options
+  - Supports column name patterns: `'price_*': {'type': 'data_bar', ...}`
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+  - Example: `conditional_formats={'score': {'type': '2_color_scale', 'min_color': '#FF0000', 'max_color': '#00FF00'}}`
+- **Formula columns** - Add calculated columns with Excel formulas
+  - Use `{row}` placeholder for row numbers (1-based)
+  - Columns appear after data columns
+  - Order preserved (first formula = first new column)
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+  - Example: `formula_columns={'Total': '=A{row}+B{row}', 'Percentage': '=C{row}/D{row}*100'}`
+- **Merged cells** - Merge cell ranges for headers, titles, and grouped labels
+  - Uses Excel notation for ranges (e.g., 'A1:D1')
+  - Optional formatting with HeaderFormat options (bold, colors, etc.)
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+  - Example: `merged_ranges=[('A1:C1', 'Title'), ('A2:C2', 'Subtitle', {'bold': True})]`
+- **Hyperlinks** - Add clickable links to cells
+  - Uses Excel notation for cell reference (e.g., 'A1', 'B5')
+  - Optional display text (defaults to URL if not provided)
+  - Available in both `df_to_xlsx()` and `dfs_to_xlsx()` with per-sheet overrides
+  - Example: `hyperlinks=[('A2', 'https://example.com'), ('B2', 'https://google.com', 'Google')]`
+
 ## [0.8.0] - 2026-01-15
 
 ### Added
@@ -143,6 +213,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for custom sheet names
 - Verbose mode for progress reporting
 
+[0.10.1]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.10.1
+[0.10.0]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.10.0
+[0.9.0]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.9.0
 [0.8.0]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.8.0
 [0.7.0]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.7.0
 [0.6.0]: https://github.com/tstone-1/xlsxturbo/releases/tag/v0.6.0

{xlsxturbo-0.8.0 → xlsxturbo-0.10.1}/Cargo.lock

@@ -673,9 +673,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "wasip2"
-version = "1.0.1+wasi-0.2.4"
+version = "1.0.2+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7"
+checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
 dependencies = [
  "wit-bindgen",
 ]
@@ -795,13 +795,13 @@ dependencies = [
 
 [[package]]
 name = "wit-bindgen"
-version = "0.46.0"
+version = "0.51.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
 
 [[package]]
 name = "xlsxturbo"
-version = "0.8.0"
+version = "0.10.1"
 dependencies = [
  "chrono",
  "clap",

{xlsxturbo-0.8.0 → xlsxturbo-0.10.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "xlsxturbo"
-version = "0.8.0"
+version = "0.10.1"
 edition = "2021"
 description = "High-performance Excel writer with automatic type detection (pandas, polars, CSV)"
 license = "MIT"

{xlsxturbo-0.8.0 → xlsxturbo-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlsxturbo
-Version: 0.8.0
+Version: 0.10.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -39,6 +39,14 @@ High-performance Excel writer with automatic type detection. Written in Rust, us
 
 - **Direct DataFrame support** for pandas and polars
 - **Excel tables** - filterable tables with 61 built-in styles (banded rows, autofilter)
+- **Conditional formatting** - color scales, data bars, icon sets for visual data analysis
+- **Formula columns** - add calculated columns with Excel formulas
+- **Merged cells** - merge cell ranges for headers and titles
+- **Hyperlinks** - add clickable links to cells
+- **Comments/Notes** - add cell annotations with optional author
+- **Data validation** - dropdowns, number ranges, text length constraints
+- **Rich text** - multiple formats within a single cell
+- **Images** - embed PNG, JPEG, GIF, BMP in cells
 - **Auto-fit columns** - automatically adjust column widths to fit content
 - **Custom column widths** - set specific widths per column or cap all with _all
 - **Header styling** - bold, colors, font size for header row
@@ -56,7 +64,7 @@ High-performance Excel writer with automatic type detection. Written in Rust, us
   - Datetimes (ISO 8601) → Excel datetimes
   - `NaN`/`Inf` → Empty cells (graceful handling)
   - Everything else → Text
-- **~25x faster** than pandas + openpyxl
+- **~6x faster** than pandas + openpyxl (see [benchmarks](#performance))
 - **Memory efficient** - streams data with 1MB buffer
 - Available as both **Python library** and **CLI tool**
 
@@ -337,6 +345,370 @@ Available per-sheet options:
 - `table_name` (str): Custom Excel table name
 - `header_format` (dict): Header cell styling
 - `column_formats` (dict): Column formatting with pattern matching
+- `conditional_formats` (dict): Conditional formatting (color scales, data bars, icons)
+- `formula_columns` (dict): Calculated columns with Excel formulas (column name -> formula template)
+- `merged_ranges` (list): List of (range, text) or (range, text, format) tuples to merge cells
+- `hyperlinks` (list): List of (cell, url) or (cell, url, display_text) tuples to add clickable links
+- `comments` (dict): Cell comments/notes (cell_ref -> text or {text, author})
+- `validations` (dict): Data validation rules (column name/pattern -> validation config)
+- `rich_text` (dict): Rich text with multiple formats (cell_ref -> list of segments)
+- `images` (dict): Embedded images (cell_ref -> path or {path, scale_width, scale_height, alt_text})
+
+### Conditional Formatting
+
+Apply visual formatting based on cell values:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'name': ['Alice', 'Bob', 'Charlie', 'Diana'],
+    'score': [95, 72, 88, 45],
+    'progress': [0.9, 0.5, 0.75, 0.3],
+    'status': [3, 2, 3, 1]
+})
+
+xlsxturbo.df_to_xlsx(df, "report.xlsx",
+    autofit=True,
+    conditional_formats={
+        # 2-color gradient: red (low) to green (high)
+        'score': {
+            'type': '2_color_scale',
+            'min_color': '#FF6B6B',
+            'max_color': '#51CF66'
+        },
+        # Data bars: in-cell bar chart
+        'progress': {
+            'type': 'data_bar',
+            'bar_color': '#339AF0',
+            'solid': True  # Solid fill instead of gradient
+        },
+        # Icon set: traffic lights
+        'status': {
+            'type': 'icon_set',
+            'icon_type': '3_traffic_lights'
+        }
+    }
+)
+```
+
+**Supported conditional format types:**
+
+| Type | Options |
+|------|---------|
+| `2_color_scale` | `min_color`, `max_color` |
+| `3_color_scale` | `min_color`, `mid_color`, `max_color` |
+| `data_bar` | `bar_color`, `border_color`, `solid`, `direction` |
+| `icon_set` | `icon_type`, `reverse`, `icons_only` |
+
+**Available icon types:**
+- 3 icons: `3_arrows`, `3_arrows_gray`, `3_flags`, `3_traffic_lights`, `3_traffic_lights_rimmed`, `3_signs`, `3_symbols`, `3_symbols_uncircled`
+- 4 icons: `4_arrows`, `4_arrows_gray`, `4_traffic_lights`, `4_rating`
+- 5 icons: `5_arrows`, `5_arrows_gray`, `5_quarters`, `5_rating`
+
+Column patterns work with conditional formats:
+```python
+# Apply data bars to all columns starting with "price_"
+conditional_formats={'price_*': {'type': 'data_bar', 'bar_color': '#9B59B6'}}
+```
+
+### Formula Columns
+
+Add calculated columns to your Excel output. Formulas are written after data columns and use `{row}` as a placeholder for the row number:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'price': [100, 200, 150],
+    'quantity': [5, 3, 8],
+    'tax_rate': [0.1, 0.1, 0.2]
+})
+
+xlsxturbo.df_to_xlsx(df, "sales.xlsx",
+    autofit=True,
+    formula_columns={
+        'Subtotal': '=A{row}*B{row}',      # price * quantity
+        'Tax': '=D{row}*C{row}',            # subtotal * tax_rate
+        'Total': '=D{row}+E{row}'           # subtotal + tax
+    }
+)
+```
+
+Formula columns appear after data columns (A=price, B=quantity, C=tax_rate, D=Subtotal, E=Tax, F=Total).
+
+**Notes:**
+- `{row}` is replaced with the Excel row number (1-based, starting at 2 for data rows when header=True)
+- Formula columns inherit header formatting if specified
+- Column order is preserved (first formula = first new column)
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+
+### Merged Cells
+
+Merge cell ranges to create headers, titles, or grouped labels:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'product': ['Widget A', 'Widget B'],
+    'sales': [1500, 2300],
+    'revenue': [7500, 11500]
+})
+
+# Merge cells for a title above the data
+xlsxturbo.df_to_xlsx(df, "report.xlsx",
+    header=True,
+    merged_ranges=[
+        # Simple merge with text (auto-centered)
+        ('A1:C1', 'Q4 Sales Report'),
+        # Merge with custom formatting
+        ('A2:C2', 'Regional Data', {
+            'bold': True,
+            'bg_color': '#4F81BD',
+            'font_color': 'white'
+        })
+    ]
+)
+```
+
+**Merged range format:**
+- Tuple of `(range, text)` or `(range, text, format_dict)`
+- Range uses Excel notation: `'A1:D1'`, `'B3:B10'`, etc.
+- Format options same as `header_format`: bold, italic, font_color, bg_color, font_size, underline
+
+**Notes:**
+- Merged cells are applied after data is written, so plan row positions accordingly
+- When using with `header=True`, data starts at row 2 (Excel row 2)
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+
+### Hyperlinks
+
+Add clickable links to cells:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'company': ['Anthropic', 'Google', 'Microsoft'],
+    'product': ['Claude', 'Gemini', 'Copilot'],
+})
+
+# Add hyperlinks to a new column (D) after the data columns (A, B, C with header)
+xlsxturbo.df_to_xlsx(df, "companies.xlsx",
+    autofit=True,
+    hyperlinks=[
+        # Header for the links column
+        ('C1', 'https://example.com', 'Website'),
+        # Links with company names as display text
+        ('C2', 'https://anthropic.com', 'anthropic.com'),
+        ('C3', 'https://google.com', 'google.com'),
+        ('C4', 'https://microsoft.com', 'microsoft.com'),
+    ]
+)
+```
+
+**Hyperlink format:**
+- Tuple of `(cell, url)` or `(cell, url, display_text)`
+- Cell uses Excel notation: `'A1'`, `'B5'`, etc.
+- Display text is optional; if omitted, the URL is shown
+
+**Notes:**
+- Hyperlinks write to the specified cell position (overwrites existing content)
+- To add a "links column", target cells beyond your DataFrame columns (as shown above)
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+- Not available in constant memory mode
+
+### Comments/Notes
+
+Add cell annotations (hover to view):
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'product': ['Widget A', 'Widget B'],
+    'price': [19.99, 29.99]
+})
+
+xlsxturbo.df_to_xlsx(df, "report.xlsx",
+    comments={
+        # Simple text comment
+        'A1': 'This column contains product names',
+        # Comment with author
+        'B1': {'text': 'Prices in USD', 'author': 'Finance Team'}
+    }
+)
+```
+
+**Comment format:**
+- Simple: `{'A1': 'Note text'}`
+- With author: `{'A1': {'text': 'Note text', 'author': 'Name'}}`
+
+**Notes:**
+- Comments appear as small red triangles in the cell corner
+- Hover over the cell to see the comment
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+- Not available in constant memory mode
+
+### Data Validation
+
+Add dropdowns and input constraints:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({
+    'status': ['Open', 'Closed'],
+    'score': [85, 92],
+    'price': [19.99, 29.99],
+    'code': ['ABC', 'XYZ']
+})
+
+xlsxturbo.df_to_xlsx(df, "validated.xlsx",
+    validations={
+        # Dropdown list
+        'status': {
+            'type': 'list',
+            'values': ['Open', 'Closed', 'Pending', 'Review']
+        },
+        # Whole number range (0-100)
+        'score': {
+            'type': 'whole_number',
+            'min': 0,
+            'max': 100,
+            'error_title': 'Invalid Score',
+            'error_message': 'Score must be between 0 and 100'
+        },
+        # Decimal range
+        'price': {
+            'type': 'decimal',
+            'min': 0.0,
+            'max': 999.99
+        },
+        # Text length constraint
+        'code': {
+            'type': 'text_length',
+            'min': 3,
+            'max': 10
+        }
+    }
+)
+```
+
+**Validation types:**
+
+| Type | Aliases | Description | Options |
+|------|---------|-------------|---------|
+| `list` | - | Dropdown menu | `values` (list of strings, max 255 chars total) |
+| `whole_number` | `whole`, `integer` | Integer range | `min`, `max` |
+| `decimal` | `number` | Decimal range | `min`, `max` |
+| `text_length` | `textlength`, `length` | Character count | `min`, `max` |
+
+**Optional message options:**
+- `input_title`, `input_message`: Prompt shown when cell is selected
+- `error_title`, `error_message`: Message shown when invalid data is entered
+
+**Notes:**
+- Validations apply to the data rows of the specified column
+- Column patterns work: `'score_*': {...}` matches all columns starting with `score_`
+- If only `min` or only `max` is specified, the other defaults to the type's extreme value
+- List validation values are limited to 255 total characters (Excel limitation)
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+- Not available in constant memory mode
+
+### Rich Text
+
+Multiple formats within a single cell:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({'A': [1, 2, 3]})
+
+xlsxturbo.df_to_xlsx(df, "rich.xlsx",
+    rich_text={
+        'D1': [
+            ('Important: ', {'bold': True, 'font_color': 'red'}),
+            'Please review ',
+            ('all', {'italic': True}),
+            ' values'
+        ],
+        'D2': [
+            ('Status: ', {'bold': True}),
+            ('OK', {'font_color': 'green', 'bold': True})
+        ]
+    }
+)
+```
+
+**Segment format:**
+- Formatted: `('text', {'bold': True, 'font_color': 'blue'})`
+- Plain: `'plain text'` (no formatting)
+
+**Available format options:**
+- `bold` (bool)
+- `italic` (bool)
+- `font_color` (str): '#RRGGBB' or named color
+- `bg_color` (str): Background color
+- `font_size` (float)
+- `underline` (bool)
+
+**Notes:**
+- Rich text writes to the specified cell position (overwrites existing content)
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+- Not available in constant memory mode
+
+### Images
+
+Embed images in cells:
+
+```python
+import xlsxturbo
+import pandas as pd
+
+df = pd.DataFrame({'Product': ['Widget A', 'Widget B'], 'Price': [19.99, 29.99]})
+
+xlsxturbo.df_to_xlsx(df, "catalog.xlsx",
+    autofit=True,
+    images={
+        # Simple path
+        'C2': 'images/widget_a.png',
+        # With options
+        'C3': {
+            'path': 'images/widget_b.png',
+            'scale_width': 0.5,
+            'scale_height': 0.5,
+            'alt_text': 'Widget B photo'
+        }
+    }
+)
+```
+
+**Image format:**
+- Simple: `{'C2': 'path/to/image.png'}`
+- With options: `{'C2': {'path': '...', 'scale_width': 0.5, ...}}`
+
+**Available options:**
+- `path` (str, required): Path to image file
+- `scale_width` (float): Width scale factor (1.0 = original)
+- `scale_height` (float): Height scale factor (1.0 = original)
+- `alt_text` (str): Alternative text for accessibility
+
+**Supported formats:** PNG, JPEG, GIF, BMP
+
+**Notes:**
+- Images are positioned at the specified cell (overlays any existing content)
+- Image file must exist; non-existent files will raise an error
+- Works with both `df_to_xlsx` and `dfs_to_xlsx` (global or per-sheet)
+- Not available in constant memory mode
 
 ### Constant Memory Mode (Large Files)
 
@@ -365,7 +737,18 @@ xlsxturbo.dfs_to_xlsx([
 - `table_style` (Excel tables)
 - `freeze_panes`
 - `row_heights`
+- `conditional_formats`
+- `merged_ranges`
+- `hyperlinks`
+- `comments`
+- `validations`
+- `rich_text`
+- `images`
 - `autofit`
+- `conditional_formats`
+- `formula_columns`
+- `merged_ranges`
+- `hyperlinks`
 
 Column widths still work in constant memory mode.
 
@@ -424,15 +807,16 @@ xlsxturbo sales.csv report.xlsx -d eu -v --sheet-name "Q4 Sales"
 
 ## Performance
 
-Benchmarked on 525,684 rows x 98 columns:
+*Reference benchmark on 100,000 rows x 50 columns with mixed data types. Your results will vary by system - run the benchmark yourself (see [Benchmarking](#benchmarking)).*
+
+| Library | Time (s) | Rows/sec | vs xlsxturbo |
+|---------|----------|----------|--------------|
+| **xlsxturbo** | **6.65** | **15,033** | **1.0x** |
+| polars | 25.07 | 3,988 | 3.8x |
+| pandas + xlsxwriter | 35.60 | 2,809 | 5.4x |
+| pandas + openpyxl | 38.85 | 2,574 | 5.8x |
 
-| Method | Time | Speedup |
-|--------|------|---------|
-| **xlsxturbo** | 28.5s | **26.7x** |
-| PyExcelerate | 107s | 7.1x |
-| pandas + xlsxwriter | 374s | 2.0x |
-| pandas + openpyxl | 762s | 1.0x |
-| polars.write_excel | 1039s | 0.7x |
+*Test system: Windows 11, Python 3.14, AMD Ryzen 9 (32 threads)*
 
 ## Type Detection Examples
 
@@ -468,14 +852,24 @@ maturin build --release
 
 ## Benchmarking
 
-Run the included benchmark script:
+Run the included benchmark scripts:
 
 ```bash
-# Default: 100K rows x 50 columns
-python benchmark.py
+# Compare xlsxturbo vs other libraries (100K rows default)
+python benchmarks/benchmark.py
+
+# Full benchmark: small, medium, large datasets
+python benchmarks/benchmark.py --full
 
 # Custom size
-python benchmark.py --rows 500000 --cols 100
+python benchmarks/benchmark.py --rows 500000 --cols 100
+
+# Output formats for CI/documentation
+python benchmarks/benchmark.py --markdown
+python benchmarks/benchmark.py --json
+
+# Test parallel vs single-threaded CSV conversion
+python benchmarks/benchmark_parallel.py
 ```
 
 ## License