excel-dbapi 0.1.0__py3-none-any.whl

excel_dbapi/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

excel_dbapi/connection.py

@@ -0,0 +1,75 @@
+from io import BytesIO
+from pathlib import Path
+from typing import Optional, Protocol, Union
+
+from openpyxl.workbook.workbook import Workbook
+from openpyxl.worksheet.worksheet import Worksheet
+
+from .engines.openpyxl_engine import OpenPyXLEngine
+from .exceptions import OperationalError
+from .remote import fetch_remote_file
+
+
+class ExcelEngine(Protocol):
+    """Protocol for Excel processing engines."""
+
+    def load_workbook(self, file_path: Union[str, BytesIO]) -> "ExcelEngine": ...
+    def close(self) -> None: ...
+    def get_sheet(self, sheet_name: str) -> Worksheet: ...
+    @property
+    def workbook(self) -> Workbook: ...
+
+
+class ExcelConnection:
+    """DBAPI-compliant connection to an Excel file."""
+
+    def __init__(
+        self, file_path: Union[str, Path], engine: Optional[ExcelEngine] = None
+    ) -> None:
+        """Initialize with file path and optional engine."""
+        self.file_path = Path(file_path)
+        self.engine: ExcelEngine = engine if engine else OpenPyXLEngine()
+        self._connected = False
+
+    def connect(self) -> "ExcelConnection":
+        """Establish connection to the Excel file."""
+        try:
+            if str(self.file_path).startswith(("http://", "https://")):
+                file_data = fetch_remote_file(self.file_path)
+                self.engine.load_workbook(file_data)
+            else:
+                self.engine.load_workbook(str(self.file_path))
+            self._connected = True
+            return self
+        except Exception as e:
+            raise OperationalError(f"Failed to connect to {self.file_path}: {e}")
+
+    def close(self) -> None:
+        """Close the connection."""
+        if self._connected:
+            self.engine.close()
+            self._connected = False
+
+    def commit(self) -> None:
+        """Commit changes (not applicable for read-only Excel, placeholder)."""
+        pass
+
+    def rollback(self) -> None:
+        """Rollback changes (not applicable, placeholder)."""
+        pass
+
+    def cursor(self):  # 타입 주석 제거 및 임포트 지연
+        """Return a new cursor object."""
+        from .cursor import ExcelCursor  # 메서드 안에서 임포트
+
+        if not self._connected:
+            raise OperationalError("Connection is not established.")
+        return ExcelCursor(self)
+
+    def __enter__(self) -> "ExcelConnection":
+        """Context manager entry."""
+        return self.connect()
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.close()

excel_dbapi/cursor.py

@@ -0,0 +1,75 @@
+from typing import Dict, List, Optional, Union
+
+from .connection import ExcelConnection
+from .exceptions import OperationalError, ProgrammingError
+from .query import QueryEngine
+from .table import ExcelTable
+
+
+class ExcelCursor:
+    """DBAPI-compliant cursor for executing queries on Excel tables."""
+
+    def __init__(self, connection: ExcelConnection) -> None:
+        """Initialize with a connection."""
+        self.connection = connection
+        self.table: Optional[ExcelTable] = None
+        self._results: Optional[List[Dict[str, Union[str, int, float]]]] = None
+        self._rowcount = -1
+
+    def execute(self, query: str, params: Optional[tuple] = None) -> None:
+        """Execute a SQL-like query."""
+        if not query.strip().upper().startswith("SELECT"):
+            raise ProgrammingError("Only SELECT queries are supported.")
+
+        if "FROM" not in query.upper():
+            raise ProgrammingError("Query must include FROM clause.")
+
+        table_name = query.split("FROM", 1)[1].strip().split()[0]
+        self.table = ExcelTable(self.connection, table_name)
+
+        with self.table:
+            qe = QueryEngine(self.table)
+            if "*" in query:
+                self._results = qe.select()
+            else:
+                columns = [
+                    col.strip()
+                    for col in query.split("SELECT")[1].split("FROM")[0].split(",")
+                ]
+                self._results = qe.select(columns=columns)
+            self._rowcount = len(self._results or [])
+
+    def fetchone(self) -> Optional[Dict[str, Union[str, int, float]]]:
+        """Fetch the next row of the query result."""
+        if self._results is None:
+            raise OperationalError("No query executed.")
+        if not self._results:
+            return None
+        return self._results.pop(0)
+
+    def fetchall(self) -> List[Dict[str, Union[str, int, float]]]:
+        """Fetch all rows of the query result."""
+        if self._results is None:
+            raise OperationalError("No query executed.")
+        results = self._results or []
+        self._results = []
+        return results
+
+    def fetchmany(self, size: int = 1) -> List[Dict[str, Union[str, int, float]]]:
+        """Fetch a specified number of rows."""
+        if self._results is None:
+            raise OperationalError("No query executed.")
+        results = self._results[:size]
+        self._results = self._results[size:]
+        return results
+
+    @property
+    def rowcount(self) -> int:
+        """Return the number of rows affected."""
+        return self._rowcount
+
+    def close(self) -> None:
+        """Close the cursor."""
+        self.table = None
+        self._results = None
+        self._rowcount = -1

