pyopenxlsx 0.2.0__tar.gz

pyopenxlsx-0.2.0/.clang-format

@@ -0,0 +1,3 @@
+BasedOnStyle: Google
+IndentWidth: 4
+ColumnLimit: 100

pyopenxlsx-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.idea
+.pytest_cache/
+.DS_Store
+.cache
+.ruff_cache
+.coverage
+compile_commands.json
+.benchmarks
+htmlcov
+demo

pyopenxlsx-0.2.0/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "third_party/OpenXLSX"]
+	path = third_party/OpenXLSX
+	url = git@github.com:twn39/OpenXLSX.git
+[submodule "third_party/pybind11"]
+	path = third_party/pybind11
+	url = https://github.com/pybind/pybind11.git

pyopenxlsx-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

pyopenxlsx-0.2.0/CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.15)
+project(pyopenxlsx LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Configure OpenXLSX
+set(OPENXLSX_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
+set(OPENXLSX_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(OPENXLSX_BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
+add_subdirectory(third_party/OpenXLSX)
+
+# Configure pybind11
+add_subdirectory(third_party/pybind11)
+
+# Define the python module
+pybind11_add_module(_openxlsx 
+    src/bindings.cpp
+    src/constants.cpp
+    src/types.cpp
+    src/styles.cpp
+    src/document.cpp
+    src/workbook.cpp
+    src/worksheet.cpp
+    src/cell.cpp
+)
+
+# Link dependencies
+target_link_libraries(_openxlsx PRIVATE OpenXLSX::OpenXLSX)
+
+# Install steps (handled by scikit-build-core)
+install(TARGETS _openxlsx DESTINATION pyopenxlsx)

pyopenxlsx-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.2
+Name: pyopenxlsx
+Version: 0.2.0
+Summary: Python bindings for OpenXLSX using pybind11
+Author-Email: curry tang <twn39@163.com>
+License: MIT
+Requires-Python: >=3.11
+

pyopenxlsx-0.2.0/README.md

@@ -0,0 +1,514 @@
+# pyopenxlsx
+
+`pyopenxlsx` is a high-performance Python binding for the [OpenXLSX](https://github.com/troldal/OpenXLSX) C++ library. It aims to provide significantly faster read/write speeds compared to pure Python libraries like `openpyxl`, while maintaining a Pythonic API design.
+
+## Core Features
+
+-   **High Performance**: Powered by the modern C++17 OpenXLSX library.
+-   **Pythonic API**: Intuitive interface with properties, iterators, and context managers.
+-   **Async Support**: `async/await` support for key I/O operations.
+-   **Rich Styling**: comprehensive support for fonts, fills, borders, alignments, and number formats.
+-   **Memory Safety**: Combines C++ efficiency with Python's automatic memory management.
+
+## Tech Stack
+
+| Component | Technology |
+| :--- | :--- |
+| **C++ Core** | [OpenXLSX](https://github.com/troldal/OpenXLSX) |
+| **Bindings** | [pybind11](https://github.com/pybind/pybind11) |
+| **Build System** | [scikit-build-core](https://github.com/scikit-build/scikit-build-core) & [CMake](https://cmake.org/) |
+
+## Installation
+
+### Install from Source
+
+```bash
+# Using uv (Recommended)
+uv pip install .
+
+# Or using pip
+pip install .
+```
+
+### Development Installation
+
+```bash
+uv pip install -e .
+```
+
+## Quick Start
+
+### Create and Save a Workbook
+
+```python
+from pyopenxlsx import Workbook
+
+# Create a new workbook
+with Workbook() as wb:
+    ws = wb.active
+    ws.title = "MySheet"
+    
+    # Write data
+    ws["A1"].value = "Hello"
+    ws["B1"].value = 42
+    ws.cell(row=2, column=1).value = 3.14
+    
+    # Save
+    wb.save("example.xlsx")
+```
+
+### Read a Workbook
+
+```python
+from pyopenxlsx import load_workbook
+
+wb = load_workbook("example.xlsx")
+ws = wb["MySheet"]
+print(ws["A1"].value)  # Output: Hello
+wb.close()
+```
+
+### Async Operations
+
+```python
+import asyncio
+from pyopenxlsx import load_workbook_async
+
+async def main():
+    wb = await load_workbook_async("example.xlsx")
+    ws = wb.active
+    print(ws["A1"].value)
+    
+    # Async save
+    await wb.save_async("example_saved.async.xlsx")
+    await wb.close_async()
+
+asyncio.run(main())
+```
+
+### Styling
+
+```python
+from pyopenxlsx import Workbook, Font, Fill, Border, Side, Alignment, XLColor
+
+wb = Workbook()
+ws = wb.active
+
+# Define styles
+font = Font(name="Arial", size=14, bold=True, color=XLColor(255, 0, 0))
+fill = Fill(pattern_type="solid", color=XLColor(255, 255, 0))
+border = Border(
+    left=Side(style="thin", color=XLColor(0, 0, 0)),
+    right=Side(style="thin"),
+    top=Side(style="thick"),
+    bottom=Side(style="thin")
+)
+alignment = Alignment(horizontal="center", vertical="center", wrap_text=True)
+
+# Apply style
+style_idx = wb.add_style(font=font, fill=fill, border=border, alignment=alignment)
+ws["A1"].value = "Styled Cell"
+ws["A1"].style_index = style_idx
+
+wb.save("styles.xlsx")
+```
+
+### Insert Images
+
+```python
+from pyopenxlsx import Workbook
+
+wb = Workbook()
+ws = wb.active
+
+# Insert image at A1, automatically maintaining aspect ratio
+# Requires Pillow: pip install pillow
+ws.add_image("logo.png", anchor="A1", width=200)
+
+# Or specify exact dimensions
+ws.add_image("banner.jpg", anchor="B5", width=400, height=100)
+
+wb.save("images.xlsx")
+```
+
+---
+
+## API Documentation
+
+### Module Exports
+
+```python
+from pyopenxlsx import (
+    # Core Classes
+    Workbook, Worksheet, Cell, Range,
+    load_workbook, load_workbook_async,
+    
+    # Style Classes
+    Font, Fill, Border, Side, Alignment, Style, Protection,
+    
+    # Enums & Constants
+    XLColor, XLSheetState, XLLineStyle, XLPatternType, XLAlignmentStyle,
+    XLProperty, XLUnderlineStyle, XLFontSchemeStyle, XLVerticalAlignRunStyle,
+    XLFillType,
+)
+```
+
+---
+
+### `Workbook` Class
+
+The top-level container for an Excel file.
+
+#### Constructor
+
+```python
+Workbook(filename: str | None = None)
+```
+
+-   `filename`: Optional. If provided, opens an existing file; otherwise, creates a new workbook.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `active` | `Worksheet \| None` | Get or set the currently active worksheet. |
+| `sheetnames` | `list[str]` | Returns a list of all worksheet names. |
+| `properties` | `DocumentProperties` | Access document metadata (title, author, etc.). |
+| `styles` | `XLStyles` | Access underlying style object (advanced usage). |
+| `workbook` | `XLWorkbook` | Access underlying C++ workbook object (advanced usage). |
+
+#### Methods
+
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `save(filename=None)` | `None` | Save the workbook. Saves to original path if `filename` is omitted. |
+| `save_async(filename=None)` | `Coroutine` | Asynchronously save the workbook. |
+| `close()` | `None` | Close the workbook and release resources. |
+| `close_async()` | `Coroutine` | Asynchronously close the workbook. |
+| `create_sheet(title=None, index=None)` | `Worksheet` | Create a new worksheet. `title` defaults to "Sheet1", etc. |
+| `create_sheet_async(...)` | `Coroutine` | Asynchronously create a worksheet. |
+| `remove(worksheet)` | `None` | Delete the specified worksheet. |
+| `remove_async(worksheet)` | `Coroutine` | Asynchronously delete a worksheet. |
+| `copy_worksheet(from_worksheet)` | `Worksheet` | Copy a worksheet and return the copy. |
+| `copy_worksheet_async(...)` | `Coroutine` | Asynchronously copy a worksheet. |
+| `add_style(...)` | `int` | Create a new style and return its index. See below. |
+| `add_style_async(...)` | `Coroutine` | Asynchronously create a style. |
+| `get_embedded_images()` | `list[ImageInfo]` | Get list of all images embedded in the workbook. |
+| `get_image_data(name)` | `bytes` | Get binary data of an embedded image by its name or path. |
+| `extract_images(out_dir)` | `list[str]` | Extract all images to a directory. Returns list of file paths. |
+| `extract_images_async(...)` | `Coroutine` | Asynchronously extract all images. |
+
+#### `add_style` Method
+
+```python
+def add_style(
+    font: Font | int | None = None,
+    fill: Fill | int | None = None,
+    border: Border | int | None = None,
+    alignment: Alignment | None = None,
+    number_format: str | int | None = None,
+    protection: Protection | None = None,
+) -> int:
+```
+
+**Returns:** A style index (`int`) that can be assigned to `Cell.style_index`.
+
+**Example:**
+
+```python
+# Pass all styles via a Style object
+from pyopenxlsx import Style, Font, Fill
+
+style = Style(
+    font=Font(bold=True),
+    fill=Fill(color=XLColor(200, 200, 200)),
+    number_format="0.00"
+)
+idx = wb.add_style(style)
+```
+
+---
+
+### `Worksheet` Class
+
+Represents a sheet within an Excel file.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `title` | `str` | Get or set the worksheet name. |
+| `index` | `int` | Get or set the worksheet index (0-based). |
+| `sheet_state` | `str` | Visibility: `"visible"`, `"hidden"`, `"very_hidden"`. |
+| `max_row` | `int` | Returns the maximum row index used. |
+| `max_column` | `int` | Returns the maximum column index used. |
+| `rows` | `Iterator` | Iterate over all rows with data. |
+| `merges` | `MergeCells` | Access merged cells information. |
+| `protection` | `dict` | Get worksheet protection status (read-only). |
+
+#### Methods
+
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `cell(row, column, value=None)` | `Cell` | Get cell by 1-based indices. Optionally set value. |
+| `range(address)` | `Range` | Get range by string, e.g., `ws.range("A1:C3")`. |
+| `range(start, end)` | `Range` | Get range by endpoints, e.g., `ws.range("A1", "C3")`. |
+| `merge_cells(address)` | `None` | Merge cells, e.g., `ws.merge_cells("A1:B2")`. |
+| `merge_cells_async(...)` | `Coroutine` | Asynchronously merge cells. |
+| `unmerge_cells(address)` | `None` | Unmerge cells. |
+| `unmerge_cells_async(...)` | `Coroutine` | Asynchronously unmerge cells. |
+| `append(iterable)` | `None` | Append a row of data after the last used row. |
+| `append_async(iterable)` | `Coroutine` | Asynchronously append a row. |
+| `set_column_format(col, style_idx)` | `None` | Set default style for a column. `col` can be int or "A". |
+| `set_row_format(row, style_idx)` | `None` | Set default style for a row. |
+| `column(col)` | `Column` | Get column object for width adjustments. |
+| `protect(...)` | `None` | Protect the worksheet. |
+| `protect_async(...)` | `Coroutine` | Asynchronously protect the worksheet. |
+| `unprotect()` | `None` | Unprotect the worksheet. |
+| `unprotect_async()` | `Coroutine` | Asynchronously unprotect. |
+| `add_image(...)` | `None` | Insert an image. |
+| `add_image_async(...)` | `Coroutine` | Asynchronously insert an image. |
+
+#### `add_image` Method
+
+```python
+def add_image(
+    img_path: str,
+    anchor: str = "A1",
+    width: int | None = None,
+    height: int | None = None,
+) -> None:
+```
+
+-   `img_path`: Path to image (PNG, JPG, GIF).
+-   `anchor`: Top-left cell address.
+-   `width`, `height`: Pixel dimensions. Requires Pillow for auto-detection if not provided.
+
+#### Magic Methods
+
+| Method | Description |
+| :--- | :--- |
+| `__getitem__(key)` | Get cell by address: `ws["A1"]` |
+
+---
+
+### `Cell` Class
+
+The fundamental unit of data in Excel.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `Any` | Get/Set value. Supports `str`, `int`, `float`, `bool`, `datetime`. |
+| `formula` | `Formula` | Get/Set formula string (without initial `=`). |
+| `style_index` | `int` | Get/Set style index. |
+| `style` | `int` | Alias for `style_index`. |
+| `is_date` | `bool` | True if the cell has a date format. |
+| `comment` | `str \| None` | Get/Set cell comment. Set `None` to remove. |
+| `font` | `XLFont` | Get font object (read-only). |
+| `fill` | `XLFill` | Get fill object (read-only). |
+| `border` | `XLBorder` | Get border object (read-only). |
+| `alignment` | `XLAlignment` | Get alignment object (read-only). |
+
+#### Date Handling
+
+If `is_date` is `True`, `value` automatically returns a Python `datetime` object.
+
+```python
+# Write
+ws["A1"].value = datetime(2024, 1, 15)
+ws["A1"].style_index = wb.add_style(number_format=14)  # Built-in date format
+
+# Read
+print(ws["A1"].value)   # datetime.datetime(2024, 1, 15, 0, 0)
+print(ws["A1"].is_date) # True
+```
+
+#### Formulas
+
+**Note**: Formulas must be set via the `formula` property, not `value`.
+
+```python
+# Correct
+ws["A3"].formula = "SUM(A1:A2)" 
+
+# Incorrect (treated as string)
+ws["A3"].value = "=SUM(A1:A2)"
+```
+
+---
+
+### `Range` Class
+
+Represents a rectangular area of cells.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `address` | `str` | Range address, e.g., `"A1:C3"`. |
+| `num_rows` | `int` | Row count. |
+| `num_columns` | `int` | Column count. |
+
+#### Methods
+
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `clear()` | `None` | Clear values in all cells of the range. |
+| `clear_async()` | `Coroutine` | Asynchronously clear range. |
+
+#### Iteration
+
+```python
+for cell in ws.range("A1:B2"):
+    print(cell.value)
+```
+
+---
+
+### Style Classes
+
+#### `Font`
+```python
+Font(name="Arial", size=11, bold=False, italic=False, color=None)
+```
+
+#### `Fill`
+```python
+Fill(pattern_type="solid", color=None, background_color=None)
+```
+
+#### `Border`
+```python
+Border(left=Side(), right=Side(), top=Side(), bottom=Side(), diagonal=Side())
+```
+
+#### `Side`
+```python
+Side(style="thin", color=None)
+```
+**Styles**: `"thin"`, `"thick"`, `"dashed"`, `"dotted"`, `"double"`, `"hair"`, `"medium"`, `"mediumDashed"`, `"mediumDashDot"`, `"mediumDashDotDot"`, `"slantDashDot"`
+
+#### `Alignment`
+```python
+Alignment(horizontal="center", vertical="center", wrap_text=True)
+```
+**Options**: `"left"`, `"center"`, `"right"`, `"general"`, `"top"`, `"bottom"`
+
+---
+
+### `DocumentProperties`
+
+Accessed via `wb.properties`. Supports dict-like access.
+
+-   Metadata: `title`, `subject`, `creator`, `keywords`, `description`, `last_modified_by`, `category`, `company`.
+
+```python
+wb.properties["title"] = "My Report"
+print(wb.properties["creator"])
+```
+
+---
+
+### `Column` Class
+Accessed via `ws.column(col_index)` or `ws.column("A")`.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `width` | `float` | Get or set the column width. |
+| `hidden` | `bool` | Get or set whether the column is hidden. |
+| `style_index` | `int` | Get or set the default style index for the column. |
+
+---
+
+### `Formula` Class
+Accessed via `cell.formula`.
+
+#### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `text` | `str` | Get or set the formula string. |
+
+#### Methods
+
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `clear()` | `None` | Remove the formula from the cell. |
+
+---
+
+### `MergeCells` Class
+Accessed via `ws.merges`. Represents the collection of merged ranges in a worksheet.
+
+#### Methods
+
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `append(reference)` | `None` | Create a merged range (e.g., `"A1:B2"`). |
+| `delete(index)` | `None` | Remove a merged range by its index. |
+| `find(reference)` | `int` | Find the index of a merged range. Returns -1 if not found. |
+| `__len__()` | `int` | Return the number of merged ranges. |
+| `__getitem__(index)` | `XLMergeCell` | Get a merged range object by index. |
+| `__iter__()` | `Iterator` | Iterate over all merged ranges. |
+| `__contains__(ref)` | `bool` | Check if a reference is within any merged range. |
+
+---
+
+### `ImageInfo` Class
+Returned by `wb.get_embedded_images()`.
+
+#### Attributes
+
+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `str` | Filename of the image. |
+| `path` | `str` | Internal path in the XLSX archive. |
+| `extension` | `str` | File extension (e.g., "png"). |
+
+---
+
+### Helper Functions
+
+#### `load_workbook`
+```python
+def load_workbook(filename: str) -> Workbook:
+    """Open an existing Excel file."""
+```
+
+#### `load_workbook_async`
+```python
+async def load_workbook_async(filename: str) -> Workbook:
+    """Asynchronously open an existing Excel file."""
+```
+
+#### `is_date_format`
+```python
+def is_date_format(format_code: int | str) -> bool:
+    """
+    Check if a number format code (int) or string represents a date/time format.
+    Useful for determining if a cell value should be treated as a datetime.
+    """
+```
+
+---
+
+## Development
+
+### Run Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# With coverage
+uv run pytest --cov=src/pyopenxlsx --cov-report=term-missing
+```
+
+## License
+
+MIT License.
+The underlying OpenXLSX library is licensed under its own terms.

pyopenxlsx-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["scikit-build-core", "pybind11"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "pyopenxlsx"
+version = "0.2.0"
+description = "Python bindings for OpenXLSX using pybind11"
+authors = [{name = "curry tang", email = "twn39@163.com"}]
+license = {text = "MIT"}
+requires-python = ">=3.11"
+
+[tool.scikit-build]
+cmake.version = ">=3.15"
+wheel.packages = ["src/pyopenxlsx"]
+
+[dependency-groups]
+dev = [
+    "clang-tidy>=21.1.6",
+    "openpyxl>=3.1.5",
+    "pillow>=12.1.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
+    "pytest-benchmark>=4.0.0",
+    "numpy>=1.26.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov=pyopenxlsx --cov-report=term-missing --cov-report=html"
+testpaths = ["tests"]
+norecursedirs = ["third_party"]
+
+[tool.coverage.run]
+source = ["src/pyopenxlsx"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "pass",
+    "raise ImportError",
+]
+
+[tool.ty.analysis]
+allowed-unresolved-imports = ["pyopenxlsx._openxlsx"]

pyopenxlsx-0.2.0/src/bindings.cpp

@@ -0,0 +1,12 @@
+#include "bindings.hpp"
+
+PYBIND11_MODULE(_openxlsx, m) {
+    m.doc() = "Python bindings for OpenXLSX";
+    init_constants(m);
+    init_types(m);
+    init_styles(m);
+    init_document(m);
+    init_workbook(m);
+    init_worksheet(m);
+    init_cell(m);
+}

pyopenxlsx-0.2.0/src/bindings.hpp

@@ -0,0 +1,21 @@
+#ifndef PYOPENXLSX_BINDINGS_HPP
+#define PYOPENXLSX_BINDINGS_HPP
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include <OpenXLSX.hpp>
+
+namespace py = pybind11;
+using namespace OpenXLSX;
+
+// 子模块初始化函数声明
+void init_constants(py::module& m);
+void init_types(py::module& m);
+void init_styles(py::module& m);
+void init_document(py::module& m);
+void init_workbook(py::module& m);
+void init_worksheet(py::module& m);
+void init_cell(py::module& m);
+
+#endif  // PYOPENXLSX_BINDINGS_HPP