sqlalchemy-excel 0.2.2__tar.gz → 0.3.1__tar.gz

sqlalchemy_excel-0.3.1/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## [0.3.1] - 2026-04-12
+
+### Fixed
+- Add explicit `supports_statement_cache = False` to `ExcelGraphDialect` to suppress SQLAlchemy caching warning
+- Fix import ordering in test_graph_dialect.py for ruff I001 compliance
+
+## [0.3.0] - 2026-04-12
+
+### Added
+- `ExcelGraphDialect` for remote Excel files via Microsoft Graph API
+- `excel+graph:///drive_id/item_id` URL scheme support
+- Entry point `excel.graph` for SQLAlchemy dialect resolution
+- Optional dependency: `pip install sqlalchemy-excel[graph]`
+- URL percent-decoding for drive/item IDs with special characters
+- `readonly` query parameter forwarding to Graph backend
+- Comprehensive Graph dialect tests with `httpx.MockTransport`
+- `docs/` directory with USAGE.md, DEVELOPMENT.md, and ROADMAP.md
+
+### Changed
+- Version bumped to 0.3.0
+
+## [0.2.2] - 2026-04-12
+
+### Fixed
+- Restored cast() calls needed for CI mypy and suppress redundant-cast locally
+- Version bumped to 0.2.2
+
+## [0.2.1] - 2026-04-12
+
+### Added
+- Project logo (modern minimalist SVG)
+- Contributing guide, Code of Conduct, Security and Support policies
+- Development tooling: Makefile, .editorconfig, pre-commit-config, codecov.yml, git-cliff config
+- GitHub issue/PR templates and project management files
+- py.typed marker for PEP 561 compliance
+- twine check step in publish workflow
+
+### Changed
+- Classifier updated from Alpha to Beta
+- Changelog URL added to project metadata
+
+### Fixed
+- Oracle review findings: rollback docs, absolute logo URLs, metadata alignment
+
+## [0.2.0] - 2026-04-12
+
+### Added
+- Full dialect rewrite: ExcelCompiler, ExcelDDLCompiler, ExcelTypeCompiler, ExcelInspectionMixin
+- Comprehensive README with ORM examples, type mapping table, schema inspection docs
+- Test coverage reporting with Codecov CI integration
+- IN, BETWEEN, LIKE operator tests for SQLAlchemy dialect
+
+### Changed
+- excel-dbapi dependency updated to >=0.2.0
+- Version bumped to 0.2.0
+
+### Fixed
+- mypy strict incompatibility with SQLAlchemy dialect overrides (temporarily disabled then re-enabled)
+
+## [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.2.2 → sqlalchemy_excel-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-excel
-Version: 0.2.2
+Version: 0.3.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
@@ -29,6 +29,8 @@ 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'
+Provides-Extra: graph
+Requires-Dist: excel-dbapi[graph]>=0.2.0; extra == 'graph'
 Description-Content-Type: text/markdown
 
 <p align="left">
@@ -89,6 +91,33 @@ engine = create_engine("excel:////home/user/data.xlsx")
 engine = create_engine("excel:///data.xlsx", connect_args={"engine": "openpyxl"})
 ```
 
+## Remote Excel via Microsoft Graph API
+
+Access Excel files on OneDrive/SharePoint directly:
+
+```bash
+pip install sqlalchemy-excel[graph]
+```
+
+```python
+from sqlalchemy import create_engine
+from azure.identity import DefaultAzureCredential
+
+engine = create_engine(
+    "excel+graph:///drive_id/item_id",
+    connect_args={"credential": DefaultAzureCredential()},
+)
+
+with engine.connect() as conn:
+    result = conn.execute(text("SELECT * FROM Sheet1"))
+    for row in result:
+        print(row)
+```
+
+URL format: `excel+graph:///drive_id/item_id` where `drive_id` and `item_id` are Microsoft Graph resource identifiers.
+Query parameters: `?readonly=false` to enable write operations.
+
+
 ## Features
 
 - Full SQLAlchemy 2.0 dialect

{sqlalchemy_excel-0.2.2 → sqlalchemy_excel-0.3.1}/README.md

@@ -56,6 +56,33 @@ engine = create_engine("excel:////home/user/data.xlsx")
 engine = create_engine("excel:///data.xlsx", connect_args={"engine": "openpyxl"})
 ```
 
+## Remote Excel via Microsoft Graph API
+
+Access Excel files on OneDrive/SharePoint directly:
+
+```bash
+pip install sqlalchemy-excel[graph]
+```
+
+```python
+from sqlalchemy import create_engine
+from azure.identity import DefaultAzureCredential
+
+engine = create_engine(
+    "excel+graph:///drive_id/item_id",
+    connect_args={"credential": DefaultAzureCredential()},
+)
+
+with engine.connect() as conn:
+    result = conn.execute(text("SELECT * FROM Sheet1"))
+    for row in result:
+        print(row)
+```
+
+URL format: `excel+graph:///drive_id/item_id` where `drive_id` and `item_id` are Microsoft Graph resource identifiers.
+Query parameters: `?readonly=false` to enable write operations.
+
+
 ## Features
 
 - Full SQLAlchemy 2.0 dialect

