excel-dbapi 0.1.4__tar.gz → 2.0.0__tar.gz

excel_dbapi-2.0.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: excel-dbapi
+Version: 2.0.0
+Summary: PEP 249 compliant DB-API driver for Excel files
+Author-email: Yeongseon Choe <yeongseon.choe@gmail.com>
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: openpyxl<4.0.0,>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.5; extra == "dev"
+Requires-Dist: pytest-cov<5.0.0,>=4.1; extra == "dev"
+Requires-Dist: black<26.0.0,>=25.1.0; extra == "dev"
+Requires-Dist: isort<7.0.0,>=6.0.1; extra == "dev"
+Requires-Dist: ruff<0.12.0,>=0.11.2; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.15.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: bandit<2.0.0,>=1.7.0; extra == "dev"
+Requires-Dist: vulture<3.0,>=2.0; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: types-requests<3.0.0,>=2.28.0; extra == "dev"
+Dynamic: license-file

excel_dbapi-2.0.0/README.md

@@ -0,0 +1,92 @@
+
+# excel-dbapi
+
+![CI](https://github.com/your-username/excel-dbapi/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/your-username/excel-dbapi/branch/main/graph/badge.svg)](https://codecov.io/gh/your-username/excel-dbapi)
+
+A lightweight, Python DB-API 2.0 compliant connector for Excel files.
+
+---
+
+## Features
+
+- Python DB-API 2.0 compliant interface
+- Query Excel files using SQL syntax
+- Supports SELECT (INSERT, UPDATE, DELETE planned)
+- Sheet-to-Table mapping
+- Pandas & Openpyxl engine selector
+- Transaction simulation (planned)
+- SQLAlchemy Dialect integration (planned)
+
+---
+
+## Installation
+
+```bash
+pip install excel-dbapi
+```
+
+See [CHANGELOG](CHANGELOG.md) for release history.
+
+---
+
+## Quick Start
+
+### Basic Usage (Local File)
+
+```python
+from excel_dbapi.connection import ExcelConnection
+
+# Using default engine (openpyxl)
+with ExcelConnection("path/to/sample.xlsx") as conn:
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM Sheet1")
+    print(cursor.fetchall())
+
+# Using pandas engine
+with ExcelConnection("path/to/sample.xlsx", engine="pandas") as conn:
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM Sheet1")
+    print(cursor.fetchall())
+```
+
+### Engine Options
+
+| Engine    | Description                  | Dependency  |
+|---------|------------------------------|--------------|
+| openpyxl (default) | Fast sheet access (read-only) | openpyxl   |
+| pandas  | DataFrame based operations   | pandas, openpyxl |
+
+You can explicitly specify the engine using:
+
+```python
+conn = ExcelConnection("sample.xlsx", engine="openpyxl")
+conn = ExcelConnection("sample.xlsx", engine="pandas")
+```
+
+---
+
+## Planned Features
+
+- Write operations (INSERT, UPDATE, DELETE)
+- DDL support (CREATE TABLE, DROP TABLE)
+- Transaction simulation
+- Advanced SQL condition support (WHERE, ORDER BY, LIMIT)
+- Remote file connection support
+- SQLAlchemy Dialect
+
+See [Project Roadmap](docs/ROADMAP.md) for details.
+
+---
+
+## Documentation
+
+- [Usage Guide](docs/USAGE.md)
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Project Roadmap](docs/ROADMAP.md)
+
+---
+
+## License
+
+MIT License

excel_dbapi-2.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "excel-dbapi"
+version = "2.0.0"
+description = "PEP 249 compliant DB-API driver for Excel files"
+requires-python = ">=3.9"
+dependencies = [
+    "pandas>=2.0.0,<3.0.0",
+    "openpyxl>=3.1.0,<4.0.0"
+]
+
+[[project.authors]]
+name = "Yeongseon Choe"
+email = "yeongseon.choe@gmail.com"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.5,<9.0.0",
+    "pytest-cov>=4.1,<5.0.0",
+    "black>=25.1.0,<26.0.0",
+    "isort>=6.0.1,<7.0.0",
+    "ruff>=0.11.2,<0.12.0",
+    "mypy>=1.15.0,<2.0.0",
+    "build",
+    "bandit>=1.7.0,<2.0.0",
+    "vulture>=2.0,<3.0",
+    "pre-commit",
+    "types-requests>=2.28.0,<3.0.0"
+]
+
+[tool.mypy]
+ignore_missing_imports = true
+strict = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

