sqlpiston 0.1.0__tar.gz

sqlpiston-0.1.0/LICENSE

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

sqlpiston-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: sqlpiston
+Version: 0.1.0
+Summary: A low-level SQL library that builds parameterized SQL queries through Python operator overloading
+Author: MuliMuri
+License: MIT
+Keywords: sql,query-builder,orm,mysql,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: flake8>=7; extra == "dev"
+Requires-Dist: mypy>=1; extra == "dev"
+Dynamic: license-file
+
+# SQLPiston
+
+[![test](https://github.com/MuliMuri/sqlpiston/actions/workflows/test.yml/badge.svg)](https://github.com/MuliMuri/sqlpiston/actions/workflows/test.yml)
+[![lint](https://github.com/MuliMuri/sqlpiston/actions/workflows/lint.yml/badge.svg)](https://github.com/MuliMuri/sqlpiston/actions/workflows/lint.yml)
+[![coverage](https://codecov.io/gh/MuliMuri/sqlpiston/branch/main/graph/badge.svg)](https://codecov.io/gh/MuliMuri/sqlpiston)
+[![pypi](https://img.shields.io/pypi/v/sqlpiston.svg)](https://pypi.org/project/sqlpiston/)
+[![python](https://img.shields.io/pypi/pyversions/sqlpiston)](https://pypi.org/project/sqlpiston/)
+[![license](https://img.shields.io/github/license/MuliMuri/sqlpiston)](https://github.com/MuliMuri/sqlpiston/blob/main/LICENSE)
+
+*Write once, query everywhere — build SQL with Python operators.*
+
+[中文版](README_ZH.md)
+
+SQLPiston is a low-level SQL library that builds parameterized SQL queries
+through Python operator overloading. AST nodes carry zero SQL knowledge;
+dialect-specific compilers translate the same AST into the right SQL for each
+database.
+
+## Install
+
+```bash
+git clone https://github.com/MuliMuri/sqlpiston.git
+cd sqlpiston
+pip install -e .
+```
+
+Python 3.9+ on Linux / macOS / Windows.
+
+## Basic Usage
+
+```python
+from sqlpiston import Select, Field, Insert
+from sqlpiston import DBEngine, DBType, Session
+from dataclasses import dataclass
+
+eng = DBEngine(DBType.SQLite)
+eng.init_engine(":memory:")
+session = Session(eng)
+
+stmt = (
+    Select()
+    .select("id", "name", "age")
+    .from_table("users")
+    .where((Field("age") >= 18) & (Field("status") == "active"))
+    .order_by("id", "ASC")
+    .limit(10)
+)
+result = session.execute(stmt)
+
+@dataclass
+class User:
+    id: int
+    name: str
+    age: int
+
+users = result.map(User)
+
+session.execute(
+    Insert().into("users").values({"name": "Alice", "age": 25})
+)
+
+session.commit()
+session.close()
+```
+
+<details>
+<summary>More examples: JOIN, subquery, CTE, UPSERT, DDL</summary>
+
+**JOIN**
+
+```python
+Select() \
+    .select("users.name", "orders.total") \
+    .from_table("users") \
+    .join("orders",
+          Field("user_id", "orders") == Field("id", "users")) \
+    .where(Field("total", "orders") > 100)
+```
+
+**Subquery (IN / EXISTS / Scalar)**
+
+```python
+# IN subquery
+admin_ids = Select().select("id").from_table("admins")
+stmt = Select().select("name").from_table("users") \
+    .where(Field("id").is_in(admin_ids))
+
+# EXISTS
+sub = Select().select("1").from_table("orders") \
+    .where(Field("user_id", "orders") == Field("id", "users"))
+stmt = Select().select("name").from_table("users").where(sub.exists())
+
+# Scalar
+avg = Select().select(SQLFunction("avg", "salary")).from_table("employees")
+stmt = Select().select("name").from_table("staff").where(Field("salary") > avg)
+```
+
+**CTE**
+
+```python
+cte = Select().select("*").from_table("sales") \
+    .where(Field("amount") > 100).cte("big_sales")
+stmt = Select().with_(cte).select("*").from_table("big_sales")
+```
+
+**UPSERT — same AST, different SQL per dialect**
+
+```python
+Upsert() \
+    .into("users") \
+    .values({"id": 1, "name": "X"}) \
+    .on_conflict("id") \
+    .do_update({"name": "X"})
+```
+
+| Dialect | Generated SQL |
+|---------|--------------|
+| MySQL   | `INSERT INTO ... ON DUPLICATE KEY UPDATE` |
+| SQLite  | `INSERT INTO ... ON CONFLICT DO UPDATE`   |
+
+**DDL**
+
+```python
+CreateTable().table("users").if_not_exists() \
+    .column("id", "INTEGER", primary_key=True, nullable=False) \
+    .column("name", "VARCHAR(255)")
+
+AlterTable().table("users").add_column("age", "INTEGER", default=0)
+
+DropTable().table("users").if_exists()
+```
+
+</details>
+
+## Highlights
+
+- **Operator overloading** — `Field("age") >= 18` builds AST, not a boolean
+- **Dialect-aware** — same AST compiles to MySQL (%s, backticks) or SQLite (?, double-quotes)
+- **Full standard SQL** — SELECT, INSERT, UPDATE, DELETE, UPSERT, CTE, UNION, subqueries, DDL
+- **Parameterized by design** — values never interpolated into SQL strings
+- **Weak ORM** — result-to-dataclass mapping, no identity map or change tracking
+
+## Documentation
+
+```bash
+cd docs
+pip install -r requirements.txt
+sphinx-build -b html source build/html
+```
+
+## License
+
+MIT

sqlpiston-0.1.0/README.md

@@ -0,0 +1,153 @@
+# SQLPiston
+
+[![test](https://github.com/MuliMuri/sqlpiston/actions/workflows/test.yml/badge.svg)](https://github.com/MuliMuri/sqlpiston/actions/workflows/test.yml)
+[![lint](https://github.com/MuliMuri/sqlpiston/actions/workflows/lint.yml/badge.svg)](https://github.com/MuliMuri/sqlpiston/actions/workflows/lint.yml)
+[![coverage](https://codecov.io/gh/MuliMuri/sqlpiston/branch/main/graph/badge.svg)](https://codecov.io/gh/MuliMuri/sqlpiston)
+[![pypi](https://img.shields.io/pypi/v/sqlpiston.svg)](https://pypi.org/project/sqlpiston/)
+[![python](https://img.shields.io/pypi/pyversions/sqlpiston)](https://pypi.org/project/sqlpiston/)
+[![license](https://img.shields.io/github/license/MuliMuri/sqlpiston)](https://github.com/MuliMuri/sqlpiston/blob/main/LICENSE)
+
+*Write once, query everywhere — build SQL with Python operators.*
+
+[中文版](README_ZH.md)
+
+SQLPiston is a low-level SQL library that builds parameterized SQL queries
+through Python operator overloading. AST nodes carry zero SQL knowledge;
+dialect-specific compilers translate the same AST into the right SQL for each
+database.
+
+## Install
+
+```bash
+git clone https://github.com/MuliMuri/sqlpiston.git
+cd sqlpiston
+pip install -e .
+```
+
+Python 3.9+ on Linux / macOS / Windows.
+
+## Basic Usage
+
+```python
+from sqlpiston import Select, Field, Insert
+from sqlpiston import DBEngine, DBType, Session
+from dataclasses import dataclass
+
+eng = DBEngine(DBType.SQLite)
+eng.init_engine(":memory:")
+session = Session(eng)
+
+stmt = (
+    Select()
+    .select("id", "name", "age")
+    .from_table("users")
+    .where((Field("age") >= 18) & (Field("status") == "active"))
+    .order_by("id", "ASC")
+    .limit(10)
+)
+result = session.execute(stmt)
+
+@dataclass
+class User:
+    id: int
+    name: str
+    age: int
+
+users = result.map(User)
+
+session.execute(
+    Insert().into("users").values({"name": "Alice", "age": 25})
+)
+
+session.commit()
+session.close()
+```
+
+<details>
+<summary>More examples: JOIN, subquery, CTE, UPSERT, DDL</summary>
+
+**JOIN**
+
+```python
+Select() \
+    .select("users.name", "orders.total") \
+    .from_table("users") \
+    .join("orders",
+          Field("user_id", "orders") == Field("id", "users")) \
+    .where(Field("total", "orders") > 100)
+```
+
+**Subquery (IN / EXISTS / Scalar)**
+
+```python
+# IN subquery
+admin_ids = Select().select("id").from_table("admins")
+stmt = Select().select("name").from_table("users") \
+    .where(Field("id").is_in(admin_ids))
+
+# EXISTS
+sub = Select().select("1").from_table("orders") \
+    .where(Field("user_id", "orders") == Field("id", "users"))
+stmt = Select().select("name").from_table("users").where(sub.exists())
+
+# Scalar
+avg = Select().select(SQLFunction("avg", "salary")).from_table("employees")
+stmt = Select().select("name").from_table("staff").where(Field("salary") > avg)
+```
+
+**CTE**
+
+```python
+cte = Select().select("*").from_table("sales") \
+    .where(Field("amount") > 100).cte("big_sales")
+stmt = Select().with_(cte).select("*").from_table("big_sales")
+```
+
+**UPSERT — same AST, different SQL per dialect**
+
+```python
+Upsert() \
+    .into("users") \
+    .values({"id": 1, "name": "X"}) \
+    .on_conflict("id") \
+    .do_update({"name": "X"})
+```
+
+| Dialect | Generated SQL |
+|---------|--------------|
+| MySQL   | `INSERT INTO ... ON DUPLICATE KEY UPDATE` |
+| SQLite  | `INSERT INTO ... ON CONFLICT DO UPDATE`   |
+
+**DDL**
+
+```python
+CreateTable().table("users").if_not_exists() \
+    .column("id", "INTEGER", primary_key=True, nullable=False) \
+    .column("name", "VARCHAR(255)")
+
+AlterTable().table("users").add_column("age", "INTEGER", default=0)
+
+DropTable().table("users").if_exists()
+```
+
+</details>
+
+## Highlights
+
+- **Operator overloading** — `Field("age") >= 18` builds AST, not a boolean
+- **Dialect-aware** — same AST compiles to MySQL (%s, backticks) or SQLite (?, double-quotes)
+- **Full standard SQL** — SELECT, INSERT, UPDATE, DELETE, UPSERT, CTE, UNION, subqueries, DDL
+- **Parameterized by design** — values never interpolated into SQL strings
+- **Weak ORM** — result-to-dataclass mapping, no identity map or change tracking
+
+## Documentation
+
+```bash
+cd docs
+pip install -r requirements.txt
+sphinx-build -b html source build/html
+```
+
+## License
+
+MIT

sqlpiston-0.1.0/lib/sqlpiston/__init__.py

@@ -0,0 +1,27 @@
+from sqlpiston._types import ColumnValue, SQLValue
+from sqlpiston.builder.ddl import (
+    AlterTable, ColumnDef, CreateIndex, CreateTable, CreateView,
+    DropIndex, DropTable, DropView, Truncate,
+)
+from sqlpiston.builder.dml import Delete, Insert, Update, Upsert
+from sqlpiston.builder.nodes import CaseNode, Field, SQLFunction
+from sqlpiston.builder.selectable import CTE, CompoundSelect, Select
+from sqlpiston.compiler.base import Dialect
+from sqlpiston.core.engine import DBType
+from sqlpiston.core.engine.base import DBEngine
+from sqlpiston.core.pool import ConnectionPool
+from sqlpiston.core.session import Session
+from sqlpiston.orm.mapper import ResultSet
+
+__all__ = [
+    'SQLValue', 'ColumnValue',
+    'AlterTable', 'ColumnDef', 'CreateIndex', 'CreateTable', 'CreateView',
+    'DropIndex', 'DropTable', 'DropView', 'Truncate',
+    'Delete', 'Insert', 'Update', 'Upsert',
+    'CaseNode', 'Field', 'SQLFunction',
+    'CTE', 'CompoundSelect', 'Select',
+    'Dialect',
+    'DBType', 'DBEngine',
+    'ConnectionPool', 'Session',
+    'ResultSet',
+]

sqlpiston-0.1.0/lib/sqlpiston/_types.py

@@ -0,0 +1,5 @@
+from typing import TypeAlias, Union
+
+
+SQLValue: TypeAlias = Union[str, int, float, bool, None, bytes]
+ColumnValue = SQLValue

sqlpiston-0.1.0/lib/sqlpiston/builder/ddl.py

@@ -0,0 +1,228 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+from sqlpiston.builder.nodes import ASTNode
+from sqlpiston._types import SQLValue
+
+if TYPE_CHECKING:
+    from sqlpiston.builder.selectable import Select
+
+
+class AlterAction(Enum):
+    ADD = 1
+    DROP = 2
+    MODIFY = 3
+
+
+@dataclass
+class ColumnDef:
+    """Column definition for CREATE TABLE."""
+    name: str
+    type_: str
+    nullable: bool = True
+    primary_key: bool = False
+    default: Optional[SQLValue] = None
+    unique: bool = False
+
+
+class CreateTable(ASTNode):
+    """CREATE TABLE name (col1 TYPE, col2 TYPE, ...)"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._if_not_exists: bool = False
+        self._columns: List[ColumnDef] = []
+
+    def table(self, name: str) -> 'CreateTable':
+        self._table = name
+        return self
+
+    def if_not_exists(self) -> 'CreateTable':
+        self._if_not_exists = True
+        return self
+
+    def column(self, name: str, type_: str, *,
+               nullable: bool = True,
+               primary_key: bool = False,
+               default: Optional[SQLValue] = None,
+               unique: bool = False) -> 'CreateTable':
+        self._columns.append(ColumnDef(
+            name=name, type_=type_, nullable=nullable,
+            primary_key=primary_key, default=default, unique=unique,
+        ))
+        return self
+
+    def columns(self, *col_defs: ColumnDef) -> 'CreateTable':
+        self._columns.extend(col_defs)
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateTable(table={self._table!r}, columns={len(self._columns)})"
+
+
+class AlterTable(ASTNode):
+    """ALTER TABLE name ADD/DROP/MODIFY COLUMN ..."""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._actions: List[Tuple[AlterAction, str, Optional[str], Optional[ColumnDef]]] = []
+
+    def table(self, name: str) -> 'AlterTable':
+        self._table = name
+        return self
+
+    def add_column(self, name: str, type_: str, *,
+                   nullable: bool = True,
+                   default: Optional[SQLValue] = None) -> 'AlterTable':
+        col_def = ColumnDef(name=name, type_=type_, nullable=nullable, default=default)
+        self._actions.append((AlterAction.ADD, name, type_, col_def))
+        return self
+
+    def drop_column(self, name: str) -> 'AlterTable':
+        self._actions.append((AlterAction.DROP, name, None, None))
+        return self
+
+    def modify_column(self, name: str, type_: str, *,
+                      nullable: bool = True,
+                      default: Optional[SQLValue] = None) -> 'AlterTable':
+        col_def = ColumnDef(name=name, type_=type_, nullable=nullable, default=default)
+        self._actions.append((AlterAction.MODIFY, name, type_, col_def))
+        return self
+
+    def __repr__(self) -> str:
+        return f"AlterTable(table={self._table!r}, actions={len(self._actions)})"
+
+
+class DropTable(ASTNode):
+    """DROP TABLE [IF EXISTS] name"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+        self._if_exists: bool = False
+
+    def table(self, name: str) -> 'DropTable':
+        self._table = name
+        return self
+
+    def if_exists(self) -> 'DropTable':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropTable(table={self._table!r}, if_exists={self._if_exists})"
+
+
+class CreateIndex(ASTNode):
+    """CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col1, col2, ...)"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._table: Optional[str] = None
+        self._columns: Tuple[str, ...] = ()
+        self._unique: bool = False
+        self._if_not_exists: bool = False
+
+    def name(self, idx_name: str) -> 'CreateIndex':
+        self._name = idx_name
+        return self
+
+    def on(self, table: str) -> 'CreateIndex':
+        self._table = table
+        return self
+
+    def columns(self, *cols: str) -> 'CreateIndex':
+        self._columns = cols
+        return self
+
+    def unique(self) -> 'CreateIndex':
+        self._unique = True
+        return self
+
+    def if_not_exists(self) -> 'CreateIndex':
+        self._if_not_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateIndex(name={self._name!r}, table={self._table!r})"
+
+
+class DropIndex(ASTNode):
+    """DROP INDEX [IF EXISTS] name ON table"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._table: Optional[str] = None
+        self._if_exists: bool = False
+
+    def name(self, idx_name: str) -> 'DropIndex':
+        self._name = idx_name
+        return self
+
+    def on(self, table: str) -> 'DropIndex':
+        self._table = table
+        return self
+
+    def if_exists(self) -> 'DropIndex':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropIndex(name={self._name!r}, table={self._table!r})"
+
+
+class CreateView(ASTNode):
+    """CREATE VIEW [IF NOT EXISTS] name AS SELECT ..."""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._select: Optional['Select'] = None
+        self._if_not_exists: bool = False
+
+    def name(self, view_name: str) -> 'CreateView':
+        self._name = view_name
+        return self
+
+    def as_(self, select: 'Select') -> 'CreateView':
+        self._select = select
+        return self
+
+    def if_not_exists(self) -> 'CreateView':
+        self._if_not_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"CreateView(name={self._name!r})"
+
+
+class DropView(ASTNode):
+    """DROP VIEW [IF EXISTS] name"""
+
+    def __init__(self) -> None:
+        self._name: Optional[str] = None
+        self._if_exists: bool = False
+
+    def name(self, view_name: str) -> 'DropView':
+        self._name = view_name
+        return self
+
+    def if_exists(self) -> 'DropView':
+        self._if_exists = True
+        return self
+
+    def __repr__(self) -> str:
+        return f"DropView(name={self._name!r})"
+
+
+class Truncate(ASTNode):
+    """TRUNCATE TABLE name"""
+
+    def __init__(self) -> None:
+        self._table: Optional[str] = None
+
+    def table(self, name: str) -> 'Truncate':
+        self._table = name
+        return self
+
+    def __repr__(self) -> str:
+        return f"Truncate(table={self._table!r})"