sqlalchemy-excel 0.1.1__tar.gz

sqlalchemy_excel-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type check
+        run: |
+          mypy --strict src/
+
+      - name: Test
+        run: |
+          pytest -v --tb=short

sqlalchemy_excel-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sqlalchemy_excel-0.1.1/.gitignore

@@ -0,0 +1,37 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+*.xlsx
+!tests/fixtures/*.xlsx

sqlalchemy_excel-0.1.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-04-12)
+
+- Initial release
+- SQLAlchemy 2.0 dialect for Excel files
+- PEP 249 DB-API 2.0 driver via excel-dbapi
+- SQL support: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE
+- WHERE clause with AND/OR, comparison operators, IS NULL, IS NOT NULL
+- ORDER BY, LIMIT
+- Type mapping: TEXT, INTEGER, FLOAT, BOOLEAN, DATE, DATETIME
+- Reflection: get_table_names, get_columns, get_pk_constraint, has_table
+- ORM support with DeclarativeBase

sqlalchemy_excel-0.1.1/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.

sqlalchemy_excel-0.1.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-excel
+Version: 0.1.1
+Summary: SQLAlchemy dialect for Excel files — use Excel as a database
+Project-URL: Homepage, https://github.com/yeongseon/sqlalchemy-excel
+Project-URL: Repository, https://github.com/yeongseon/sqlalchemy-excel
+Project-URL: Issues, https://github.com/yeongseon/sqlalchemy-excel/issues
+Author: Yeongseon Choe
+License: MIT
+License-File: LICENSE
+Keywords: database,dialect,excel,openpyxl,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: excel-dbapi>=0.1.1
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sqlalchemy-excel
+
+SQLAlchemy dialect for Excel files — use Excel as a database.
+
+```python
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.orm import DeclarativeBase, Session, Mapped, mapped_column
+
+engine = create_engine("excel:///data.xlsx")
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "Sheet1"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column()
+
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add(User(id=1, name="Alice"))
+    session.commit()
+
+with Session(engine) as session:
+    users = session.query(User).all()
+```
+
+## Installation
+
+```bash
+pip install sqlalchemy-excel
+```
+
+## URL Format
+
+```python
+# Relative path
+engine = create_engine("excel:///data.xlsx")
+
+# Absolute path (note four slashes)
+engine = create_engine("excel:////home/user/data.xlsx")
+```
+
+## Features
+
+- Full SQLAlchemy 2.0 dialect
+- PEP 249 DB-API 2.0 compliant driver ([excel-dbapi](https://github.com/yeongseon/excel-dbapi))
+- SELECT with WHERE, ORDER BY, LIMIT
+- INSERT, UPDATE, DELETE
+- CREATE TABLE / DROP TABLE
+- ORM support with `DeclarativeBase`
+- Type mapping: String, Integer, Float, Boolean, Date, DateTime
+
+## Limitations
+
+- No JOIN, GROUP BY, HAVING, DISTINCT, OFFSET
+- No subqueries, CTEs, or aggregate functions
+- No ALTER TABLE, foreign keys, or indexes
+- Single-table operations only
+
+## License
+
+MIT

sqlalchemy_excel-0.1.1/README.md

@@ -0,0 +1,64 @@
+# sqlalchemy-excel
+
+SQLAlchemy dialect for Excel files — use Excel as a database.
+
+```python
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.orm import DeclarativeBase, Session, Mapped, mapped_column
+
+engine = create_engine("excel:///data.xlsx")
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "Sheet1"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column()
+
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add(User(id=1, name="Alice"))
+    session.commit()
+
+with Session(engine) as session:
+    users = session.query(User).all()
+```
+
+## Installation
+
+```bash
+pip install sqlalchemy-excel
+```
+
+## URL Format
+
+```python
+# Relative path
+engine = create_engine("excel:///data.xlsx")
+
+# Absolute path (note four slashes)
+engine = create_engine("excel:////home/user/data.xlsx")
+```
+
+## Features
+
+- Full SQLAlchemy 2.0 dialect
+- PEP 249 DB-API 2.0 compliant driver ([excel-dbapi](https://github.com/yeongseon/excel-dbapi))
+- SELECT with WHERE, ORDER BY, LIMIT
+- INSERT, UPDATE, DELETE
+- CREATE TABLE / DROP TABLE
+- ORM support with `DeclarativeBase`
+- Type mapping: String, Integer, Float, Boolean, Date, DateTime
+
+## Limitations
+
+- No JOIN, GROUP BY, HAVING, DISTINCT, OFFSET
+- No subqueries, CTEs, or aggregate functions
+- No ALTER TABLE, foreign keys, or indexes
+- Single-table operations only
+
+## License
+
+MIT

sqlalchemy_excel-0.1.1/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlalchemy-excel"
+version = "0.1.1"
+description = "SQLAlchemy dialect for Excel files — use Excel as a database"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Yeongseon Choe"},
+]
+keywords = ["sqlalchemy", "excel", "dialect", "database", "openpyxl"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "sqlalchemy>=2.0",
+    "excel-dbapi>=0.1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.entry-points."sqlalchemy.dialects"]
+excel = "sqlalchemy_excel.dialect:ExcelDialect"
+
+[project.urls]
+Homepage = "https://github.com/yeongseon/sqlalchemy-excel"
+Repository = "https://github.com/yeongseon/sqlalchemy-excel"
+Issues = "https://github.com/yeongseon/sqlalchemy-excel/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqlalchemy_excel"]
+
+[tool.ruff]
+target-version = "py310"
+src = ["src"]
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "TCH",  # flake8-type-checking
+    "RUF",  # ruff-specific
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/sqlalchemy_excel/types.py" = ["N802"]  # SQLAlchemy visit_TYPE convention
+"src/sqlalchemy_excel/compiler.py" = ["RUF005"]  # Match SQLAlchemy's tuple concat pattern
+
+[tool.ruff.lint.isort]
+known-first-party = ["sqlalchemy_excel"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "excel_dbapi.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["sqlalchemy_excel"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__",
+    "@overload",
+]

sqlalchemy_excel-0.1.1/src/sqlalchemy_excel/__init__.py

@@ -0,0 +1,12 @@
+"""sqlalchemy-excel — SQLAlchemy dialect for Excel files."""
+
+from __future__ import annotations
+
+from .dialect import ExcelDialect
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "ExcelDialect",
+    "__version__",
+]

sqlalchemy_excel-0.1.1/src/sqlalchemy_excel/compiler.py

@@ -0,0 +1,159 @@
+"""SQL compiler for the Excel dialect.
+
+Compiles SQLAlchemy expression trees into the SQL subset that
+excel-dbapi's parser understands:
+
+Supported:
+    SELECT columns FROM table [WHERE ...] [ORDER BY col [ASC|DESC]] [LIMIT n]
+    INSERT INTO table (cols) VALUES (vals)
+    UPDATE table SET col=val [WHERE ...]
+    DELETE FROM table [WHERE ...]
+
+Rejected (raises CompileError):
+    JOIN, GROUP BY, HAVING, DISTINCT, OFFSET, subqueries,
+    CTEs, aggregate functions, window functions, RETURNING
+
+excel-dbapi's parser uses unquoted, unprefixed column names:
+    SELECT id, name FROM users          (correct)
+    SELECT users.id, users.name FROM users  (WRONG — parser rejects)
+
+So we override the identifier preparer to never use table prefixes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from sqlalchemy import exc
+from sqlalchemy.sql import compiler, elements
+
+
+class ExcelIdentifierPreparer(compiler.IdentifierPreparer):
+    """Identifier preparer that never quotes identifiers.
+
+    excel-dbapi's parser expects bare column names without quotes
+    or table prefixes.
+    """
+
+    reserved_words: ClassVar[set[str]] = set()
+
+    def __init__(self, dialect: Any) -> None:
+        super().__init__(dialect, initial_quote="", final_quote="")
+
+    def quote_identifier(self, value: str) -> str:
+        return value
+
+    def quote(self, ident: str, force: Any = None) -> str:
+        return ident
+
+
+class ExcelCompiler(compiler.SQLCompiler):
+    """Compiles SQLAlchemy SQL expressions for excel-dbapi."""
+
+    def visit_column(
+        self,
+        column: Any,
+        add_to_result_map: Any = None,
+        include_table: bool = True,
+        **kw: Any,
+    ) -> str:
+        """Override to never include table prefix in column references.
+
+        excel-dbapi expects: SELECT id, name FROM users
+        Not: SELECT users.id, users.name FROM users
+        """
+        # Force include_table=False to avoid table.column notation
+        return super().visit_column(
+            column,
+            add_to_result_map=add_to_result_map,
+            include_table=False,
+            **kw,
+        )
+
+    def visit_label(
+        self,
+        label: Any,
+        add_to_result_map: Any = None,
+        within_label_clause: bool = False,
+        within_columns_clause: bool = False,
+        render_label_as_label: Any = None,
+        result_map_targets: Any = (),
+        **kw: Any,
+    ) -> str:
+        """Override to never emit AS <label> in SELECT columns.
+
+        excel-dbapi's parser does not understand column aliases.
+        We still register the result map so SQLAlchemy can map
+        result columns back to ORM attributes by position.
+        """
+        render_label_with_as = within_columns_clause and not within_label_clause
+
+        if render_label_with_as:
+            # Compute the label name for the result map
+            if isinstance(label.name, elements._truncated_label):
+                labelname = self._truncated_identifier("colident", label.name)
+            else:
+                labelname = label.name
+
+            if add_to_result_map is not None:
+                add_to_result_map(
+                    labelname,
+                    label.name,
+                    (label, labelname) + label._alt_names + result_map_targets,
+                    label.type,
+                )
+
+            # Emit the column WITHOUT "AS <label>"
+            return label.element._compiler_dispatch(
+                self,
+                within_columns_clause=True,
+                within_label_clause=True,
+                **kw,
+            )
+
+        if render_label_as_label is label:
+            if isinstance(label.name, elements._truncated_label):
+                labelname = self._truncated_identifier("colident", label.name)
+            else:
+                labelname = label.name
+            return self.preparer.format_label(label, labelname)
+
+        return label.element._compiler_dispatch(self, within_columns_clause=False, **kw)
+
+    # ── Unsupported feature guards ─────────────────────────
+
+    def visit_join(self, join: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support JOIN")
+
+    def group_by_clause(self, select: Any, **kw: Any) -> str:
+        if select._group_by_clauses:
+            raise exc.CompileError("Excel dialect does not support GROUP BY")
+        return ""
+
+    def having_clause(self, select: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support HAVING")
+
+    def limit_clause(self, select: Any, **kw: Any) -> str:
+        text = ""
+        if select._limit_clause is not None:
+            text += " LIMIT " + self.process(select._limit_clause, **kw)
+        if select._offset_clause is not None:
+            raise exc.CompileError("Excel dialect does not support OFFSET")
+        return text
+
+    def visit_cte(self, cte: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support CTEs")
+
+    def visit_subquery(self, subquery: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support subqueries")
+
+    def returning_clause(
+        self,
+        stmt: Any,
+        returning_cols: Any,
+        **kw: Any,
+    ) -> str:
+        raise exc.CompileError("Excel dialect does not support RETURNING")
+
+    def for_update_clause(self, select: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support SELECT ... FOR UPDATE")

sqlalchemy_excel-0.1.1/src/sqlalchemy_excel/ddl.py

@@ -0,0 +1,57 @@
+"""DDL compiler for the Excel dialect.
+
+CREATE TABLE → creates a worksheet and writes column metadata.
+DROP TABLE   → deletes the worksheet and removes metadata.
+ALTER TABLE  → rejected (not supported).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import exc
+from sqlalchemy.sql import compiler
+
+
+class ExcelDDLCompiler(compiler.DDLCompiler):
+    """Compiles DDL statements for excel-dbapi."""
+
+    def visit_create_table(self, create: Any, **kw: Any) -> str:
+        """Compile CREATE TABLE into SQL that excel-dbapi's parser accepts.
+
+        Format: CREATE TABLE name (col1 TYPE, col2 TYPE, ...)
+        """
+        table = create.element
+        table_name = self.preparer.format_table(table)
+
+        columns = []
+        for col in table.columns:
+            col_name = self.preparer.format_column(col)
+            col_type = self.dialect.type_compiler.process(col.type)
+            columns.append(f"{col_name} {col_type}")
+
+        return f"CREATE TABLE {table_name} ({', '.join(columns)})"
+
+    def visit_drop_table(self, drop: Any, **kw: Any) -> str:
+        """Compile DROP TABLE."""
+        table = drop.element
+        table_name = self.preparer.format_table(table)
+        return f"DROP TABLE {table_name}"
+
+    def visit_create_index(self, create: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support CREATE INDEX")
+
+    def visit_drop_index(self, drop: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support DROP INDEX")
+
+    def visit_add_constraint(self, create: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support constraints")
+
+    def visit_drop_constraint(self, drop: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support constraints")
+
+    def visit_create_sequence(self, create: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support sequences")
+
+    def visit_drop_sequence(self, drop: Any, **kw: Any) -> str:
+        raise exc.CompileError("Excel dialect does not support sequences")