python-calamine 0.3.2__cp312-cp312-win_amd64.whl

python_calamine/__init__.py

@@ -0,0 +1,29 @@
+from ._python_calamine import (
+    CalamineError,
+    CalamineSheet,
+    CalamineWorkbook,
+    PasswordError,
+    SheetMetadata,
+    SheetTypeEnum,
+    SheetVisibleEnum,
+    WorkbookClosed,
+    WorksheetNotFound,
+    XmlError,
+    ZipError,
+    load_workbook,
+)
+
+__all__ = (
+    "CalamineError",
+    "CalamineSheet",
+    "CalamineWorkbook",
+    "PasswordError",
+    "SheetMetadata",
+    "SheetTypeEnum",
+    "SheetVisibleEnum",
+    "WorksheetNotFound",
+    "XmlError",
+    "ZipError",
+    "WorkbookClosed",
+    "load_workbook",
+)

python_calamine/_python_calamine.pyi

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import contextlib
+import datetime
+import enum
+import os
+import types
+import typing
+
+@typing.type_check_only
+class ReadBuffer(typing.Protocol):
+    def seek(self, __offset: int, __whence: int = ...) -> int: ...
+    def read(self, __size: int = ...) -> bytes | None: ...
+
+@typing.final
+class SheetTypeEnum(enum.Enum):
+    WorkSheet = ...
+    DialogSheet = ...
+    MacroSheet = ...
+    ChartSheet = ...
+    Vba = ...
+
+@typing.final
+class SheetVisibleEnum(enum.Enum):
+    Visible = ...
+    Hidden = ...
+    VeryHidden = ...
+
+@typing.final
+class SheetMetadata:
+    name: str
+    typ: SheetTypeEnum
+    visible: SheetVisibleEnum
+
+    def __init__(
+        self, name: str, typ: SheetTypeEnum, visible: SheetVisibleEnum
+    ) -> None: ...
+
+@typing.final
+class CalamineSheet:
+    name: str
+    @property
+    def height(self) -> int: ...
+    @property
+    def width(self) -> int: ...
+    @property
+    def total_height(self) -> int: ...
+    @property
+    def total_width(self) -> int: ...
+    @property
+    def start(self) -> tuple[int, int] | None: ...
+    @property
+    def end(self) -> tuple[int, int] | None: ...
+    def to_python(
+        self, skip_empty_area: bool = True, nrows: int | None = None
+    ) -> list[
+        list[
+            int
+            | float
+            | str
+            | bool
+            | datetime.time
+            | datetime.date
+            | datetime.datetime
+            | datetime.timedelta
+        ]
+    ]:
+        """Retunrning data from sheet as list of lists.
+
+        Args:
+            skip_empty_area (bool):
+                By default, calamine skips empty rows/cols before data.
+                For suppress this behaviour, set `skip_empty_area` to `False`.
+        """
+
+    def iter_rows(
+        self,
+    ) -> typing.Iterator[
+        list[
+            int
+            | float
+            | str
+            | bool
+            | datetime.time
+            | datetime.date
+            | datetime.datetime
+            | datetime.timedelta
+        ]
+    ]:
+        """Retunrning data from sheet as iterator of lists."""
+
+@typing.final
+class CalamineWorkbook(contextlib.AbstractContextManager):
+    path: str | None
+    sheet_names: list[str]
+    sheets_metadata: list[SheetMetadata]
+    @classmethod
+    def from_object(
+        cls, path_or_filelike: str | os.PathLike | ReadBuffer
+    ) -> "CalamineWorkbook":
+        """Determining type of pyobject and reading from it.
+
+        Args:
+            path_or_filelike (str | os.PathLike | ReadBuffer): path to file or IO (must imlpement read/seek methods).
+        """
+
+    @classmethod
+    def from_path(cls, path: str | os.PathLike) -> "CalamineWorkbook":
+        """Reading file from path.
+
+        Args:
+            path (str | os.PathLike): path to file.
+        """
+
+    @classmethod
+    def from_filelike(cls, filelike: ReadBuffer) -> "CalamineWorkbook":
+        """Reading file from IO.
+
+        Args:
+            filelike : IO (must imlpement read/seek methods).
+        """
+
+    def close(self) -> None:
+        """Close the workbook.
+
+        Drop internal rust structure from workbook (and close the file under the hood).
+        `get_sheet_by_name`/`get_sheet_by_index` will raise WorkbookClosed after calling that method.
+
+        Raises:
+            WorkbookClosed: If workbook already closed.
+        """
+
+    def __enter__(self) -> "CalamineWorkbook": ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> None: ...
+    def get_sheet_by_name(self, name: str) -> CalamineSheet:
+        """Get worksheet by name.
+
+        Args:
+            name(str): name of worksheet
+
+        Returns:
+            CalamineSheet
+
+        Raises:
+            WorkbookClosed: If workbook already closed.
+            WorksheetNotFound: If worksheet not found in workbook.
+        """
+
+    def get_sheet_by_index(self, index: int) -> CalamineSheet:
+        """Get worksheet by index.
+
+        Args:
+            index(int): index of worksheet
+
+        Returns:
+            CalamineSheet
+
+        Raises:
+            WorkbookClosed: If workbook already closed.
+            WorksheetNotFound: If worksheet not found in workbook.
+        """
+
+class CalamineError(Exception): ...
+class PasswordError(CalamineError): ...
+class WorksheetNotFound(CalamineError): ...
+class XmlError(CalamineError): ...
+class ZipError(CalamineError): ...
+class WorkbookClosed(CalamineError): ...
+
+def load_workbook(
+    path_or_filelike: str | os.PathLike | ReadBuffer,
+) -> CalamineWorkbook:
+    """Determining type of pyobject and reading from it.
+
+    Args:
+        path_or_filelike (str | os.PathLike | ReadBuffer): path to file or IO (must imlpement read/seek methods).
+    """