sqlalchemy_excel-0.3.1/docs/DEVELOPMENT.md

@@ -0,0 +1,263 @@
+# Development Guide
+
+This guide covers how to set up a development environment and contribute to sqlalchemy-excel.
+
+## Getting Started
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/yeongseon/sqlalchemy-excel.git
+cd sqlalchemy-excel
+```
+
+### Set Up Virtual Environment
+
+Create and activate a virtual environment:
+
+```bash
+# Using venv (Python 3.10+)
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Or using virtualenv
+virtualenv .venv
+source .venv/bin/activate
+```
+
+### Install Development Dependencies
+
+Install the package in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+This installs:
+- `sqlalchemy>=2.0`
+- `excel-dbapi>=0.2.0`
+- `pytest>=8.0`
+- `pytest-cov>=4.0`
+- `ruff>=0.4`
+- `mypy>=1.10`
+
+## Makefile Commands
+
+The project includes a Makefile for common development tasks:
+
+| Command | Description |
+|---------|-------------|
+| `make install` | Install the package in editable mode with dev dependencies |
+| `make format` | Format code with ruff |
+| `make lint` | Run linting checks with ruff and mypy |
+| `make test` | Run tests with pytest |
+| `make coverage` | Run tests with coverage report |
+| `make build` | Build distribution packages |
+| `make clean` | Remove build artifacts and cache files |
+
+## Running Tests
+
+Run the test suite using pytest:
+
+```bash
+# Run all tests
+pytest
+
+# Or use make
+make test
+
+# Run with coverage
+pytest --cov=sqlalchemy_excel --cov-report=html
+make coverage
+
+# Run specific test file
+pytest tests/test_dialect.py
+
+# Run specific test
+pytest tests/test_dialect.py::test_create_engine
+
+# Run with verbose output
+pytest -v
+```
+
+Test files are located in the `tests/` directory.
+
+## Code Style
+
+sqlalchemy-excel follows strict code quality standards:
+
+### Linting and Formatting
+
+**Ruff** is used for both linting and formatting:
+
+```bash
+# Format code (auto-fix)
+ruff format .
+
+# Check linting (without fixing)
+ruff check .
+
+# Auto-fix linting issues
+ruff check --fix .
+
+# Or use make
+make format  # Format + auto-fix
+make lint    # Check without fixing
+```
+
+Configuration is in `pyproject.toml`:
+- Target version: Python 3.10+
+- Line length: 88 characters
+- Enabled rules: pycodestyle, pyflakes, isort, pep8-naming, pyupgrade, flake8-bugbear, flake8-simplify, flake8-type-checking, ruff-specific
+
+### Type Checking
+
+**mypy** is configured in strict mode:
+
+```bash
+mypy src/sqlalchemy_excel
+
+# Or as part of make lint
+make lint
+```
+
+Configuration (`pyproject.toml`):
+- `strict = true`
+- `warn_return_any = true`
+- `warn_unused_configs = true`
+
+All code must pass strict type checking before merging.
+
+## Project Structure
+
+```
+sqlalchemy-excel/
+├── src/sqlalchemy_excel/     # Main source code
+│   ├── __init__.py           # Package entry point
+│   ├── dialect.py            # ExcelDialect implementation
+│   ├── compiler.py           # SQL compilation (ExcelCompiler, DDLCompiler, TypeCompiler)
+│   ├── types.py              # Type mappings
+│   └── py.typed              # PEP 561 marker file
+├── tests/                     # Test suite
+│   ├── test_dialect.py
+│   ├── test_compiler.py
+│   └── fixtures/             # Test data files
+├── docs/                      # Documentation
+│   ├── USAGE.md
+│   ├── DEVELOPMENT.md
+│   └── ROADMAP.md
+├── pyproject.toml            # Project metadata and config
+├── README.md                 # Main documentation
+├── CHANGELOG.md              # Version history
+├── LICENSE                   # MIT License
+└── Makefile                  # Development commands
+```
+
+## Development Workflow
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+2. **Make changes** and add tests
+
+3. **Format and lint**:
+   ```bash
+   make format
+   make lint
+   ```
+
+4. **Run tests**:
+   ```bash
+   make test
+   ```
+
+5. **Commit changes**:
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   ```
+
+6. **Push and create pull request**:
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+## Release Process
+
+sqlalchemy-excel uses GitHub Actions for automated releases:
+
+### 1. Update CHANGELOG.md
+
+Document all changes in the changelog following the format:
+
+```markdown
+## [0.3.0] - 2024-01-15
+
+### Added
+- New feature X
+- Support for Y
+
+### Fixed
+- Bug Z
+```
+
+### 2. Bump Version
+
+Update the version in `pyproject.toml`:
+
+```toml
+[project]
+version = "0.3.0"
+```
+
+### 3. Create Git Tag
+
+```bash
+git add pyproject.toml CHANGELOG.md
+git commit -m "chore: bump version to 0.3.0"
+git tag v0.3.0
+git push origin main
+git push origin v0.3.0
+```
+
+### 4. Automated Publishing
+
+When you push a tag (`v*`), GitHub Actions automatically:
+1. Runs all tests and linting
+2. Builds distribution packages (`sdist` and `wheel`)
+3. Publishes to PyPI using **Trusted Publisher (OIDC)**
+
+**No API token needed** — the project uses PyPI's Trusted Publisher feature with OIDC authentication configured in GitHub Actions.
+
+### 5. Verify Release
+
+Check that the release appears on:
+- PyPI: https://pypi.org/project/sqlalchemy-excel/
+- GitHub Releases: https://github.com/yeongseon/sqlalchemy-excel/releases
+
+## Continuous Integration
+
+The CI pipeline (`.github/workflows/ci.yml`) runs on every push and pull request:
+
+1. **Linting**: ruff + mypy
+2. **Testing**: pytest on Python 3.10, 3.11, 3.12, 3.13
+3. **Coverage**: Upload to Codecov
+
+All checks must pass before merging.
+
+## Contributing Guidelines
+
+- Write tests for all new features and bug fixes
+- Maintain or improve code coverage (target: 90%+)
+- Follow the existing code style (enforced by ruff)
+- Add type hints for all functions (enforced by mypy strict mode)
+- Update documentation for user-facing changes
+- Keep commits atomic and write clear commit messages
+
+## Getting Help
+
+- Open an issue: https://github.com/yeongseon/sqlalchemy-excel/issues
+- Check existing discussions and issues
+- Review the main README and USAGE guide