excel_dbapi/engines/openpyxl_engine.py

@@ -0,0 +1,46 @@
+from io import BytesIO
+from typing import Optional, Union
+
+import openpyxl
+from openpyxl.workbook.workbook import Workbook
+from openpyxl.worksheet.worksheet import Worksheet
+
+from ..exceptions import OperationalError
+
+
+class OpenPyXLEngine:
+    """Excel processing engine using openpyxl."""
+
+    def __init__(self) -> None:
+        """Initialize the engine."""
+        self._workbook: Optional[Workbook] = None
+
+    def load_workbook(self, file_path: Union[str, BytesIO]) -> "OpenPyXLEngine":
+        """Load the workbook from a file path or BytesIO."""
+        try:
+            self._workbook = openpyxl.load_workbook(file_path)
+            return self
+        except Exception as e:
+            raise OperationalError(f"Failed to load workbook: {e}")
+
+    def close(self) -> None:
+        """Close the workbook."""
+        if self._workbook:
+            self._workbook.close()
+            self._workbook = None
+
+    def get_sheet(self, sheet_name: str) -> Worksheet:
+        """Get a specific sheet by name."""
+        if not self._workbook:
+            raise OperationalError("Workbook not loaded.")
+        try:
+            return self._workbook[sheet_name]
+        except KeyError:
+            raise OperationalError(f"Sheet '{sheet_name}' not found.")
+
+    @property
+    def workbook(self) -> Workbook:
+        """Property to access the loaded workbook."""
+        if not self._workbook:
+            raise OperationalError("Workbook not loaded.")
+        return self._workbook

excel_dbapi/exceptions.py

@@ -0,0 +1,34 @@
+class Error(Exception):
+    """Base class for all DBAPI exceptions."""
+
+    pass
+
+
+class InterfaceError(Error):
+    """Raised for errors related to the database interface."""
+
+    pass
+
+
+class DatabaseError(Error):
+    """Raised for errors related to the database itself."""
+
+    pass
+
+
+class TableError(Exception):
+    """Raised when a table-related error occurs."""
+
+    pass
+
+
+class OperationalError(DatabaseError):
+    """Raised for operational errors (e.g., connection issues)."""
+
+    pass
+
+
+class ProgrammingError(DatabaseError):
+    """Raised for programming errors (e.g., invalid SQL)."""
+
+    pass

excel_dbapi/query.py

@@ -0,0 +1,54 @@
+from typing import Callable, Dict, List, Optional, Union
+
+from .exceptions import OperationalError
+from .table import ExcelTable
+
+
+class QueryEngine:
+    """Engine for executing SQL-like queries on Excel tables."""
+
+    def __init__(self, table: ExcelTable) -> None:
+        """Initialize with a table instance."""
+        self.table = table
+
+    def select(
+        self,
+        columns: Optional[List[str]] = None,
+        where: Optional[Callable[[List[Union[str, int, float]]], bool]] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Union[str, int, float]]]:
+        """Execute a SELECT query with optional columns, where clause, and limit."""
+        if not self.table.sheet:
+            raise OperationalError("Table must be opened before querying.")
+
+        headers = [cell.value for cell in self.table.sheet[1]]
+        if not headers or not all(isinstance(h, str) for h in headers):
+            raise OperationalError("First row must contain valid string headers.")
+
+        if columns:
+            col_indices = [headers.index(col) for col in columns if col in headers]
+        else:
+            col_indices = list(range(len(headers)))
+
+        rows = self.table.fetch_all()[1:]
+        result: List[Dict[str, Union[str, int, float]]] = []
+
+        for row in rows:
+            if where is None or where(row):
+                row_dict = {headers[i]: row[i] for i in col_indices}
+                result.append(row_dict)
+                if limit and len(result) >= limit:
+                    break
+
+        return result
+
+
+def query(
+    table: ExcelTable,
+    columns: Optional[List[str]] = None,
+    where: Optional[Callable[[List[Union[str, int, float]]], bool]] = None,
+    limit: Optional[int] = None,
+) -> List[Dict[str, Union[str, int, float]]]:
+    """Convenience function to execute a query."""
+    engine = QueryEngine(table)
+    return engine.select(columns=columns, where=where, limit=limit)

excel_dbapi/remote.py

