pyfastexcel 0.0.7__tar.gz → 0.0.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyfastexcel
-Version: 0.0.7
+Version: 0.0.9
 Summary: High performace excel file generation library.
 Home-page: https://github.com/Zncl2222/pyfastexcel
 Author: Zncl2222
@@ -100,7 +100,7 @@ If you prefer to build the package manually, follow these steps:
 
 ## Usage
 
-The index assignment is now avaliable in `Workbook` and the `FastWriter`.
+The index assignment is now avaliable in `Workbook` and the `StreamWriter`.
 Here is the example usage:
 
 ```python
@@ -146,8 +146,8 @@ if __name__ == '__main__':
 
 ```
 
-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/).
+You can also using the `StreamWriter` which was the
+subclass of `Workbook` to write excel row by row, see more in [StreamWriter](https://pyfastexcel.readthedocs.io/en/stable/writer/).
 
 ## Documentation
 
@@ -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.9}/README.md

@@ -76,7 +76,7 @@ If you prefer to build the package manually, follow these steps:
 
 ## Usage
 
-The index assignment is now avaliable in `Workbook` and the `FastWriter`.
+The index assignment is now avaliable in `Workbook` and the `StreamWriter`.
 Here is the example usage:
 
 ```python
@@ -122,8 +122,8 @@ if __name__ == '__main__':
 
 ```
 
-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/).
+You can also using the `StreamWriter` which was the
+subclass of `Workbook` to write excel row by row, see more in [StreamWriter](https://pyfastexcel.readthedocs.io/en/stable/writer/).
 
 ## Documentation
 
@@ -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.9}/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.9/pyfastexcel/_typing.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict, Optional, List, Union
+
+
+class CommentTextDict(TypedDict, total=False):
+    text: str
+    size: Optional[int]
+    name: Optional[str]
+    bold: Optional[bool]
+    italic: Optional[bool]
+    underline: Optional[Literal['single', 'double']]
+    strike: Optional[bool]
+    vert_align: Optional[str]
+    color: Optional[str]
+
+
+class SelectionDict(TypedDict, total=False):
+    sq_ref: str
+    active_cell: str
+    pane: str
+
+
+CommentTextStructure = Union[str, List[str], CommentTextDict, List[CommentTextDict]]
+SetPanesSelection = List[SelectionDict]

pyfastexcel-0.0.9/pyfastexcel/driver.py

@@ -0,0 +1,192 @@
+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:
+        _FILE_PROPS (dict[str, str]): Default file properties for the Excel
+        file.
+        _PROTECT_ALGORITHM (tuple[str]): Algorithm for the workbook protection
+
+    ### 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, pre_allocate: dict[str, int] = None, plain_data: list[list[str]] = None):
+        """
+        Initializes the Workbook with default settings and initializes Sheet1.
+
+        It initializes the workbook structure with Sheet1 as the default sheet,
+        sets default file properties, initializes current sheet and sheet list,
+        and initializes dictionaries for workbook and protection settings.
+
+        Args:
+            pre_allocate (dict[str, int], optional): A dictionary containing 'n_rows' and 'n_cols'
+                keys specifying the dimensions for pre-allocating data in Sheet1.
+            plain_data (list[list[str]], optional): A 2D list of strings representing initial data
+                to populate Sheet1.
+        """
+        self.workbook = {
+            'Sheet1': WorkSheet(pre_allocate=pre_allocate, plain_data=plain_data),
+        }
+        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.9/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