excel_dbapi-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

excel_dbapi-2.0.0/src/excel_dbapi/connection.py

@@ -0,0 +1,107 @@
+from typing import Optional, Type
+
+from .cursor import ExcelCursor
+from .engine import BaseEngine, OpenpyxlEngine, PandasEngine
+from .exceptions import InterfaceError, NotSupportedError
+
+
+def check_closed(func):
+    """Decorator to check if connection is closed before executing method."""
+
+    def wrapper(self, *args, **kwargs):
+        if self.closed:
+            raise InterfaceError("Connection is already closed")
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+class ExcelConnection:
+    """
+    ExcelConnection provides a PEP 249 compliant Connection interface
+    for reading and querying Excel files.
+    """
+
+    def __init__(self, file_path: str, engine: str = "openpyxl"):
+        """
+        Initialize the connection with the Excel file and selected engine.
+
+        Args:
+            file_path (str): Path to the Excel file.
+            engine (str): Engine type ('pandas' or 'openpyxl').
+        """
+        self.file_path: str = file_path
+        self.closed: bool = False
+
+        if engine == "pandas":
+            self.engine: BaseEngine = PandasEngine(file_path)
+        elif engine == "openpyxl":
+            self.engine: BaseEngine = OpenpyxlEngine(file_path)
+        else:
+            raise ValueError(f"Unsupported engine: {engine}")
+
+    @check_closed
+    def cursor(self) -> ExcelCursor:
+        """
+        Return a new Cursor object using the connection.
+
+        Returns:
+            ExcelCursor: A new cursor object.
+        """
+        return ExcelCursor(self.engine)
+
+    @check_closed
+    def commit(self) -> None:
+        """
+        Commit any pending transaction (Not supported for Excel).
+
+        Raises:
+            NotSupportedError: Always raised because transactions are not supported.
+        """
+        raise NotSupportedError("Transactions are not supported")
+
+    @check_closed
+    def rollback(self) -> None:
+        """
+        Roll back to the start of any pending transaction (Not supported for Excel).
+
+        Raises:
+            NotSupportedError: Always raised because transactions are not supported.
+        """
+        raise NotSupportedError("Transactions are not supported")
+
+    def close(self) -> None:
+        """
+        Close the connection.
+        """
+        self.closed = True
+
+    @property
+    def engine_name(self) -> str:
+        """
+        Return the name of the engine being used.
+        """
+        return self.engine.__class__.__name__
+
+    def __str__(self) -> str:
+        return f"<ExcelConnection file='{self.file_path}' engine='{self.engine_name}' closed={self.closed}>"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def __enter__(self) -> "ExcelConnection":
+        """
+        Enter the runtime context related to this object.
+        """
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb,
+    ) -> None:
+        """
+        Exit the runtime context and close the connection.
+        """
+        self.close()

excel_dbapi-2.0.0/src/excel_dbapi/cursor.py