sqlalchemy_excel-0.3.1/docs/ROADMAP.md

@@ -0,0 +1,151 @@
+# Project Roadmap
+
+This roadmap outlines the past achievements and future plans for sqlalchemy-excel.
+
+## Completed Features
+
+### v0.1.0 — Initial Release
+- ✅ SQLAlchemy 2.0 dialect implementation
+- ✅ ORM support with `DeclarativeBase`
+- ✅ Basic SQL operations: SELECT, INSERT, UPDATE, DELETE
+- ✅ WHERE clauses with comparison operators
+- ✅ ORDER BY and LIMIT support
+- ✅ Type mapping for common SQLAlchemy types
+- ✅ Integration with excel-dbapi driver
+- ✅ Schema inspection (`get_table_names`, `get_columns`, `has_table`)
+
+### v0.2.x — Dialect Rewrite and Quality Improvements
+- ✅ Complete dialect architecture rewrite
+  - ExcelCompiler for SQL compilation
+  - DDLCompiler for CREATE/DROP TABLE
+  - TypeCompiler for type system
+- ✅ Enhanced operator support: IN, BETWEEN, LIKE
+- ✅ Codecov integration for coverage tracking
+- ✅ mypy strict mode with full type safety
+- ✅ Comprehensive test suite
+- ✅ Improved documentation and examples
+- ✅ GitHub Actions CI/CD pipeline
+- ✅ PyPI Trusted Publisher (OIDC) for secure releases
+
+## Planned Features
+
+### High Priority
+
+#### Remote Excel Access via Microsoft Graph API
+- [ ] Implement `excel+graph://` URL scheme
+- [ ] Support for OneDrive and SharePoint Excel files
+- [ ] OAuth 2.0 authentication flow
+- [ ] Read/write operations on cloud-stored Excel files
+- [ ] Caching layer for remote files
+
+**Use case**: Access and query Excel files stored in Microsoft 365 without downloading them locally.
+
+```python
+# Future API
+engine = create_engine(
+    "excel+graph:///sites/mysite/documents/data.xlsx",
+    connect_args={
+        "tenant_id": "...",
+        "client_id": "...",
+        "client_secret": "..."
+    }
+)
+```
+
+### Medium Priority
+
+#### Advanced SQL Support
+- [ ] **DISTINCT**: Remove duplicate rows
+- [ ] **OFFSET**: Pagination support (currently only LIMIT works)
+- [ ] **Aggregate functions**: COUNT, SUM, AVG, MIN, MAX
+- [ ] **GROUP BY**: Grouping and aggregation
+- [ ] **HAVING**: Filtering on aggregated data
+- [ ] **Subqueries**: Nested SELECT statements
+- [ ] **CTEs (Common Table Expressions)**: WITH clauses
+
+**Status**: These features require significant changes to the excel-dbapi query engine. Aggregate functions are particularly complex due to Excel's storage model.
+
+#### Multi-Table Operations
+- [ ] **JOIN support**: INNER JOIN, LEFT JOIN, RIGHT JOIN
+- [ ] Cross-sheet queries
+- [ ] Foreign key awareness (metadata only, no enforcement)
+
+**Challenge**: Excel has no native concept of relationships or joins. Implementation would require loading and joining data in memory.
+
+#### Performance Optimization
+- [ ] Lazy loading for large Excel files
+- [ ] Column-level filtering (avoid loading entire rows)
+- [ ] Query result caching
+- [ ] Batch operation optimization
+- [ ] Memory-efficient streaming for large datasets
+
+**Target**: Support Excel files with 100K+ rows without excessive memory usage.
+
+### Low Priority
+
+#### Async Support
+- [ ] Async dialect (`excel+aio://`)
+- [ ] AsyncEngine and AsyncSession support
+- [ ] Non-blocking I/O for file operations
+
+**Note**: Requires asyncio-compatible openpyxl wrapper or alternative Excel library.
+
+#### Additional Features
+- [ ] Support for Excel formulas in queries
+- [ ] Worksheet-level transactions (via temporary files)
+- [ ] ALTER TABLE support (add/remove columns)
+- [ ] Index simulation for faster lookups
+- [ ] Excel template support (preserve formatting)
+- [ ] Multiple sheet joins within same file
+
+## Known Issues and Limitations
+
+### Current Limitations (By Design)
+- No transactional rollback (Excel files don't support ACID transactions)
+- No concurrent writes (Excel file format limitations)
+- Limited SQL feature set compared to traditional RDBMS
+- Performance degrades with very large files (>50MB)
+
+### Under Consideration
+- **Alternative Excel engines**: Support for xlrd, xlwt, pyexcel in addition to openpyxl
+- **CSV fallback**: Automatic conversion to CSV for read-only operations
+- **SQLite hybrid mode**: Use SQLite as intermediate cache for complex queries
+
+## Community Feedback
+
+We welcome feedback on this roadmap! Please:
+- 🌟 Star the repository if you find it useful
+- 💬 Open an issue to suggest new features
+- 🐛 Report bugs and edge cases
+- 📝 Contribute to documentation improvements
+- 🔀 Submit pull requests for planned features
+
+**Priority is driven by community demand** — let us know what you need!
+
+## Versioning Strategy
+
+sqlalchemy-excel follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR (1.0.0)**: Stable API, production-ready, breaking changes
+- **MINOR (0.x.0)**: New features, backward-compatible
+- **PATCH (0.0.x)**: Bug fixes, no new features
+
+**Current status**: Beta (0.x.x) — API may change before 1.0.0.
+
+## Long-Term Vision
+
+The goal of sqlalchemy-excel is to:
+1. Provide a **seamless SQLAlchemy experience** for Excel files
+2. Enable **analysts and developers** to use familiar SQL tools with Excel
+3. Bridge the gap between **ad-hoc Excel data** and **structured database workflows**
+4. Support **cloud-native Excel** (Microsoft 365, Google Sheets in future)
+
+**Not a goal**: Replace traditional databases for production workloads. Excel is great for prototyping, data analysis, and small-scale applications, but RDBMS should be used for critical systems.
+
+## Contributing to the Roadmap
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for contribution guidelines.
+
+---
+
+**Last updated**: 2024-01 (v0.2.2)

sqlalchemy_excel-0.3.1/docs/USAGE.md

@@ -0,0 +1,267 @@
+# Usage Guide
+
+This guide covers how to use sqlalchemy-excel in your projects.
+
+## Installation
+
+```bash
+pip install sqlalchemy-excel
+```
+
+The underlying driver `excel-dbapi` is automatically installed as a dependency.
+
+## URL Format
+
+sqlalchemy-excel uses the `excel://` URL scheme:
+
+```python
+from sqlalchemy import create_engine
+
+# Relative path (relative to current working directory)
+engine = create_engine("excel:///data.xlsx")
+
+# Absolute path (note four slashes total: excel:// + //)
+engine = create_engine("excel:////home/user/data.xlsx")
+engine = create_engine("excel:////Users/alice/Documents/data.xlsx")
+
+# With engine options (passed to connect_args)
+engine = create_engine("excel:///data.xlsx", connect_args={"engine": "openpyxl"})
+```
+
+**Important**: Absolute paths require **four slashes** total (`excel:////absolute/path.xlsx`).
+
+## Basic ORM Usage
+
+### Define Models
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, Mapped, mapped_column
+
+engine = create_engine("excel:///data.xlsx")
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column()
+    age: Mapped[int] = mapped_column()
+
+# Create the table (sheet) if it doesn't exist
+Base.metadata.create_all(engine)
+```
+
+### Use Sessions
+
+```python
+# Insert data
+with Session(engine) as session:
+    session.add(User(id=1, name="Alice", age=30))
+    session.add(User(id=2, name="Bob", age=25))
+    session.commit()
+
+# Query data
+with Session(engine) as session:
+    users = session.query(User).all()
+    for user in users:
+        print(f"{user.id}: {user.name} ({user.age})")
+```
+
+## Core Usage
+
+You can also use SQLAlchemy Core with `text()` queries:
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("excel:///data.xlsx")
+
+with engine.connect() as conn:
+    # Execute a raw SQL query
+    result = conn.execute(text("SELECT * FROM Sheet1"))
+    for row in result:
+        print(row)
+    
+    # Parameterized query (always use this for security)
+    result = conn.execute(
+        text("SELECT * FROM users WHERE name = :name"),
+        {"name": "Alice"}
+    )
+    for row in result:
+        print(row)
+```
+
+## Query Examples
+
+### WHERE Clause
+
+```python
+from sqlalchemy import select
+
+with Session(engine) as session:
+    # Simple equality
+    user = session.query(User).filter(User.name == "Alice").first()
+    
+    # Comparison operators
+    stmt = select(User).where(User.age > 25)
+    users = session.scalars(stmt).all()
+```
+
+### IN Operator
+
+```python
+with Session(engine) as session:
+    stmt = select(User).where(User.name.in_(["Alice", "Bob", "Charlie"]))
+    users = session.scalars(stmt).all()
+```
+
+### BETWEEN Operator
+
+```python
+with Session(engine) as session:
+    # Find users with age between 25 and 35
+    stmt = select(User).where(User.age.between(25, 35))
+    users = session.scalars(stmt).all()
+```
+
+### LIKE Operator
+
+```python
+with Session(engine) as session:
+    # Find users whose name starts with 'A'
+    stmt = select(User).where(User.name.like("A%"))
+    users = session.scalars(stmt).all()
+    
+    # Contains 'li'
+    stmt = select(User).where(User.name.like("%li%"))
+    users = session.scalars(stmt).all()
+```
+
+### ORDER BY and LIMIT
+
+```python
+with Session(engine) as session:
+    # Order by age descending
+    stmt = select(User).order_by(User.age.desc())
+    users = session.scalars(stmt).all()
+    
+    # Get top 5 oldest users
+    stmt = select(User).order_by(User.age.desc()).limit(5)
+    users = session.scalars(stmt).all()
+```
+
+## Insert, Update, and Delete
+
+### Insert
+
+```python
+with Session(engine) as session:
+    new_user = User(id=3, name="Charlie", age=28)
+    session.add(new_user)
+    session.commit()
+```
+
+### Update
+
+```python
+with Session(engine) as session:
+    user = session.query(User).filter(User.id == 1).first()
+    if user:
+        user.name = "Ann"
+        user.age = 31
+        session.commit()
+```
+
+### Delete
+
+```python
+with Session(engine) as session:
+    user = session.query(User).filter(User.id == 2).first()
+    if user:
+        session.delete(user)
+        session.commit()
+```
+
+## Schema Inspection
+
+SQLAlchemy's inspector API works with Excel files:
+
+```python
+from sqlalchemy import create_engine, inspect
+
+engine = create_engine("excel:///data.xlsx")
+inspector = inspect(engine)
+
+# List all sheets (tables)
+table_names = inspector.get_table_names()
+print(f"Available sheets: {table_names}")
+
+# Get columns for a specific sheet
+columns = inspector.get_columns("users")
+for col in columns:
+    print(f"{col['name']}: {col['type']}")
+
+# Check if a sheet exists
+if inspector.has_table("users"):
+    print("The 'users' sheet exists")
+```
+
+## Type Mapping
+
+sqlalchemy-excel maps SQLAlchemy types to Excel storage types:
+
+| SQLAlchemy Type | Excel Storage | Notes |
+|-----------------|---------------|-------|
+| `String`, `Text`, `VARCHAR`, `CHAR` | TEXT | All string types → TEXT |
+| `Integer`, `SmallInteger`, `BigInteger` | INTEGER | All integer types → INTEGER |
+| `Float`, `Numeric`, `Decimal` | FLOAT | All numeric types → FLOAT |
+| `Boolean` | BOOLEAN | Stored as boolean |
+| `Date` | DATE | Date without time |
+| `DateTime`, `TIMESTAMP` | DATETIME | Date with time |
+| `Time` | TEXT | Stored as text |
+| `Uuid` | TEXT | Stored as text |
+
+**Unsupported types**: BLOB, BINARY, JSON, ARRAY (will raise `CompileError`)
+
+## Limitations
+
+sqlalchemy-excel has some limitations due to the nature of Excel as a database:
+
+- **No JOIN operations**: Single-table queries only
+- **No GROUP BY, HAVING, DISTINCT**: Aggregations not supported
+- **No OFFSET**: Only LIMIT is supported
+- **No subqueries or CTEs**: Simple queries only
+- **No aggregate functions**: COUNT, SUM, AVG, etc. not available
+- **No ALTER TABLE**: Cannot modify table structure after creation
+- **No foreign keys or indexes**: Excel has no concept of these
+- **No concurrent writes**: Use a single-writer model
+- **Rollback is a no-op**: `Session.rollback()` does nothing — Excel files don't support transactional rollback
+
+## Security
+
+**Always use parameterized queries** to prevent SQL injection:
+
+```python
+# ✅ GOOD: Parameterized query
+with engine.connect() as conn:
+    result = conn.execute(
+        text("SELECT * FROM users WHERE name = :name"),
+        {"name": user_input}
+    )
+
+# ❌ BAD: String interpolation (vulnerable to SQL injection)
+with engine.connect() as conn:
+    result = conn.execute(
+        text(f"SELECT * FROM users WHERE name = '{user_input}'")
+    )
+```
+
+SQLAlchemy ORM queries are automatically parameterized and safe:
+
+```python
+# ✅ SAFE: ORM automatically parameterizes
+with Session(engine) as session:
+    user = session.query(User).filter(User.name == user_input).first()
+```

sqlalchemy_excel-0.3.1/logo.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#1DB954"/>
+      <stop offset="100%" stop-color="#148A40"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Base (same as excel-dbapi) -->
+  <rect x="8" y="8" width="112" height="112" rx="26" fill="url(#bg)"/>
+
+  <!-- Left: bold SA angle bracket -->
+  <path d="M52 30 L26 64 L52 98" fill="none" stroke="#fff" stroke-width="8" stroke-linecap="round" stroke-linejoin="round" opacity="0.92"/>
+
+  <!-- Right: 2×1 grid cells (spreadsheet) -->
+  <rect x="64" y="36" width="36" height="24" rx="5" fill="#fff" opacity="0.92"/>
+  <rect x="64" y="66" width="36" height="24" rx="5" fill="#fff" opacity="0.68"/>
+
+  <!-- Bridge: connector -->
+  <line x1="55" y1="64" x2="61" y2="64" stroke="#fff" stroke-width="4" stroke-linecap="round" opacity="0.60"/>
+</svg>

{sqlalchemy_excel-0.2.2 → sqlalchemy_excel-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-excel"
-version = "0.2.2"
+version = "0.3.1"
 description = "SQLAlchemy dialect for Excel files — use Excel as a database"
 readme = "README.md"
 license = {text = "MIT"}
@@ -33,6 +33,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+graph = ["excel-dbapi[graph]>=0.2.0"]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=4.0",
@@ -42,6 +43,7 @@ dev = [
 
 [project.entry-points."sqlalchemy.dialects"]
 excel = "sqlalchemy_excel.dialect:ExcelDialect"
+"excel.graph" = "sqlalchemy_excel.dialect:ExcelGraphDialect"
 
 [project.urls]
 Homepage = "https://github.com/yeongseon/sqlalchemy-excel"

{sqlalchemy_excel-0.2.2 → sqlalchemy_excel-0.3.1}/src/sqlalchemy_excel/__init__.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
-from .dialect import ExcelDialect
+from .dialect import ExcelDialect, ExcelGraphDialect
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"
 
 __all__ = [
     "ExcelDialect",
+    "ExcelGraphDialect",
     "__version__",
 ]

{sqlalchemy_excel-0.2.2 → sqlalchemy_excel-0.3.1}/src/sqlalchemy_excel/dialect.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import re
 from typing import TYPE_CHECKING, Any, Literal, cast
+from urllib.parse import unquote as _url_unquote
 
 from sqlalchemy import event, pool
 from sqlalchemy.engine import default
@@ -230,3 +231,63 @@ class ExcelDialect(  # type: ignore[misc]  # pyright: ignore[reportIncompatibleM
     def do_close(self, dbapi_connection: Any) -> None:
         """Close the underlying excel-dbapi connection."""
         dbapi_connection.close()
+
+
+class ExcelGraphDialect(ExcelDialect):  # type: ignore[misc,unused-ignore]
+    """SQLAlchemy dialect for remote Excel files via Microsoft Graph API.
+
+    Connection URLs::
+
+        # With drive_id and item_id
+        excel+graph:///drive_id/item_id
+
+        # With query parameters
+        excel+graph:///drive_id/item_id?readonly=false
+
+    Credentials must be passed via ``connect_args``::
+
+        engine = create_engine(
+            "excel+graph:///drive_id/item_id",
+            connect_args={"credential": DefaultAzureCredential()},
+        )
+    """
+
+    driver: str = "graph"
+    supports_statement_cache: bool = False
+
+    def create_connect_args(self, url: URL) -> ConnectArgsType:
+        """Translate an excel+graph:// URL to excel-dbapi connect() arguments.
+
+        URL format: excel+graph:///drive_id/item_id
+        Maps to DSN: msgraph://drives/{drive_id}/items/{item_id}
+        """
+        database = url.database
+        if not database:
+            raise ValueError(
+                "No drive/item path in URL. Use excel+graph:///drive_id/item_id"
+            )
+
+        parts = database.strip("/").split("/")
+        if len(parts) != 2:
+            raise ValueError(
+                f"Expected excel+graph:///drive_id/item_id (got {len(parts)} path segments: {database!r})"
+            )
+
+        drive_id = _url_unquote(parts[0])
+        item_id = _url_unquote(parts[1])
+        dsn = f"msgraph://drives/{drive_id}/items/{item_id}"
+
+        kwargs = {
+            "file_path": dsn,
+            "engine": "graph",
+            "autocommit": True,
+            "create": False,
+        }
+
+        query = dict(url.query)
+        if "readonly" in query:
+            raw = query.pop("readonly")
+            val = raw[0] if isinstance(raw, tuple) else raw
+            kwargs["readonly"] = str(val).lower() in ("true", "1", "yes")
+
+        return ([], kwargs)

sqlalchemy_excel-0.3.1/tests/test_graph_dialect.py

@@ -0,0 +1,170 @@
+"""Tests for ExcelGraphDialect — URL parsing and Graph API integration."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from sqlalchemy import create_engine, text
+from sqlalchemy.dialects import registry
+from sqlalchemy.engine import make_url
+
+# ---------------------------------------------------------------------------
+# Mock transport (minimal Graph API stub)
+# ---------------------------------------------------------------------------
+
+
+def _graph_handler(request: httpx.Request) -> httpx.Response:
+    """Stateless mock handler for read-only Graph API tests."""
+    path = request.url.path
+    method = request.method
+
+    if path.endswith("/createSession"):
+        return httpx.Response(201, json={"id": "sess-graph-test"})
+    if path.endswith("/closeSession"):
+        return httpx.Response(204)
+
+    if (
+        path.endswith("/worksheets") or "/worksheets?" in str(request.url)
+    ) and method == "GET":
+        return httpx.Response(
+            200,
+            json={"value": [{"id": "ws-sheet1", "name": "Sheet1"}]},
+        )
+
+    if "usedRange" in path and method == "GET":
+        return httpx.Response(
+            200,
+            json={
+                "values": [
+                    ["id", "name", "value"],
+                    [1, "Alice", 100],
+                    [2, "Bob", 200],
+                ]
+            },
+        )
+
+    return httpx.Response(404)
+
+
+# ---------------------------------------------------------------------------
+# URL Parsing Tests
+# ---------------------------------------------------------------------------
+
+
+class TestGraphURLParsing:
+    def test_url_components(self):
+        url = make_url("excel+graph:///drv-abc/itm-xyz")
+        assert url.get_backend_name() == "excel"
+        assert url.get_driver_name() == "graph"
+        assert url.database == "drv-abc/itm-xyz"
+
+    def test_url_with_host_ignored(self):
+        """Host part (tenant_id) is allowed but unused."""
+        url = make_url("excel+graph://my-tenant/drv-abc/itm-xyz")
+        assert url.host == "my-tenant"
+        assert url.database == "drv-abc/itm-xyz"
+
+    def test_create_connect_args_basic(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///drv-abc/itm-xyz")
+        args, kwargs = dialect.create_connect_args(url)
+        assert args == []
+        assert kwargs["file_path"] == "msgraph://drives/drv-abc/items/itm-xyz"
+        assert kwargs["engine"] == "graph"
+        assert kwargs["autocommit"] is True
+        assert kwargs["create"] is False
+
+    def test_create_connect_args_url_decoding(self):
+        """Drive/item IDs with percent-encoded chars should be decoded."""
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///b%21abc/itm%2D123")
+        _, kwargs = dialect.create_connect_args(url)
+        assert kwargs["file_path"] == "msgraph://drives/b!abc/items/itm-123"
+
+    def test_create_connect_args_readonly_false(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///drv/itm?readonly=false")
+        _, kwargs = dialect.create_connect_args(url)
+        assert kwargs.get("readonly") is False
+
+    def test_create_connect_args_readonly_true(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///drv/itm?readonly=true")
+        _, kwargs = dialect.create_connect_args(url)
+        assert kwargs.get("readonly") is True
+
+    def test_empty_path_raises(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph://")
+        with pytest.raises(ValueError, match="No drive/item path"):
+            _ = dialect.create_connect_args(url)
+
+    def test_single_segment_raises(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///only-one")
+        with pytest.raises(ValueError, match="path segments"):
+            _ = dialect.create_connect_args(url)
+
+    def test_three_segments_raises(self):
+        dialect = registry.load("excel.graph")()
+        url = make_url("excel+graph:///a/b/c")
+        with pytest.raises(ValueError, match="path segments"):
+            _ = dialect.create_connect_args(url)
+
+
+# ---------------------------------------------------------------------------
+# Dialect Feature Flags
+# ---------------------------------------------------------------------------
+
+
+class TestGraphDialectFlags:
+    def test_driver(self):
+        d = registry.load("excel.graph")()
+        assert d.driver == "graph"
+
+    def test_name(self):
+        d = registry.load("excel.graph")()
+        assert d.name == "excel"
+
+
+# ---------------------------------------------------------------------------
+# Integration: SELECT via mock transport
+# ---------------------------------------------------------------------------
+
+
+class TestGraphDialectIntegration:
+    def test_select_via_engine(self):
+        """Full round-trip: create_engine → connect → SELECT."""
+        transport = httpx.MockTransport(_graph_handler)
+        engine = create_engine(
+            "excel+graph:///drv-test/itm-test",
+            connect_args={
+                "credential": "test-token",
+                "transport": transport,
+            },
+        )
+        with engine.connect() as conn:
+            result = conn.execute(text("SELECT * FROM Sheet1"))
+            rows = result.fetchall()
+            assert len(rows) == 2
+            assert rows[0] == (1, "Alice", 100)
+        engine.dispose()
+
+    def test_select_with_where(self):
+        transport = httpx.MockTransport(_graph_handler)
+        engine = create_engine(
+            "excel+graph:///drv-test/itm-test",
+            connect_args={
+                "credential": "test-token",
+                "transport": transport,
+            },
+        )
+        with engine.connect() as conn:
+            result = conn.execute(
+                text("SELECT name FROM Sheet1 WHERE id = :id"),
+                {"id": 1},
+            )
+            rows = result.fetchall()
+            assert len(rows) == 1
+            assert rows[0] == ("Alice",)
+        engine.dispose()

sqlalchemy_excel-0.2.2/CHANGELOG.md

@@ -1,13 +0,0 @@
-# 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.2.2/logo.svg

@@ -1,23 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
-  <!-- SQL code bracket left -->
-  <path d="M10 38 L22 28 L22 34 L16 40 L16 64 L22 70 L22 76 L10 66 L10 38Z" fill="#CE4926" opacity="0.85" />
-  <!-- SQL code bracket right -->
-  <path d="M58 38 L46 28 L46 34 L52 40 L52 64 L46 70 L46 76 L58 66 L58 38Z" fill="#CE4926" opacity="0.85" />
-  <!-- SQL text -->
-  <text x="34" y="58" font-family="monospace" font-size="14" font-weight="bold" fill="#CE4926" text-anchor="middle">SA</text>
-  <!-- Arrow / bridge -->
-  <line x1="62" y1="52" x2="72" y2="52" stroke="#666" stroke-width="2" stroke-linecap="round" />
-  <polygon points="72,48 80,52 72,56" fill="#666" />
-  <!-- Excel spreadsheet -->
-  <rect x="82" y="16" width="40" height="56" rx="4" fill="#217346" />
-  <rect x="86" y="22" width="32" height="44" rx="2" fill="#fff" />
-  <!-- Grid lines -->
-  <line x1="86" y1="33" x2="118" y2="33" stroke="#217346" stroke-width="1" opacity="0.3" />
-  <line x1="86" y1="44" x2="118" y2="44" stroke="#217346" stroke-width="1" opacity="0.3" />
-  <line x1="86" y1="55" x2="118" y2="55" stroke="#217346" stroke-width="1" opacity="0.3" />
-  <line x1="97" y1="22" x2="97" y2="66" stroke="#217346" stroke-width="1" opacity="0.3" />
-  <line x1="107" y1="22" x2="107" y2="66" stroke="#217346" stroke-width="1" opacity="0.3" />
-  <!-- Dialect label -->
-  <rect x="14" y="88" width="100" height="24" rx="12" fill="#3572A5" />
-  <text x="64" y="104" font-family="sans-serif" font-size="11" font-weight="bold" fill="#fff" text-anchor="middle">dialect</text>
-</svg>