python_calamine/pandas.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from importlib.metadata import version
+from typing import TYPE_CHECKING, Union, cast
+
+import pandas as pd
+from packaging.version import Version, parse
+from pandas._typing import Scalar
+from pandas.compat._optional import import_optional_dependency
+from pandas.core.shared_docs import _shared_docs
+from pandas.io.excel import ExcelFile
+from pandas.io.excel._base import (  # type:ignore[attr-defined] # missing in pandas-stubs
+    BaseExcelReader,
+)
+from pandas.util._decorators import (  # type:ignore[attr-defined] # missing in pandas-stubs
+    doc,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import FilePath, ReadBuffer, StorageOptions
+    from python_calamine import CalamineSheet, CalamineWorkbook
+
+_CellValueT = Union[int, float, str, bool, time, date, datetime, timedelta]
+
+
+PANDAS_VERSION = parse(version("pandas"))
+
+
+class CalamineExcelReader(BaseExcelReader):
+    book: CalamineWorkbook
+
+    @doc(storage_options=_shared_docs["storage_options"])
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Reader using calamine engine (xlsx/xls/xlsb/ods).
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path to be parsed or
+            an open readable stream.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        import_optional_dependency("python_calamine")
+        if PANDAS_VERSION >= Version("2.2.0"):
+            raise ValueError("Pandas >= 2.2.0 has builtin support of calamine")
+        elif PANDAS_VERSION >= Version("2.1.0"):
+            super().__init__(
+                filepath_or_buffer,
+                storage_options=storage_options,
+                engine_kwargs=engine_kwargs,
+            )
+        elif PANDAS_VERSION >= Version("2.0.0"):
+            super().__init__(
+                filepath_or_buffer,
+                storage_options=storage_options,
+            )
+        else:
+            raise ValueError("Pandas >= 2 is only supported")
+
+    @property
+    def _workbook_class(self) -> type[CalamineWorkbook]:
+        from python_calamine import CalamineWorkbook
+
+        return CalamineWorkbook
+
+    def load_workbook(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        engine_kwargs: dict | None = None,
+    ) -> CalamineWorkbook:
+        from python_calamine import load_workbook
+
+        return load_workbook(filepath_or_buffer, **(engine_kwargs or {}))
+
+    @property
+    def sheet_names(self) -> list[str]:
+        from python_calamine import SheetTypeEnum
+
+        return [
+            sheet.name
+            for sheet in self.book.sheets_metadata
+            if sheet.typ == SheetTypeEnum.WorkSheet
+        ]
+
+    def get_sheet_by_name(self, name: str) -> CalamineSheet:
+        self.raise_if_bad_sheet_by_name(name)
+        return self.book.get_sheet_by_name(name)
+
+    def get_sheet_by_index(self, index: int) -> CalamineSheet:
+        self.raise_if_bad_sheet_by_index(index)
+        return self.book.get_sheet_by_index(index)
+
+    def get_sheet_data(
+        self, sheet: CalamineSheet, file_rows_needed: int | None = None
+    ) -> list[list[Scalar]]:
+        def _convert_cell(value: _CellValueT) -> Scalar:
+            if isinstance(value, float):
+                val = int(value)
+                if val == value:
+                    return val
+                else:
+                    return value
+            elif isinstance(value, date):
+                return pd.Timestamp(value)
+            elif isinstance(value, timedelta):
+                return pd.Timedelta(value)
+            elif isinstance(value, time):
+                # cast needed here because Scalar doesn't include datetime.time
+                return cast(Scalar, value)
+
+            return value
+
+        rows: list[list[_CellValueT]] = sheet.to_python(skip_empty_area=False)
+        data: list[list[Scalar]] = []
+
+        for row in rows:
+            data.append([_convert_cell(cell) for cell in row])
+            if file_rows_needed is not None and len(data) >= file_rows_needed:
+                break
+
+        return data
+
+
+def pandas_monkeypatch() -> None:
+    ExcelFile._engines = {  # type:ignore[attr-defined] # missing in pandas-stubs
+        "calamine": CalamineExcelReader,
+        **ExcelFile._engines,  # type:ignore[attr-defined] # missing in pandas-stubs
+    }

python_calamine-0.3.2.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: python-calamine
+Version: 0.3.2
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: packaging>=23.1
+Requires-Dist: maturin~=1.0 ; extra == 'dev'
+Requires-Dist: pre-commit~=3.0 ; extra == 'dev'
+Requires-Dist: pytest~=8.0 ; extra == 'dev'
+Requires-Dist: pandas[excel]~=2.0 ; extra == 'dev'
+Requires-Dist: numpy~=1.0 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Python binding for Rust's library for reading excel and odf file - calamine
+Home-Page: https://github.com/dimastbk/python-calamine
+Author: Dmitriy <dimastbk@proton.me>
+Author-email: Dmitriy <dimastbk@proton.me>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Source Code, https://github.com/dimastbk/python-calamine
+
+# python-calamine
+[![PyPI - Version](https://img.shields.io/pypi/v/python-calamine)](https://pypi.org/project/python-calamine/)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/python-calamine.svg)](https://anaconda.org/conda-forge/python-calamine)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdimastbk%2Fpython-calamine%2Fmaster%2Fpyproject.toml)
+
+
+Python binding for beautiful Rust's library for reading excel and odf file - [calamine](https://github.com/tafia/calamine).
+
+### Is used
+* [calamine](https://github.com/tafia/calamine)
+* [pyo3](https://github.com/PyO3/pyo3)
+* [maturin](https://github.com/PyO3/maturin)
+
+### Installation
+Pypi:
+```
+pip install python-calamine
+```
+Conda:
+```
+conda install -c conda-forge python-calamine
+```
+
+### Example
+```python
+from python_calamine import CalamineWorkbook
+
+workbook = CalamineWorkbook.from_path("file.xlsx")
+workbook.sheet_names
+# ["Sheet1", "Sheet2"]
+
+workbook.get_sheet_by_name("Sheet1").to_python()
+# [
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ]
+```
+
+By default, calamine skips empty rows/cols before data. For suppress this behaviour, set `skip_empty_area` to `False`.
+```python
+from python_calamine import CalamineWorkbook
+
+workbook = CalamineWorkbook.from_path("file.xlsx").get_sheet_by_name("Sheet1").to_python(skip_empty_area=False)
+# [
+# [",  ",  ",  ",  ",  ",  "],
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ["1",  "2",  "3",  "4",  "5",  "6",  "7"],
+# ]
+```
+
+Also, you can use monkeypatch for pandas for use this library as engine in `read_excel()` (only pandas 2.0 and 2.1 are supported).
+Pandas 2.2 and above have built-in support of python-calamine.
+```python
+from pandas import read_excel
+from python_calamine.pandas import pandas_monkeypatch
+
+
+pandas_monkeypatch()
+
+read_excel("file.xlsx", engine="calamine")
+#            1   2   3   4   5   6   7
+# 0          1   2   3   4   5   6   7
+# 1          1   2   3   4   5   6   7
+```
+
+Also, you can find additional examples in [tests](https://github.com/dimastbk/python-calamine/blob/master/tests/test_base.py).
+
+### Development
+
+You'll need rust [installed](https://rustup.rs/).
+
+```python
+# clone this repo or your fork
+git clone git@github.com:dimastbk/python-calamine.git
+cd python-calamine
+# create a new virtual env
+python3 -m venv env
+source env/bin/activate
+# install dev dependencies and install python-calamine
+pip install -e .[dev]
+# lint code
+pre-commit run --all-files
+# test code
+pytest
+```
+

python_calamine-0.3.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+python_calamine-0.3.2.dist-info/METADATA,sha256=aOKwJP8J3tnHw8OEmtvCAuZW8MTsW_8UKBcDZP0CIag,3960
+python_calamine-0.3.2.dist-info/WHEEL,sha256=jABKVkLC9kJr8mi_er5jOqpiQUjARSLXDUIIxDqsS50,96
+python_calamine-0.3.2.dist-info/licenses/LICENSE,sha256=cYURXgSnjCTOT2jQ_McTGn-AhDycRqzJa11QzR38Sn4,1086
+python_calamine/pandas.py,sha256=QL-cy_9TMEsjb4bRCNB40tWGPPYlBmUBwEmKBFFuTGc,4734
+python_calamine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_calamine/_python_calamine.pyi,sha256=nPoUpA4zWdJvoBpX8SGmxVx8X1b8EjLYkbsD5ZyPOGA,4973
+python_calamine/__init__.py,sha256=evxSwIkpatTkygn2mRmWUYPslvdj08q_pNkayyyptfI,560
+python_calamine/_python_calamine.cp312-win_amd64.pyd,sha256=ICD7Zxg7JhiIyWXzKtuPjApSrl7F62jjd2AxR1LwBjE,1478656
+python_calamine-0.3.2.dist-info/RECORD,,

python_calamine-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp312-cp312-win_amd64

python_calamine-0.3.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 dimastbk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.