@@ -0,0 +1,84 @@
+from typing import Any, Dict, List, Optional
+
+from .engine.executor import execute_query
+from .engine.parser import parse_sql
+from .exceptions import InterfaceError
+
+
+def check_closed(func):
+    """Decorator to check if cursor is closed before executing method."""
+
+    def wrapper(self, *args, **kwargs):
+        if self.closed:
+            raise InterfaceError("Cursor is already closed")
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+class ExcelCursor:
+    """
+    ExcelCursor provides a PEP 249 compliant Cursor interface
+    for executing SQL-like queries on Excel data.
+    """
+
+    def __init__(self, connection: Any):
+        """
+        Initialize the cursor with a connection.
+
+        Args:
+            connection (ExcelConnection): The parent connection object.
+        """
+        self.connection = connection
+        self.closed: bool = False
+        self._results: List[Dict[str, Any]] = []
+        self._index: int = 0
+
+    @check_closed
+    def execute(self, query: str, params: Optional[tuple] = None) -> "ExcelCursor":
+        """
+        Execute a SQL query.
+
+        Args:
+            query (str): The SQL query string.
+            params (Optional[tuple]): Parameters to bind to query placeholders.
+
+        Returns:
+            ExcelCursor: The cursor itself.
+        """
+        parsed = parse_sql(query, params)
+        self._results = execute_query(parsed, self.connection.data)
+        self._index = 0
+        return self
+
+    @check_closed
+    def fetchone(self) -> Optional[Dict[str, Any]]:
+        """
+        Fetch the next row of a query result.
+
+        Returns:
+            Optional[Dict[str, Any]]: The next row or None if no more rows.
+        """
+        if self._index >= len(self._results):
+            return None
+        result = self._results[self._index]
+        self._index += 1
+        return result
+
+    @check_closed
+    def fetchall(self) -> List[Dict[str, Any]]:
+        """
+        Fetch all remaining rows of a query result.
+
+        Returns:
+            List[Dict[str, Any]]: List of all remaining rows.
+        """
+        results = self._results[self._index :]
+        self._index = len(self._results)
+        return results
+
+    def close(self) -> None:
+        """
+        Close the cursor.
+        """
+        self.closed = True

excel_dbapi-2.0.0/src/excel_dbapi/engine/__init__.py

@@ -0,0 +1,5 @@
+from .base import BaseEngine
+from .openpyxl_engine import OpenpyxlEngine
+from .pandas_engine import PandasEngine
+
+__all__ = ["BaseEngine", "PandasEngine", "OpenpyxlEngine"]

excel_dbapi-2.0.0/src/excel_dbapi/engine/base.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+
+class BaseEngine(ABC):
+    @abstractmethod
+    def load(self) -> Dict[str, Any]:
+        """
+        Load data from the Excel file.
+        """
+        pass
+
+    @abstractmethod
+    def execute(self, query: str) -> List[Dict[str, Any]]:
+        """
+        Execute a query against the loaded data.
+        """
+        pass

excel_dbapi-2.0.0/src/excel_dbapi/engine/executor.py

@@ -0,0 +1,40 @@
+from typing import Any, Dict, List
+
+from pandas import DataFrame
+
+
+def execute_query(
+    parsed: Dict[str, Any], data: Dict[str, DataFrame]
+) -> List[Dict[str, Any]]:
+    """
+    Execute the parsed SQL query against the provided Excel data.
+
+    Args:
+        parsed (Dict[str, Any]): Parsed SQL query components.
+        data (Dict[str, DataFrame]): Excel sheet data as DataFrames.
+
+    Returns:
+        List[Dict[str, Any]]: Query result as list of dictionaries.
+
+    Raises:
+        ValueError: If the specified sheet (table) is not found.
+        NotImplementedError: For unsupported SQL actions.
+    """
+    table = parsed.get("table")
+    if table not in data:
+        raise ValueError(f"Sheet '{table}' not found in Excel")
+
+    if parsed["action"] == "SELECT":
+        df = data[table]
+        if parsed.get("where"):
+            try:
+                df = df.query(parsed["where"])
+            except Exception as e:
+                raise ValueError(f"Invalid WHERE condition: {parsed['where']}") from e
+        return df.to_dict(orient="records")
+
+    elif parsed["action"] == "INSERT":
+        raise NotImplementedError("INSERT is not yet implemented")
+
+    else:
+        raise NotImplementedError(f"Unsupported action: {parsed['action']}")

excel_dbapi-2.0.0/src/excel_dbapi/engine/openpyxl_engine.py

