xlsxturbo 0.9.0__tar.gz → 0.10.1__tar.gz

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

@@ -5,6 +5,48 @@ 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
@@ -171,6 +213,8 @@ 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

{xlsxturbo-0.9.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.9.0"
+version = "0.10.1"
 dependencies = [
  "chrono",
  "clap",

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlsxturbo
-Version: 0.9.0
+Version: 0.10.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -43,6 +43,10 @@ High-performance Excel writer with automatic type detection. Written in Rust, us
 - **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
@@ -60,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**
 
@@ -345,6 +349,10 @@ Available per-sheet options:
 - `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
 
@@ -515,6 +523,193 @@ xlsxturbo.df_to_xlsx(df, "companies.xlsx",
 - 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)
 
 For very large files (millions of rows), use `constant_memory=True` to minimize RAM usage:
@@ -542,6 +737,13 @@ 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`
@@ -605,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
 
@@ -649,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

{xlsxturbo-0.9.0 → xlsxturbo-0.10.1}/README.md

@@ -10,6 +10,10 @@ High-performance Excel writer with automatic type detection. Written in Rust, us
 - **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
@@ -27,7 +31,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**
 
@@ -312,6 +316,10 @@ Available per-sheet options:
 - `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
 
@@ -482,6 +490,193 @@ xlsxturbo.df_to_xlsx(df, "companies.xlsx",
 - 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)
 
 For very large files (millions of rows), use `constant_memory=True` to minimize RAM usage:
@@ -509,6 +704,13 @@ 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`
@@ -572,15 +774,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
 
@@ -616,14 +819,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