pyfastexcel 0.0.7__tar.gz → 0.0.8__tar.gz

{pyfastexcel-0.0.7 → pyfastexcel-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyfastexcel
-Version: 0.0.7
+Version: 0.0.8
 Summary: High performace excel file generation library.
 Home-page: https://github.com/Zncl2222/pyfastexcel
 Author: Zncl2222
@@ -157,6 +157,17 @@ The documentation is hosted on Read the Docs.
 
 - [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,

{pyfastexcel-0.0.7 → pyfastexcel-0.0.8}/README.md

@@ -133,6 +133,17 @@ The documentation is hosted on Read the Docs.
 
 - [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,

{pyfastexcel-0.0.7 → pyfastexcel-0.0.8}/pyfastexcel/__init__.py

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

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)

pyfastexcel-0.0.8/pyfastexcel/style.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from openpyxl_style_writer import CustomStyle
+
+BASE_DIR = Path(__file__).resolve().parent
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+ch = logging.StreamHandler()
+ch.setLevel(logging.DEBUG)
+
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+
+if not logger.hasHandlers():
+    logger.addHandler(ch)
+
+# TODO: Implement a CustomStyle without the dependency of openpyxl_style_writer
+
+
+class StyleManager:
+    """
+    A class to set custom styles for Excel files.
+
+    ### Attributes:
+        BORDER_TO_INDEX (dict[str, int]): Mapping of border styles to excelize's
+        corresponding index.
+
+    ### Methods:
+        set_custom_style(cls, name: str, custom_style: CustomStyle): Set custom style
+        by register method.
+        _create_style(): Creates custom styles for the Excel file.
+        _get_style_collections(): Gets collections of custom styles.
+        _get_default_style(): Gets the default style.
+        _update_style_map(style_name: str, custom_style: CustomStyle): Updates
+            the style map.
+        _get_font_style(style: CustomStyle): Gets the font style.
+        _get_fill_style(style: CustomStyle): Gets the fill style.
+        _get_border_style(style: CustomStyle): Gets the border style.
+        _get_alignment_style(style: CustomStyle): Gets the alignment style.
+        _get_protection_style(style: CustomStyle): Gets the protection style.
+    """
+
+    BORDER_TO_INDEX = {
+        None: 0,
+        'thick': 5,
+        'slantDashDot': 13,
+        'dotted': 4,
+        'hair': 7,
+        'dashed': 3,
+        'double': 6,
+        'mediumDashDotDot': 12,
+        'medium': 2,
+        'dashDotDot': 11,
+        'thin': 1,
+        'dashDot': 9,
+        'mediumDashed': 8,
+        'mediumDashDot': 10,
+    }
+    # The style retrieved from set_custom_style will be stored in
+    # REGISTERED_STYLES temporarily. It will be created after any
+    # Writer is initialized and calls the self._create_style() method.
+    DEFAULT_STYLE = CustomStyle()
+    REGISTERED_STYLES = {'DEFAULT_STYLE': DEFAULT_STYLE}
+    _STYLE_NAME_MAP = {}
+    _STYLE_ID = 0
+    # The shared memory in the parent class that stores every CustomStyle
+    # from different Writer classes.
+    _style_map = {}
+
+    @classmethod
+    def set_custom_style(cls, name: str, custom_style: CustomStyle):
+        cls.REGISTERED_STYLES[name] = custom_style
+        cls._STYLE_NAME_MAP[custom_style] = name
+
+    @classmethod
+    def reset_style_configs(cls):
+        cls.REGISTERED_STYLES = {'DEFAULT_STYLE': cls.DEFAULT_STYLE}
+        cls._STYLE_NAME_MAP = {}
+        cls._STYLE_ID = 0
+        cls._style_map = {}
+
+    def _get_default_style(self) -> dict[str, dict[str, Any] | str]:
+        """
+        Gets the default style.
+
+        Returns:
+            dict[str, dict[str, Any] | str]: A dictionary containing the
+                default style settings.
+        """
+        return {
+            'Font': {},
+            'Fill': {},
+            'Border': {},
+            'Alignment': {},
+            'Protection': {},
+            'CustomNumFmt': 'general',
+        }
+
+    def _update_style_map(self, style_name: str, custom_style: CustomStyle) -> None:
+        if self._style_map.get(style_name):
+            logger.warning(f'{style_name} has already existed. Overiding the style settings.')
+        self._style_map[style_name] = self._get_default_style()
+        self._style_map[style_name]['Font'] = self._get_font_style(custom_style)
+        self._style_map[style_name]['Fill'] = self._get_fill_style(custom_style)
+        self._style_map[style_name]['Border'] = self._get_border_style(custom_style)
+        self._style_map[style_name]['Alignment'] = self._get_alignment_style(custom_style)
+        self._style_map[style_name]['Protection'] = self._get_protection_style(custom_style)
+        self._style_map[style_name]['CustomNumFmt'] = custom_style.number_format
+
+    def _get_font_style(self, style: CustomStyle) -> dict[str, str | int | bool | None]:
+        font_style_map = {}
+        if style.font.name:
+            font_style_map['Family'] = style.font.name
+        if style.font.sz:
+            font_style_map['Size'] = style.font.sz
+        if style.font.b:
+            font_style_map['Bold'] = style.font.b
+        if style.font.i:
+            font_style_map['Italic'] = style.font.i
+        if style.font.strike:
+            font_style_map['Strike'] = style.font.strike
+        if style.font.u:
+            font_style_map['UnderLine'] = style.font.u
+        if style.font.color.rgb:
+            font_style_map['Color'] = f'#{style.font.color.rgb[2:]}'
+        return font_style_map
+
+    def _get_fill_style(self, style: CustomStyle) -> dict[str, str]:
+        fill_style_map = {}
+        if style.fill.fgColor.rgb:
+            fill_style_map['Color'] = f'#{style.fill.fgColor.rgb[2:]}'
+        fill_style_map['Type'] = 'pattern'
+        fill_style_map['Pattern'] = 1
+        return fill_style_map
+
+    def _get_border_style(self, style: CustomStyle) -> dict[str, str]:
+        border_style_map = {}
+        direction = ['left', 'right', 'top', 'bottom']
+
+        for d in direction:
+            border_style_map[d] = {}
+
+        if style.border.left.style:
+            border_style_map['left']['Style'] = self.BORDER_TO_INDEX[style.border.left.style]
+        if style.border.right.style:
+            border_style_map['right']['Style'] = self.BORDER_TO_INDEX[style.border.right.style]
+        if style.border.top.style:
+            border_style_map['top']['Style'] = self.BORDER_TO_INDEX[style.border.top.style]
+        if style.border.bottom.style:
+            border_style_map['bottom']['Style'] = self.BORDER_TO_INDEX[style.border.bottom.style]
+
+        if style.border.left.color.rgb:
+            border_style_map['left']['Color'] = f'#{style.border.left.color.rgb[2:]}'
+        if style.border.right.color.rgb:
+            border_style_map['right']['Color'] = f'#{style.border.right.color.rgb[2:]}'
+        if style.border.top.color.rgb:
+            border_style_map['top']['Color'] = f'#{style.border.top.color.rgb[2:]}'
+        if style.border.bottom.color.rgb:
+            border_style_map['bottom']['Color'] = f'#{style.border.bottom.color.rgb[2:]}'
+        return border_style_map
+
+    def _get_alignment_style(self, style: CustomStyle) -> dict[str, str]:
+        ali_style_map = {}
+
+        if style.ali.horizontal:
+            ali_style_map['Horizontal'] = style.ali.horizontal
+        if style.ali.vertical:
+            ali_style_map['Vertical'] = style.ali.vertical
+        if style.ali.wrapText:
+            ali_style_map['WrapText'] = style.ali.wrapText
+        if style.ali.shrinkToFit:
+            ali_style_map['ShrinkToFit'] = style.ali.shrinkToFit
+        if style.ali.indent:
+            ali_style_map['Indent'] = style.ali.indent
+        if style.ali.readingOrder:
+            ali_style_map['ReadingOrder'] = style.ali.readingOrder
+        if style.ali.textRotation:
+            ali_style_map['TextRotation'] = style.ali.textRotation
+        if style.ali.justifyLastLine:
+            ali_style_map['JustifyLastLine'] = style.ali.justifyLastLine
+        if style.ali.relativeIndent:
+            ali_style_map['RelativeIndent'] = style.ali.relativeIndent
+
+        return ali_style_map
+
+    def _get_protection_style(self, style: CustomStyle) -> dict[str, str]:
+        protection_style_map = {}
+        if style.protection.locked:
+            protection_style_map['Locked'] = style.protection.locked
+        if style.protection.hidden:
+            protection_style_map['Hidden'] = style.protection.hidden
+        return protection_style_map

{pyfastexcel-0.0.7 → pyfastexcel-0.0.8}/pyfastexcel/utils.py

@@ -2,26 +2,37 @@ from __future__ import annotations
 
 import re
 import string
+import warnings
 from typing import Any, Literal
 
 from openpyxl_style_writer import CustomStyle
 
+warnings.simplefilter('always', DeprecationWarning)
+
+
+def deprecated_warning(msg: str):
+    warnings.warn(
+        msg,
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
 
 def set_custom_style(style_name: str, style: CustomStyle) -> None:
-    from .driver import ExcelDriver
+    from .style import StyleManager
 
-    ExcelDriver.set_custom_style(style_name, style)
+    StyleManager.set_custom_style(style_name, style)
 
 
 def validate_and_register_style(style: CustomStyle) -> None:
-    from .driver import ExcelDriver
+    from .style import StyleManager
 
     if not isinstance(style, CustomStyle):
         raise TypeError(
             f'Invalid type ({type(style)}). Style should be a CustomStyle object.',
         )
-    set_custom_style(f'Custom Style {ExcelDriver._STYLE_ID}', style)
-    ExcelDriver._STYLE_ID += 1
+    set_custom_style(f'Custom Style {StyleManager._STYLE_ID}', style)
+    StyleManager._STYLE_ID += 1
 
 
 def validate_and_format_value(
@@ -37,9 +48,15 @@ def validate_and_format_value(
     return (value, 'DEFAULT_STYLE') if set_default_style else value
 
 
-def separate_alpha_numeric(input_string: str):
+def _separate_alpha_numeric(input_string: str) -> tuple[str, str]:
+    '''
+    Separate the alpha and numeric part of a string.
+    Return alpha_part at first index and num_part at second index.
+    '''
     alpha_part = re.findall(r'[a-zA-Z]+', input_string)
     num_part = re.findall(r'[0-9]+', input_string)
+    if len(alpha_part) == 0 or len(num_part) == 0:
+        raise ValueError(f'Invalid input string {input_string}.')
     return alpha_part[0], num_part[0]
 
 
@@ -80,13 +97,19 @@ def index_to_column(index: int) -> str:
 
 
 def excel_index_to_list_index(index: str) -> tuple[int, int]:
-    alpha, num = separate_alpha_numeric(index)
+    alpha, num = _separate_alpha_numeric(index)
     column = column_to_index(alpha)
     row = int(num)
     return row - 1, column - 1
 
 
-def extract_numeric_part(cell_location: str) -> str | None:
-    numeric_part = re.search(r'\d+', cell_location)
-    if numeric_part:
-        return numeric_part.group()
+def _validate_excel_index(index: str) -> bool:
+    alpha, num = _separate_alpha_numeric(index)
+    num = int(num)
+    if not all(c in string.ascii_uppercase for c in alpha):
+        raise ValueError(f'Invalid column ({alpha}). Column should be in uppercase.')
+    if not _is_valid_column(alpha):
+        raise ValueError(f"Invalid column ({alpha}). Maximum Column is 'XFD'.")
+    if num < 1 or num > 16384:
+        raise ValueError(f'Invalid index ({num}). Index should less and equal to 16384.')
+    return True

pyfastexcel-0.0.8/pyfastexcel/workbook.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from pyfastexcel.driver import ExcelDriver, WorkSheet
+from pyfastexcel.utils import deprecated_warning
+
+
+class Workbook(ExcelDriver):
+    """
+    A base class for writing data to Excel files with custom styles.
+
+    This class provides methods to set file properties, cell dimensions,
+    merge cells, manipulate sheets, and more.
+
+    Methods:
+        remove_sheet(sheet: str) -> None:
+            Removes a sheet from the Excel data.
+        create_sheet(sheet_name: str) -> None:
+            Creates a new sheet.
+        switch_sheet(sheet_name: str) -> None:
+            Set current self.sheet to a different sheet.
+        set_file_props(key: str, value: str) -> None:
+            Sets a file property.
+        set_cell_width(sheet: str, col: str | int, value: int) -> None:
+            Sets the width of a cell.
+        set_cell_height(sheet: str, row: int, value: int) -> None:
+            Sets the height of a cell.
+        set_merge_cell(sheet: str, top_left_cell: str, bottom_right_cell: str) -> None:
+            Sets a merge cell range in the specified sheet.
+    """
+
+    def remove_sheet(self, sheet: str) -> None:
+        """
+        Removes a sheet from the Excel data.
+
+        Args:
+            sheet (str): The name of the sheet to remove.
+        """
+        if len(self.workbook) == 1:
+            raise ValueError('Cannot remove the only sheet in the workbook.')
+        if self.workbook.get(sheet) is None:
+            raise IndexError(f'Sheet {sheet} does not exist.')
+        self.workbook.pop(sheet)
+        self._sheet_list = tuple(self.workbook.keys())
+        self.sheet = self._sheet_list[0]
+
+    def create_sheet(self, sheet_name: str) -> None:
+        """
+        Creates a new sheet, and set it as current self.sheet.
+
+        Args:
+            sheet_name (str): The name of the new sheet.
+        """
+        if self.workbook.get(sheet_name) is not None:
+            raise ValueError(f'Sheet {sheet_name} already exists.')
+        self.workbook[sheet_name] = WorkSheet()
+        self.sheet = sheet_name
+        self._sheet_list = tuple([x for x in self._sheet_list] + [sheet_name])
+
+    def switch_sheet(self, sheet_name: str) -> None:
+        """
+        Set current self.sheet to a different sheet. If sheet does not existed
+        then raise error.
+
+        Args:
+            sheet_name (str): The name of the sheet to switch to.
+
+        Raises:
+            IndexError: If sheet does not exist.
+        """
+        self._check_if_sheet_exists(sheet_name)
+        self.sheet = sheet_name
+
+    def set_file_props(self, key: str, value: str) -> None:
+        """
+        Sets a file property.
+
+        Args:
+            key (str): The property key.
+            value (str): The property value.
+
+        Raises:
+            ValueError: If the key is invalid.
+        """
+        if key not in self._FILE_PROPS:
+            raise ValueError(f'Invalid file property: {key}')
+        self.file_props[key] = value
+
+    def protect_workbook(
+        self,
+        algorithm: str,
+        password: str,
+        lock_structure: bool = False,
+        lock_windows: bool = False,
+    ):
+        if algorithm not in self._PROTECT_ALGORITHM:
+            raise ValueError(
+                f'Invalid algorithm, the options are {self._PROTECT_ALGORITHM}',
+            )
+        self.protection['algorithm'] = algorithm
+        self.protection['password'] = password
+        self.protection['lock_structure'] = lock_structure
+        self.protection['lock_windows'] = lock_windows
+
+    def set_cell_width(self, sheet: str, col: str | int, value: int) -> None:
+        self._check_if_sheet_exists(sheet)
+        self.workbook[sheet].set_cell_width(col, value)
+
+    def set_cell_height(self, sheet: str, row: int, value: int) -> None:
+        self._check_if_sheet_exists(sheet)
+        self.workbook[sheet].set_cell_height(row, value)
+
+    def set_merge_cell(self, sheet: str, top_left_cell: str, bottom_right_cell: str) -> None:
+        deprecated_warning(
+            "This function is going to deprecated in v1.0.0. Please use 'wb.merge_cell' instead",
+        )
+        self.merge_cell(sheet, top_left_cell, bottom_right_cell)
+
+    def merge_cell(self, sheet: str, top_left_cell: str, bottom_right_cell: str) -> None:
+        self._check_if_sheet_exists(sheet)
+        self.workbook[sheet].set_merge_cell(top_left_cell, bottom_right_cell)
+
+    def auto_filter(self, sheet: str, target_range: str) -> None:
+        self._check_if_sheet_exists(sheet)
+        self.workbook[sheet].auto_filter(target_range)