@@ -0,0 +1,39 @@
+from typing import Any, Dict, List
+
+from openpyxl import load_workbook
+
+from .base import BaseEngine
+
+
+class OpenpyxlEngine(BaseEngine):
+    def __init__(self, file_path: str):
+        """
+        Initialize OpenpyxlEngine with the given file path.
+        """
+        self.file_path = file_path
+        self.data = self.load()
+
+    def load(self) -> Dict[str, Any]:
+        """
+        Load all sheets using openpyxl.
+        """
+        wb = load_workbook(self.file_path, data_only=True)
+        return {sheet: wb[sheet] for sheet in wb.sheetnames}
+
+    def save(self) -> None:
+        """
+        Save is not implemented for OpenpyxlEngine.
+        """
+        raise NotImplementedError(
+            "Save operation is not implemented for OpenpyxlEngine."
+        )
+
+    def execute(self, query: str) -> List[Dict[str, Any]]:
+        """
+        Example execution: return all records from the first sheet.
+        """
+        sheet = list(self.data.keys())[0]
+        ws = self.data[sheet]
+        rows = list(ws.iter_rows(values_only=True))
+        headers = rows[0]
+        return [dict(zip(headers, row)) for row in rows[1:]]

excel_dbapi-2.0.0/src/excel_dbapi/engine/pandas_engine.py

@@ -0,0 +1,49 @@
+from typing import Any, Dict
+
+import pandas as pd
+from pandas import DataFrame
+
+from .base import BaseEngine
+
+
+class PandasEngine(BaseEngine):
+    """
+    PandasEngine uses pandas with openpyxl backend to load and query Excel files.
+    """
+
+    def __init__(self, file_path: str):
+        """
+        Initialize PandasEngine with the given file path.
+        """
+        self.file_path = file_path
+        self.data = self.load()
+
+    def load(self) -> Dict[str, DataFrame]:
+        """
+        Load all sheets as DataFrames using pandas with openpyxl engine.
+        """
+        try:
+            data = pd.read_excel(self.file_path, sheet_name=None, engine="openpyxl")
+            return data
+        except Exception as e:
+            raise IOError(f"Failed to load Excel file: {self.file_path}") from e
+
+    def save(self, file_path: str) -> None:
+        """
+        Save the current data back to an Excel file.
+        """
+        try:
+            with pd.ExcelWriter(file_path, engine="openpyxl") as writer:
+                for sheet_name, df in self.data.items():
+                    df.to_excel(writer, sheet_name=sheet_name, index=False)
+        except Exception as e:
+            raise IOError(f"Failed to save Excel file: {file_path}") from e
+
+    def execute(self, query: str) -> list[dict[str, Any]]:
+        """
+        Execute a query and return the result.
+
+        Currently, only SELECT * FROM [Sheet$] is supported as an example.
+        """
+        sheet = list(self.data.keys())[0]
+        return self.data[sheet].to_dict(orient="records")

excel_dbapi-2.0.0/src/excel_dbapi/engine/parser.py

@@ -0,0 +1,49 @@
+import re
+from typing import Any, Dict, Optional, Tuple
+
+
+def parse_sql(query: str, params: Optional[Tuple[Any, ...]] = None) -> Dict[str, Any]:
+    query = query.strip()
+
+    # Parameter binding
+    if params:
+        placeholders = re.findall(r"\?", query)
+        if len(placeholders) != len(params):
+            raise ValueError(
+                f"Expected {len(placeholders)} parameters, got {len(params)}"
+            )
+
+        for param in params:
+            if isinstance(param, str):
+                value = f"'{param}'"
+            else:
+                value = str(param)
+            query = query.replace("?", value, 1)
+
+    result: Dict[str, Any] = {}
+    lower_query = query.lower()
+
+    if lower_query.startswith("select"):
+        result["action"] = "SELECT"
+        table_match = re.search(r"from\s+\[?(\w+)\$?\]?", query, re.IGNORECASE)
+        result["table"] = table_match.group(1).lower() if table_match else None
+
+        where_match = re.search(r"where\s+(.+)", query, re.IGNORECASE)
+        if where_match:
+            condition = where_match.group(1).strip()
+            # SQL → pandas 변환
+            condition = re.sub(r"(?<![=!<>])=(?!=)", "==", condition)
+            result["where"] = condition
+        else:
+            result["where"] = None
+
+    elif lower_query.startswith("insert"):
+        result["action"] = "INSERT"
+        table_match = re.search(r"into\s+\[?(\w+)\$?\]?", query, re.IGNORECASE)
+        result["table"] = table_match.group(1).lower() if table_match else None
+
+    else:
+        raise NotImplementedError(f"Unsupported SQL: {query}")
+
+    result["query"] = query
+    return result