@@ -0,0 +1,17 @@
+from io import BytesIO
+from pathlib import Path
+from typing import Union
+
+import requests
+
+from .exceptions import OperationalError  # ConnectionError -> OperationalError
+
+
+def fetch_remote_file(url: Union[str, Path]) -> BytesIO:
+    """Fetch a remote file and return it as BytesIO."""
+    try:
+        response = requests.get(str(url), timeout=10)
+        response.raise_for_status()
+        return BytesIO(response.content)
+    except requests.RequestException as e:
+        raise OperationalError(f"Failed to fetch remote file {url}: {e}")

excel_dbapi/table.py

@@ -0,0 +1,53 @@
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .connection import ExcelConnection
+from .exceptions import OperationalError
+
+
+class ExcelTable:
+    """Class to treat an Excel sheet as a table."""
+
+    def __init__(self, connection: ExcelConnection, sheet_name: str) -> None:
+        """Initialize with a connection and sheet name."""
+        self.connection = connection
+        self.sheet_name = sheet_name
+        self.sheet: Optional[Any] = None
+
+    def open(self) -> "ExcelTable":
+        """Open the sheet and prepare it as a table."""
+        try:
+            self.sheet = self.connection.engine.get_sheet(self.sheet_name)
+            return self
+        except Exception as e:
+            raise OperationalError(f"Failed to open sheet '{self.sheet_name}': {e}")
+
+    def fetch_all(self) -> List[List[Union[str, int, float]]]:
+        """Fetch all data from the sheet."""
+        if not self.sheet:
+            raise OperationalError("Table is not opened.")
+        return [[cell.value for cell in row] for row in self.sheet.rows]
+
+    def fetch_row(self, row_num: int) -> List[Union[str, int, float]]:
+        """Fetch a specific row by number (1-based index)."""
+        if not self.sheet:
+            raise OperationalError("Table is not opened.")
+        return [cell.value for cell in self.sheet[row_num]]
+
+    def query(
+        self,
+        columns: Optional[List[str]] = None,
+        where: Optional[Callable[[List[Union[str, int, float]]], bool]] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Union[str, int, float]]]:
+        """Execute a query on the table."""
+        from .query import query  # lazy import to avoid circular dependency
+
+        return query(self, columns=columns, where=where, limit=limit)
+
+    def __enter__(self) -> "ExcelTable":
+        """Context manager entry."""
+        return self.open()
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.sheet = None

excel_dbapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: excel-dbapi
+Version: 0.1.0
+Summary: A DBAPI-like interface for Excel files with extensible engines
+Author-email: Yeongseon Choe <yeongseon.choe@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: bandit<2.0.0,>=1.7.0; extra == 'dev'
+Requires-Dist: black<26.0.0,>=25.1.0; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: isort<7.0.0,>=6.0.1; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.15.0; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=8.3.5; extra == 'dev'
+Requires-Dist: ruff<0.12.0,>=0.11.2; extra == 'dev'
+Requires-Dist: types-requests<3.0.0,>=2.28.0; extra == 'dev'
+Requires-Dist: vulture<3.0,>=2.0; extra == 'dev'

excel_dbapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+excel_dbapi/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+excel_dbapi/connection.py,sha256=0Fr463-qho3nlBt_w36qzzGj14pMVsLE6tCObOB4Jwo,2531
+excel_dbapi/cursor.py,sha256=87jk2g8yC0iK80ZTyphGPOeHaWeYibagJCh1JaciC8M,2725
+excel_dbapi/exceptions.py,sha256=V3wX_8SqFfnvMAAeQELEB8veWFszXZEieBxkJf5CEmo,608
+excel_dbapi/query.py,sha256=UULdZqB1zbmlaXqR7pTRMNO_mnSb0T8_GpXOyItNBaE,1935
+excel_dbapi/remote.py,sha256=1Q2w_1eT8dVioSJPsUrgg-I5bd6UcIohp7qUtThwHJ8,543
+excel_dbapi/table.py,sha256=V1vBz66Mec5Na8-HBFGboyfN2gl3lvA3P8ew2LpKKJU,2000
+excel_dbapi/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+excel_dbapi/engines/openpyxl_engine.py,sha256=PCvAwg_Ai51viMLTjFGZEqe7-KkS6GzRPjCP-OXCrU0,1483
+excel_dbapi-0.1.0.dist-info/METADATA,sha256=CpPLVQ1meqfKj7wd0EZi9g8TcP2PJGHqSyhdubtotuE,811
+excel_dbapi-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+excel_dbapi-0.1.0.dist-info/licenses/LICENSE,sha256=gBTzk1NFKuyZKqa5-8leVY816k7POZUMpw2_PKl2MsY,1071
+excel_dbapi-0.1.0.dist-info/RECORD,,

excel_dbapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

excel_dbapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yeongseon Choe
+
+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.