pyfastexcel 0.0.6__tar.gz → 0.0.8__tar.gz

pyfastexcel-0.0.8/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.1
+Name: pyfastexcel
+Version: 0.0.8
+Summary: High performace excel file generation library.
+Home-page: https://github.com/Zncl2222/pyfastexcel
+Author: Zncl2222
+Author-email: 3002shinning@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Go
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgspec
+Requires-Dist: openpyxl-style-writer>=1.1.3
+
+# pyfastexcel
+
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/go.yml?logo=go)
+[![Go Report Card](https://goreportcard.com/badge/github.com/Zncl2222/pyfastexcel)](https://goreportcard.com/report/github.com/Zncl2222/pyfastexcel)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/pre-commit.yml?logo=pre-commit&label=pre-commit)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/codeql.yml?logo=github&label=CodeQL)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/03f42030775045b791586dee20288905)](https://app.codacy.com/gh/Zncl2222/pyfastexcel/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![codecov](https://codecov.io/gh/Zncl2222/pyfastexcel/graph/badge.svg?token=6I03AWUUWL)](https://codecov.io/gh/Zncl2222/pyfastexcel)
+[![Documentation Status](https://readthedocs.org/projects/pyfastexcel/badge/?version=stable)](https://pyfastexcel.readthedocs.io/en/stable/?badge=stable)
+
+This package enables high-performance Excel writing by integrating with the
+streaming API from the golang package
+[excelize](https://github.com/qax-os/excelize). Users can leverage this
+functionality without the need to write any Go code, as the entire process
+can be accomplished through Python.
+
+## Features
+
+- Python and Golang Integration: Seamlessly call Golang built shared
+libraries from Python.
+
+- No Golang Code Required: Users can solely rely on Python for Excel file
+generation, eliminating the need for Golang expertise.
+
+## Installation
+
+### Install via pip (Recommended)
+
+You can easily install the package via pip
+
+```bash
+pip install pyfastexcel
+```
+
+### Install manually
+
+If you prefer to build the package manually, follow these steps:
+
+1. Clone the repository:
+
+    ```bash
+    git clone https://github.com/Zncl2222/pyfastexcel.git
+    ```
+
+2. Go to the project root directory:
+
+    ```bash
+    cd pyfastexcel
+    ```
+
+3. Install the required golang packages:
+
+    ```bash
+    go mod download
+    ```
+
+4. Build the Golang shared library using the Makefile:
+
+    ```bash
+    make
+    ```
+
+5. Install the required python packages:
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+    or
+
+    ```bash
+    pipenv install
+    ```
+
+6. Import the project and start using it!
+
+## Usage
+
+The index assignment is now avaliable in `Workbook` and the `FastWriter`.
+Here is the example usage:
+
+```python
+from pyfastexcel import Workbook
+from pyfastexcel.utils import set_custom_style
+
+# CustomStyle will be integrate to the pyfatexcel in next version
+# Beside, CustomStyle will be re-implement in future to make it no-longer
+# depend on openpyxl_style writer and openpyxl
+from openpyxl_style_writer import CustomStyle
+
+
+if __name__ == '__main__':
+    # Workbook
+    wb = Workbook()
+
+    # Set and register CustomStyle
+    bold_style = CustomStyle(font_size=15, font_bold=True)
+    set_custom_style('bold_style', bold_style)
+
+    ws = wb['Sheet1']
+    # Write value with default style
+    ws['A1'] = 'A1 value'
+    # Write value with custom style
+    ws['B1'] = ('B1 value', 'bold_style')
+
+    # Write value in slice with default style
+    ws['A2': 'C2'] = [1, 2, 3]
+    # Write value in slice with custom style
+    ws['A3': 'C3'] = [(1, 'bold_style'), (2, 'bold_style'), (3, 'bold_style')]
+
+    # Write value by row with default style (python index 0 is the index 1 in excel)
+    ws[3] = [9, 8, 'go']
+    # Write value by row with custom style
+    ws[4] = [(9, 'bold_style'), (8, 'bold_style'), ('go', 'bold_style')]
+
+    # Send request to golang lib and create excel
+    wb.read_lib_and_create_excel()
+
+    # File path to save
+    file_path = 'pyexample_workbook.xlsx'
+    wb.save(file_path)
+
+```
+
+You can also using the `FastWriter` or `NormalWriter` which was the
+subclass of `Workbook` to write excel row by row, see the more in documentations [quickstart](https://pyfastexcel.readthedocs.io/en/stable/quickstart/).
+
+## Documentation
+
+The documentation is hosted on Read the Docs.
+
+- [Development Version](https://pyfastexcel.readthedocs.io/en/latest/)
+
+- [Latest Stable Version](https://pyfastexcel.readthedocs.io/en/stable/)
+
+## Benchmark
+
+The following result displays the performance comparison between
+`pyfastexcel` and `openpyxl` for writing 50000 rows with 30
+columns (Total 1500000 cells). To see more benchmark results, please
+see the [benchmark](https://pyfastexcel.readthedocs.io/en/stable/benchmark/).
+
+<dev align='center'>
+    <img src='./docs/images/50000_30_horizontal_Windows11.png' width="80%" height="45%" >
+</dev>
+
+## How it Works
+
+The core functionality revolves around encoding Excel cell data and styles,
+or any other Excel properties, into a JSON string within Python. This JSON
+payload is then passed through ctypes to a Golang shared library. In Golang,
+the JSON is parsed, and using the streaming writer of
+[excelize](https://github.com/qax-os/excelize) to wrtie excel in
+high performance.
+
+## Current Limitations & Future Plans
+
+### Problem 1: Dependence on Other Excel Package
+
+Limitations:
+
+This project currently depends on the `CustomStyle` object of
+the [openpyxl_style_writer](https://github.com/Zncl2222/openpyxl_style_writer)
+package, which is built for openpyxl to write styles in write-only
+mode more efficiently without duplicating code.
+
+Future Plans:
+
+This project plans to create its own `Style` object, making it no longer
+dependent on the mentioned package.

pyfastexcel-0.0.8/README.md

@@ -0,0 +1,170 @@
+# pyfastexcel
+
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/go.yml?logo=go)
+[![Go Report Card](https://goreportcard.com/badge/github.com/Zncl2222/pyfastexcel)](https://goreportcard.com/report/github.com/Zncl2222/pyfastexcel)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/pre-commit.yml?logo=pre-commit&label=pre-commit)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Zncl2222/pyfastexcel/codeql.yml?logo=github&label=CodeQL)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/03f42030775045b791586dee20288905)](https://app.codacy.com/gh/Zncl2222/pyfastexcel/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![codecov](https://codecov.io/gh/Zncl2222/pyfastexcel/graph/badge.svg?token=6I03AWUUWL)](https://codecov.io/gh/Zncl2222/pyfastexcel)
+[![Documentation Status](https://readthedocs.org/projects/pyfastexcel/badge/?version=stable)](https://pyfastexcel.readthedocs.io/en/stable/?badge=stable)
+
+This package enables high-performance Excel writing by integrating with the
+streaming API from the golang package
+[excelize](https://github.com/qax-os/excelize). Users can leverage this
+functionality without the need to write any Go code, as the entire process
+can be accomplished through Python.
+
+## Features
+
+- Python and Golang Integration: Seamlessly call Golang built shared
+libraries from Python.
+
+- No Golang Code Required: Users can solely rely on Python for Excel file
+generation, eliminating the need for Golang expertise.
+
+## Installation
+
+### Install via pip (Recommended)
+
+You can easily install the package via pip
+
+```bash
+pip install pyfastexcel
+```
+
+### Install manually
+
+If you prefer to build the package manually, follow these steps:
+
+1. Clone the repository:
+
+    ```bash
+    git clone https://github.com/Zncl2222/pyfastexcel.git
+    ```
+
+2. Go to the project root directory:
+
+    ```bash
+    cd pyfastexcel
+    ```
+
+3. Install the required golang packages:
+
+    ```bash
+    go mod download
+    ```
+
+4. Build the Golang shared library using the Makefile:
+
+    ```bash
+    make
+    ```
+
+5. Install the required python packages:
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+    or
+
+    ```bash
+    pipenv install
+    ```
+
+6. Import the project and start using it!
+
+## Usage
+
+The index assignment is now avaliable in `Workbook` and the `FastWriter`.
+Here is the example usage:
+
+```python
+from pyfastexcel import Workbook
+from pyfastexcel.utils import set_custom_style
+
+# CustomStyle will be integrate to the pyfatexcel in next version
+# Beside, CustomStyle will be re-implement in future to make it no-longer
+# depend on openpyxl_style writer and openpyxl
+from openpyxl_style_writer import CustomStyle
+
+
+if __name__ == '__main__':
+    # Workbook
+    wb = Workbook()
+
+    # Set and register CustomStyle
+    bold_style = CustomStyle(font_size=15, font_bold=True)
+    set_custom_style('bold_style', bold_style)
+
+    ws = wb['Sheet1']
+    # Write value with default style
+    ws['A1'] = 'A1 value'
+    # Write value with custom style
+    ws['B1'] = ('B1 value', 'bold_style')
+
+    # Write value in slice with default style
+    ws['A2': 'C2'] = [1, 2, 3]
+    # Write value in slice with custom style
+    ws['A3': 'C3'] = [(1, 'bold_style'), (2, 'bold_style'), (3, 'bold_style')]
+
+    # Write value by row with default style (python index 0 is the index 1 in excel)
+    ws[3] = [9, 8, 'go']
+    # Write value by row with custom style
+    ws[4] = [(9, 'bold_style'), (8, 'bold_style'), ('go', 'bold_style')]
+
+    # Send request to golang lib and create excel
+    wb.read_lib_and_create_excel()
+
+    # File path to save
+    file_path = 'pyexample_workbook.xlsx'
+    wb.save(file_path)
+
+```
+
+You can also using the `FastWriter` or `NormalWriter` which was the
+subclass of `Workbook` to write excel row by row, see the more in documentations [quickstart](https://pyfastexcel.readthedocs.io/en/stable/quickstart/).
+
+## Documentation
+
+The documentation is hosted on Read the Docs.
+
+- [Development Version](https://pyfastexcel.readthedocs.io/en/latest/)
+
+- [Latest Stable Version](https://pyfastexcel.readthedocs.io/en/stable/)
+
+## Benchmark
+
+The following result displays the performance comparison between
+`pyfastexcel` and `openpyxl` for writing 50000 rows with 30
+columns (Total 1500000 cells). To see more benchmark results, please
+see the [benchmark](https://pyfastexcel.readthedocs.io/en/stable/benchmark/).
+
+<dev align='center'>
+    <img src='./docs/images/50000_30_horizontal_Windows11.png' width="80%" height="45%" >
+</dev>
+
+## How it Works
+
+The core functionality revolves around encoding Excel cell data and styles,
+or any other Excel properties, into a JSON string within Python. This JSON
+payload is then passed through ctypes to a Golang shared library. In Golang,
+the JSON is parsed, and using the streaming writer of
+[excelize](https://github.com/qax-os/excelize) to wrtie excel in
+high performance.
+
+## Current Limitations & Future Plans
+
+### Problem 1: Dependence on Other Excel Package
+
+Limitations:
+
+This project currently depends on the `CustomStyle` object of
+the [openpyxl_style_writer](https://github.com/Zncl2222/openpyxl_style_writer)
+package, which is built for openpyxl to write styles in write-only
+mode more efficiently without duplicating code.
+
+Future Plans:
+
+This project plans to create its own `Style` object, making it no longer
+dependent on the mentioned package.

pyfastexcel-0.0.8/pyfastexcel/__init__.py

@@ -0,0 +1,13 @@
+from openpyxl_style_writer import CustomStyle, DefaultStyle
+
+from pyfastexcel.workbook import Workbook
+from pyfastexcel.writer import StreamWriter
+
+__all__ = [
+    'Workbook',
+    'StreamWriter',
+    # Temporary link the CustomStyle from openpyxl_style_writer for
+    # convinent usage.
+    'CustomStyle',
+    'DefaultStyle',
+]

pyfastexcel-0.0.8/pyfastexcel/driver.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import base64
+import ctypes
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import msgspec
+from openpyxl_style_writer import CustomStyle
+
+from .style import StyleManager
+from .worksheet import WorkSheet
+
+BASE_DIR = Path(__file__).resolve().parent
+
+
+class ExcelDriver:
+    """
+    A driver class to write data to Excel files using custom styles.
+
+    ### Attributes:
+        BORDER_TO_INDEX (dict[str, int]): Mapping of border styles to excelize's
+        corresponding index.
+        _FILE_PROPS (dict[str, str]): Default file properties for the Excel
+        file.
+
+    ### Methods:
+        __init__(): Initializes the ExcelDriver.
+        _read_lib(lib_path: str): Reads a library for Excel manipulation.
+        read_lib_and_create_excel(lib_path: str = None): Reads the library and
+                creates the Excel file.
+    """
+
+    _FILE_PROPS = {
+        'Category': '',
+        'ContentStatus': '',
+        'Created': '',
+        'Creator': 'pyfastexcel',
+        'Description': '',
+        'Identifier': 'xlsx',
+        'Keywords': 'spreadsheet',
+        'LastModifiedBy': 'pyfastexcel',
+        'Modified': '',
+        'Revision': '0',
+        'Subject': '',
+        'Title': '',
+        'Language': 'en-Us',
+        'Version': '',
+    }
+    _PROTECT_ALGORITHM = (
+        'XOR',
+        'MD4',
+        'MD5',
+        'SHA-1',
+        'SHA-256',
+        'SHA-384',
+        'SHA-512',
+    )
+
+    def __init__(self):
+        """
+        Initializes the PyExcelizeDriver.
+
+        It initializes the Excel data, file properties, default sheet,
+        current sheet, and style mappings.
+        """
+        self.workbook = {
+            'Sheet1': WorkSheet(),
+        }
+        self.file_props = self._get_default_file_props()
+        self.sheet = 'Sheet1'
+        self._sheet_list = tuple(['Sheet1'])
+        self._dict_wb = {}
+        self.protection = {}
+        self.style = StyleManager()
+
+    @property
+    def sheet_list(self):
+        return self._sheet_list
+
+    def save(self, path: str = './pyfastexcel.xlsx') -> None:
+        if not hasattr(self, 'decoded_bytes'):
+            self.read_lib_and_create_excel()
+
+        with open(path, 'wb') as file:
+            file.write(self.decoded_bytes)
+
+    def __getitem__(self, key: str) -> WorkSheet:
+        return self.workbook[key]
+
+    def _check_if_sheet_exists(self, sheet_name: str) -> None:
+        if sheet_name not in self.sheet_list:
+            raise KeyError(f'{sheet_name} Sheet Does Not Exist.')
+
+    def read_lib_and_create_excel(self, lib_path: str = None) -> bytes:
+        """
+        Reads the library and creates the Excel file.
+
+        Args:
+            lib_path (str, optional): The path to the library. Defaults to None.
+
+        Returns:
+            bytes: The byte data of the created Excel file.
+        """
+        pyfastexcel = self._read_lib(lib_path)
+        self._create_style()
+
+        # Transfer all WorkSheet Object to the sheet dictionary in the workbook.
+        for sheet in self._sheet_list:
+            self._dict_wb[sheet] = self.workbook[sheet]._transfer_to_dict()
+
+        results = {
+            'content': self._dict_wb,
+            'file_props': self.file_props,
+            'style': self.style._style_map,
+            'protection': self.protection,
+        }
+        json_data = msgspec.json.encode(results)
+        create_excel = pyfastexcel.Export
+        free_pointer = pyfastexcel.FreeCPointer
+        free_pointer.argtypes = [ctypes.c_void_p]
+        create_excel.argtypes = [ctypes.c_char_p]
+        create_excel.restype = ctypes.c_void_p
+        byte_data = create_excel(json_data)
+        self.decoded_bytes = base64.b64decode(ctypes.cast(byte_data, ctypes.c_char_p).value)
+        free_pointer(byte_data)
+        StyleManager.reset_style_configs()
+        return self.decoded_bytes
+
+    def _read_lib(self, lib_path: str) -> ctypes.CDLL:
+        """
+        Reads a shared-library for writing Excel.
+
+        Args:
+            lib_path (str): The path to the library.
+
+        Returns:
+            ctypes.CDLL: The library object.
+        """
+        if lib_path is None:
+            if sys.platform.startswith('linux'):
+                lib_path = str(list(BASE_DIR.glob('**/*.so'))[0])
+            elif sys.platform.startswith('win32'):
+                lib_path = str(list(BASE_DIR.glob('**/*.dll'))[0])
+        lib = ctypes.CDLL(lib_path, winmode=0)
+        return lib
+
+    def _get_default_file_props(self) -> dict[str, str]:
+        now = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+        file_props = self._FILE_PROPS.copy()
+        file_props['Created'] = now
+        file_props['Modified'] = now
+        return file_props
+
+    def _get_style_collections(self) -> dict[str, CustomStyle]:
+        """
+        Gets collections of custom styles.
+
+        Returns:
+            dict[str, CustomStyle]: A dictionary containing custom style
+                collections.
+        """
+        return {
+            attr: getattr(self, attr)
+            for attr in dir(self)
+            if not callable(getattr(self, attr)) and isinstance(getattr(self, attr), CustomStyle)
+        }
+
+    def _create_style(self) -> None:
+        """
+        Creates custom styles for the Excel file.
+
+        This method initializes custom styles for the Excel file based on
+        predefined attributes.
+        """
+        style_collections = self._get_style_collections()
+        self.style._STYLE_NAME_MAP.update({val: key for key, val in style_collections.items()})
+
+        # Set the CustomStyle from the pre-defined class attributes.
+        for key, val in style_collections.items():
+            self.style._update_style_map(key, val)
+
+        # Set the CustomStyle from the REGISTERED method.
+        for key, val in self.style.REGISTERED_STYLES.items():
+            self.style._update_style_map(key, val)