excel_dbapi-2.0.0/src/excel_dbapi/exceptions.py

@@ -0,0 +1,52 @@
+class Error(Exception):
+    """Base class for all database-related exceptions."""
+
+    pass
+
+
+class DatabaseError(Error):
+    """Exception for errors related to the database."""
+
+    pass
+
+
+class InterfaceError(Error):
+    """Exception for errors related to the database interface."""
+
+    pass
+
+
+class DataError(DatabaseError):
+    """Exception for errors due to problems with the processed data."""
+
+    pass
+
+
+class OperationalError(DatabaseError):
+    """Exception for errors related to the database's operation."""
+
+    pass
+
+
+class IntegrityError(DatabaseError):
+    """Exception for errors related to data integrity."""
+
+    pass
+
+
+class InternalError(DatabaseError):
+    """Exception for internal database errors."""
+
+    pass
+
+
+class ProgrammingError(DatabaseError):
+    """Exception for programming errors (SQL syntax, etc.)."""
+
+    pass
+
+
+class NotSupportedError(DatabaseError):
+    """Exception for unsupported features."""
+
+    pass

excel_dbapi-2.0.0/src/excel_dbapi.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: excel-dbapi
+Version: 2.0.0
+Summary: PEP 249 compliant DB-API driver for Excel files
+Author-email: Yeongseon Choe <yeongseon.choe@gmail.com>
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: openpyxl<4.0.0,>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.5; extra == "dev"
+Requires-Dist: pytest-cov<5.0.0,>=4.1; extra == "dev"
+Requires-Dist: black<26.0.0,>=25.1.0; extra == "dev"
+Requires-Dist: isort<7.0.0,>=6.0.1; extra == "dev"
+Requires-Dist: ruff<0.12.0,>=0.11.2; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.15.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: bandit<2.0.0,>=1.7.0; extra == "dev"
+Requires-Dist: vulture<3.0,>=2.0; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: types-requests<3.0.0,>=2.28.0; extra == "dev"
+Dynamic: license-file

excel_dbapi-2.0.0/src/excel_dbapi.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+pyproject.toml
+src/excel_dbapi/__init__.py
+src/excel_dbapi/connection.py
+src/excel_dbapi/cursor.py
+src/excel_dbapi/exceptions.py
+src/excel_dbapi.egg-info/PKG-INFO
+src/excel_dbapi.egg-info/SOURCES.txt
+src/excel_dbapi.egg-info/dependency_links.txt
+src/excel_dbapi.egg-info/requires.txt
+src/excel_dbapi.egg-info/top_level.txt
+src/excel_dbapi/engine/__init__.py
+src/excel_dbapi/engine/base.py
+src/excel_dbapi/engine/executor.py
+src/excel_dbapi/engine/openpyxl_engine.py
+src/excel_dbapi/engine/pandas_engine.py
+src/excel_dbapi/engine/parser.py
+tests/test_connection.py
+tests/test_cursor.py
+tests/test_engine.py
+tests/test_exceptions.py
+tests/test_executor.py
+tests/test_integration.py
+tests/test_parser.py

excel_dbapi-2.0.0/src/excel_dbapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

excel_dbapi-2.0.0/src/excel_dbapi.egg-info/requires.txt

@@ -0,0 +1,15 @@
+pandas<3.0.0,>=2.0.0
+openpyxl<4.0.0,>=3.1.0
+
+[dev]
+pytest<9.0.0,>=8.3.5
+pytest-cov<5.0.0,>=4.1
+black<26.0.0,>=25.1.0
+isort<7.0.0,>=6.0.1
+ruff<0.12.0,>=0.11.2
+mypy<2.0.0,>=1.15.0
+build
+bandit<2.0.0,>=1.7.0
+vulture<3.0,>=2.0
+pre-commit
+types-requests<3.0.0,>=2.28.0

excel_dbapi-2.0.0/src/excel_dbapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+excel_dbapi