feat: bump version to 0.5.2, enhance save functionality to support in-memory operations and improve README with new examples for saving without disk access

Author: dakixr

README.md

@@ -64,6 +64,21 @@ workbook.save("output-openpyxl.xlsx", engine="openpyxl")
 workbook.save("output-xlsxwriter.xlsx", engine="xlsxwriter")
 ```
 
+### Saving without touching disk
+
+`Workbook.save` accepts a filesystem path, any binary buffer (like `io.BytesIO()`), or no target at all to get the raw bytes back:
+
+```python
+import io
+from pathlib import Path
+
+buffer = io.BytesIO()
+workbook.save(buffer, engine="xlsxwriter")  # writes into memory
+
+raw_bytes = workbook.save(engine="openpyxl")  # returns bytes when no target is provided
+Path("report.xlsx").write_bytes(raw_bytes)
+```
+
 Both engines produce equivalent Excel files, but may have subtle differences in:
 - File size and memory usage
 - Rendering performance

llm.txt

@@ -1,5 +1,4 @@
 Using xpyxl with xlsxwriter (external agents)
-- Install: dependency declared as `xlsxwriter>=3.1.0`. Import `import xpyxl as x`.
 - Build: compose nodes (no coordinates) then save with the engine you want: `x.workbook()[x.sheet("Demo")[...]].save("out.xlsx", engine="xlsxwriter")`.
 - Primitives: `x.cell[...]`, `x.row[...]`, `x.col[...]`, `x.table()[...]`, `x.vstack(..., gap=0, style=[...])`, `x.hstack(..., gap=0, style=[...])`, `x.space(rows=1, height=None)`, `x.sheet(name, background_color=None)`, `x.workbook()[...]`.
 - Table inputs: sequence of sequences, sequence of dicts (header from keys), or dict-of-lists (columns zipped). `header_style=[...]`, `style=[...]`, `column_order=[...]`.
@@ -10,10 +9,26 @@ Precomputed styles (combine in `style=[...]`)
 - Typography: `text_xs, text_sm, text_base, text_lg, text_xl, text_2xl, text_3xl, bold, italic, mono`.
 - Text colors: `text_red, text_green, text_blue, text_orange, text_purple, text_black, text_gray, text_muted, text_primary, text_white`.
 - Backgrounds: `bg_red, bg_primary, bg_muted, bg_success, bg_warning, bg_info`.
-- Alignment & layout: `text_left, text_center, text_right, align_top, align_middle, align_bottom, wrap, nowrap, wrap_shrink, allow_overflow, row_height(n), row_width(n)`.
-- Borders: `border_all, border_top, border_bottom, border_left, border_right, border_x, border_y, border_thin, border_medium, border_thick, border_dashed, border_dotted, border_double, border_none` plus color helpers `border_red/green/blue/orange/purple/black/gray/white/muted/primary`.
-- Tables: `table_bordered`, `table_banded`, `table_compact`.
-- Number/date formats: `number_comma`, `number_precision`, `percent`, `currency_usd`, `currency_eur`, `date_short`, `datetime_short`, `time_short`.
+- Alignment: `text_left, text_center, text_right, align_top, align_middle, align_bottom`.
+- Text wrapping: `wrap, nowrap, wrap_shrink, allow_overflow`.
+- Row sizing: `row_height(n), row_width(n)` (functions that take a float value).
+- Borders (sides): `border_all, border_top, border_bottom, border_left, border_right, border_x, border_y`.
+- Borders (styles): `border_thin, border_medium, border_thick, border_dashed, border_dotted, border_double, border_none`.
+- Borders (colors): `border_red, border_green, border_blue, border_orange, border_purple, border_black, border_gray, border_white, border_muted, border_primary`.
+- Tables: `table_bordered, table_banded, table_compact`.
+- Number/date formats: `number_comma, number_precision, percent, currency_usd, currency_eur, date_short, datetime_short, time_short`.
+
+Custom styles with `x.Style()`
+- If precomputed styles don't meet your needs, use `x.Style()` with any combination of these options:
+  - Font: `font_name="Arial"`, `font_size=12.0`, `font_size_delta=1.0`, `bold=True/False`, `italic=True/False`, `mono=True/False`.
+  - Colors: `text_color="#FF0000"` (hex), `fill_color="#F0F0F0"` (hex).
+  - Alignment: `horizontal_align="left"/"center"/"right"`, `vertical_align="top"/"center"/"bottom"`, `indent=2` (integer).
+  - Text wrapping: `wrap_text=True/False`, `shrink_to_fit=True/False`, `auto_width=True/False`.
+  - Row sizing: `row_height=20.0`, `row_width=100.0`.
+  - Number format: `number_format="#,##0.00"` (Excel format string).
+  - Borders: `border="thin"/"medium"/"thick"/"dashed"/"dotted"/"double"/"none"` (or "dashDot", "dashDotDot", "hair", "mediumDashDot", "mediumDashDotDot", "mediumDashed", "slantDashDot"), `border_color="#000000"`, `border_top=True/False`, `border_bottom=True/False`, `border_left=True/False`, `border_right=True/False`.
+  - Tables: `table_bordered=True/False`, `table_banded=True/False`, `table_compact=True/False`.
+- Example: `x.Style(font_size=14.0, text_color="#FF5733", fill_color="#FFF5E6", border="medium", border_top=True, border_bottom=True)`.
 
 Common patterns
 - Simple sheet: `x.sheet("Summary")[x.row(style=[x.text_2xl, x.bold])["Title"], x.row()["A", 1]]`.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xpyxl"
-version = "0.5.1"
+version = "0.5.2"
 description = "Create styled excel reports with declarative python."
 readme = "README.md"
 authors = [{ name = "dakixr", email = "[email protected]" }]

src/xpyxl/_workbook.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, BinaryIO
 
 from openpyxl import Workbook as _OpenpyxlWorkbook
 
@@ -21,18 +21,24 @@ class Workbook:
     def __init__(self, node: WorkbookNode) -> None:
         self._node = node
 
-    def save(self, path: str | Path, *, engine: EngineName = "openpyxl") -> None:
-        """Save the workbook to a file.
+    def save(
+        self,
+        target: str | Path | BinaryIO | None = None,
+        *,
+        engine: EngineName = "openpyxl",
+    ) -> bytes | None:
+        """Save the workbook to a file or binary stream.
 
         Args:
-            path: The file path to save to.
+            target: File path or binary buffer to write to. Pass None to receive
+                the rendered workbook as bytes.
             engine: The rendering engine to use. Options are "openpyxl" (default)
                 or "xlsxwriter".
         """
-        engine_instance = get_engine(engine, path)
+        engine_instance = get_engine(engine)
         for sheet in self._node.sheets:
             render_sheet(engine_instance, sheet)
-        engine_instance.save()
+        return engine_instance.save(target)
 
     def to_openpyxl(self) -> _OpenpyxlWorkbook:
         """Convert to an openpyxl Workbook object.
@@ -42,8 +48,8 @@ def to_openpyxl(self) -> _OpenpyxlWorkbook:
         """
         from .engines.openpyxl_engine import OpenpyxlEngine
 
-        # Create a temporary path - we won't actually save to it
-        engine = OpenpyxlEngine(Path("/tmp/temp.xlsx"))
+        # Render with the openpyxl engine without persisting to disk
+        engine = OpenpyxlEngine()
         for sheet in self._node.sheets:
             render_sheet(engine, sheet)
         return engine._workbook

src/xpyxl/engines/__init__.py

@@ -2,15 +2,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal
+from typing import Literal
 
 from .base import Engine
 from .openpyxl_engine import OpenpyxlEngine
 from .xlsxwriter_engine import XlsxWriterEngine
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
 __all__ = [
     "Engine",
     "OpenpyxlEngine",
@@ -22,13 +19,11 @@
 EngineName = Literal["openpyxl", "xlsxwriter"]
 
 
-def get_engine(name: EngineName, path: str | Path) -> Engine:
-    """Create an engine instance for the given name and output path."""
+def get_engine(name: EngineName) -> Engine:
+    """Create an engine instance for the given name."""
     if name == "openpyxl":
-        return OpenpyxlEngine(path)
+        return OpenpyxlEngine()
     elif name == "xlsxwriter":
-        return XlsxWriterEngine(path)
+        return XlsxWriterEngine()
     else:
         raise ValueError(f"Unknown engine: {name}")
-
-

src/xpyxl/engines/base.py

@@ -5,12 +5,12 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, BinaryIO
 
 if TYPE_CHECKING:
     from ..styles import BorderStyleName
 
-__all__ = ["Engine", "EffectiveStyle"]
+__all__ = ["Engine", "EffectiveStyle", "SaveTarget"]
 
 
 @dataclass
@@ -40,6 +40,9 @@ class EffectiveStyle:
     border_right: bool
 
 
+SaveTarget = str | Path | BinaryIO
+
+
 class Engine(ABC):
     """Abstract base class for Excel rendering engines.
 
@@ -53,8 +56,8 @@ class Engine(ABC):
       convert internally.
     """
 
-    def __init__(self, path: str | Path) -> None:
-        self._path = Path(path)
+    def __init__(self) -> None:
+        """Initialize engine state without binding to an output target."""
 
     @abstractmethod
     def create_sheet(self, name: str) -> None:
@@ -118,7 +121,13 @@ def fill_background(
         ...
 
     @abstractmethod
-    def save(self) -> None:
-        """Save the workbook to the file path."""
-        ...
+    def save(self, target: SaveTarget | None = None) -> bytes | None:
+        """Finalize and persist the workbook.
 
+        Args:
+            target: Destination to write the workbook to. If None, the engine
+                should return the workbook as bytes. When provided, the engine
+                writes to the given path or binary file-like object and should
+                return None.
+        """
+        ...

src/xpyxl/engines/openpyxl_engine.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from io import BytesIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -10,7 +11,7 @@
 from openpyxl.utils import get_column_letter
 
 from ..styles import to_argb
-from .base import EffectiveStyle, Engine
+from .base import EffectiveStyle, Engine, SaveTarget
 
 if TYPE_CHECKING:
     from openpyxl.worksheet.worksheet import Worksheet
@@ -21,8 +22,8 @@
 class OpenpyxlEngine(Engine):
     """Rendering engine using openpyxl."""
 
-    def __init__(self, path: str | Path) -> None:
-        super().__init__(path)
+    def __init__(self) -> None:
+        super().__init__()
         self._workbook = Workbook()
         # Remove default sheet created by openpyxl
         default_sheet = self._workbook.active
@@ -232,5 +233,14 @@ def fill_background(
             for cell in row:
                 cell.fill = sheet_fill
 
-    def save(self) -> None:
-        self._workbook.save(str(self._path))
+    def save(self, target: SaveTarget | None = None) -> bytes | None:
+        if target is None:
+            buffer = BytesIO()
+            self._workbook.save(buffer)
+            return buffer.getvalue()
+
+        if isinstance(target, (str, Path)):
+            self._workbook.save(str(target))
+        else:
+            self._workbook.save(target)
+        return None

src/xpyxl/engines/xlsxwriter_engine.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
+from io import BytesIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import xlsxwriter
 
 from ..styles import normalize_hex
-from .base import EffectiveStyle, Engine
+from .base import EffectiveStyle, Engine, SaveTarget
 
 if TYPE_CHECKING:
     from xlsxwriter.format import Format
@@ -40,12 +41,14 @@
 class XlsxWriterEngine(Engine):
     """Rendering engine using xlsxwriter."""
 
-    def __init__(self, path: str | Path) -> None:
-        super().__init__(path)
-        self._workbook = xlsxwriter.Workbook(str(self._path))
+    def __init__(self) -> None:
+        super().__init__()
+        self._buffer = BytesIO()
+        self._workbook = xlsxwriter.Workbook(self._buffer, {"in_memory": True})
         self._current_sheet: Worksheet | None = None
         # Cache format objects to avoid duplicates
         self._format_cache: dict[tuple[Any, ...], Format] = {}
+        self._closed = False
 
     def create_sheet(self, name: str) -> None:
         self._current_sheet = self._workbook.add_worksheet(name)
@@ -216,5 +219,18 @@ def fill_background(
             for col_idx in range(max_col):
                 self._current_sheet.write_blank(row_idx, col_idx, None, bg_fmt)
 
-    def save(self) -> None:
-        self._workbook.close()
+    def save(self, target: SaveTarget | None = None) -> bytes | None:
+        if not self._closed:
+            self._workbook.close()
+            self._closed = True
+
+        data = self._buffer.getvalue()
+        if target is None:
+            return data
+
+        if isinstance(target, (str, Path)):
+            Path(target).write_bytes(data)
+        else:
+            target.write(data)
+            target.flush()
+        return None