sqlym 0.1.0__py3-none-any.whl

sqlym-0.1.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: sqlym
+Version: 0.1.0
+Summary: SQL-first database access library for Python
+Author: izuno4t
+License-Expression: MIT
+License-File: LICENSE
+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
+Requires-Python: >=3.10
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=3.0; extra == 'oracle'
+Provides-Extra: postgresql
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgresql'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# sqlym
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlym.svg)](https://pypi.org/project/sqlym/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlym.svg)](https://pypi.org/project/sqlym/)
+[![License](https://img.shields.io/pypi/l/sqlym.svg)](https://github.com/izuno4t/sqlym/blob/main/LICENSE)
+[![CI](https://github.com/izuno4t/sqlym/actions/workflows/ci.yml/badge.svg)](https://github.com/izuno4t/sqlym/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[日本語](README.ja.md)
+
+A SQL template engine for Python. Inspired by Java's
+[Clione-SQL](https://github.com/tauty/clione-sql) /
+[Doma2](https://github.com/domaframework/doma), it provides a 2-way SQL parser
+and row-to-object mapping.
+
+- **SQL-first** — Write SQL directly, not through an ORM. sqlym never
+  auto-generates SQL
+- **2-way SQL** — SQL files remain directly executable by DB tools
+- **Zero dependencies** — Core runs on the Python standard library only
+  (Pydantic is optional)
+- **Flexible mapping** — Auto-mapping for dataclass / Pydantic, or bring your
+  own function
+
+## Quick Start
+
+```bash
+pip install sqlym
+```
+
+### 1. Define an Entity
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+from sqlym import Column
+
+@dataclass
+class Employee:
+    id: int
+    name: Annotated[str, Column("EMP_NAME")]  # when column name differs
+    dept_id: int | None = None
+```
+
+### 2. Write a SQL File
+
+`sql/employee/find_by_dept.sql`:
+
+```sql
+SELECT
+    id,
+    EMP_NAME,
+    dept_id
+FROM
+    employee
+WHERE
+    id = /* $id */0
+    AND dept_id = /* $dept_id */1
+    AND status = /* $status */'active'
+```
+
+### 3. Execute
+
+```python
+from sqlym import SqlExecutor, create_mapper
+
+executor = SqlExecutor(connection)
+mapper = create_mapper(Employee)
+
+# Lines with None parameters are automatically removed
+result = executor.query(
+    "sql/employee/find_by_dept.sql",
+    {
+        "id": 100,
+        "dept_id": None,
+        "status": "active",
+    },  # dept_id line is removed
+    mapper=mapper
+)
+
+for emp in result:
+    print(emp.name)
+```
+
+For the full SQL syntax reference, see [SQL Syntax](SQL_SYNTAX.md).
+
+## Features
+
+### 2-way SQL (Clione-SQL Style)
+
+Parameters are written as SQL comments. The SQL file can be executed directly
+by DB tools.
+
+```sql
+-- None removes the line ($ prefix)
+WHERE name = /* $name */'default'
+
+-- None binds as NULL (no $ prefix)
+WHERE name = /* name */'default'
+```
+
+### Indent-based Parent-Child Relationships
+
+When all children are removed, the parent is also removed.
+
+```sql
+WHERE
+    id = /* $id */0
+    AND (
+        status = /* $status1 */'a'
+        OR status = /* $status2 */'b'
+    )
+-- If both status1 and status2 are None, the entire parenthesized block is
+-- removed
+```
+
+### Automatic IN Clause Expansion
+
+```sql
+WHERE dept_id IN /* $dept_ids */(1, 2, 3)
+-- dept_ids=[10,20,30] → WHERE dept_id IN (?, ?, ?)
+```
+
+### Error Message Settings
+
+Errors raised during SQL parsing include the line number by default.
+If you want to hide the SQL snippet from error messages, disable it via
+config:
+
+```python
+from sqlym import config
+
+config.ERROR_INCLUDE_SQL = False
+config.ERROR_MESSAGE_LANGUAGE = "en"
+```
+
+Set `ERROR_MESSAGE_LANGUAGE` to `ja` or `en`.
+
+### Mappers
+
+```python
+# Auto-mapping (dataclass / Pydantic)
+mapper = create_mapper(Employee)
+
+# Manual mapping (when column names differ significantly)
+mapper = create_mapper(Employee, mapper=lambda row: Employee(
+    id=row['EMP_ID'],
+    name=row['EMP_NM'],
+    dept_id=row['DEPT_CODE'],
+))
+```
+
+### Column Name Mapping
+
+```python
+from typing import Annotated
+from sqlym import Column, entity
+
+@dataclass
+class Employee:
+    # Per-field mapping
+    id: Annotated[int, Column("EMP_ID")]
+    name: Annotated[str, Column("EMP_NAME")]
+
+    # No mapping — uses field name as-is
+    email: str
+
+# Or apply a naming convention
+@entity(naming="snake_to_camel")  # dept_id → deptId
+@dataclass
+class Employee:
+    dept_id: int  # → deptId
+```
+
+## RDBMS Support
+
+Supports SQLite, PostgreSQL, MySQL, and Oracle.
+
+| RDBMS | Driver | Placeholder | Extras |
+| --- | --- | --- | --- |
+| SQLite | [sqlite3](https://docs.python.org/3/library/sqlite3.html) (stdlib) | `?` | — |
+| PostgreSQL | [psycopg](https://www.psycopg.org/) 3.1+ | `%s` | `sqlym[postgresql]` |
+| MySQL | [PyMySQL](https://pymysql.readthedocs.io/) 1.1+ | `%s` | `sqlym[mysql]` |
+| Oracle | [python-oracledb](https://python-oracledb.readthedocs.io/) 3.0+ | `:name` | `sqlym[oracle]` |
+
+For RDBMS other than SQLite, install with extras. The driver will be installed
+automatically.
+
+```bash
+pip install sqlym[postgresql]
+```
+
+| Feature | Description |
+| --- | --- |
+| LIKE escaping | Handles LIKE escape differences across databases |
+| IN clause limit | Splits when exceeding Oracle's 1000-element limit |
+| RDBMS-specific SQL file loading | Fallback: `find.oracle.sql` → `find.sql` |
+
+When SQL syntax differs across databases, you can provide database-specific SQL
+files:
+
+```text
+sql/employee/
+├── find.sql              # Common SQL
+├── find.oracle.sql       # Oracle-specific (loaded preferentially)
+└── find.postgresql.sql   # PostgreSQL-specific (loaded preferentially)
+```
+
+## What sqlym Does Not Provide
+
+sqlym is a SQL template engine. The following features are out of scope.
+Write SQL directly or combine with other libraries.
+
+- SQL generation (INSERT/UPDATE/DELETE/UPSERT, etc.)
+- Pagination SQL generation (`LIMIT/OFFSET`, `ROWNUM`, etc.)
+- DDL management / migrations
+- Connection management / connection pooling
+- Transaction management
+
+## Acknowledgments
+
+sqlym's 2-way SQL parser is based on the design of
+[Clione-SQL](https://github.com/tauty/clione-sql) by tauty. The four rules for
+line-based SQL processing, indent-driven parent-child relationships, and
+parameter comment syntax all originate from Clione-SQL.
+
+The dialect design and RDBMS-specific behavior handling draw from
+[Doma2](https://github.com/domaframework/doma) by the Doma Framework team.
+
+We are grateful to both projects for their pioneering work in 2-way SQL.
+
+## License
+
+MIT

sqlym-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+sqlym/__init__.py,sha256=F4CmKaMLzvkv1yJFOTb0Y0AcVFlxDfVbZXIyDNHtexI,761
+sqlym/_parse.py,sha256=i88qDRBTuUrqMFf1dZhz3GJMTBNUXt7boKISINUfHK8,917
+sqlym/config.py,sha256=D-lZeN4hITBu0dtXkfsMpn_EVzXVd-6V1cXBClhYgT4,196
+sqlym/dialect.py,sha256=0M2AUh4ouAgLICjvf8mdnWXsOiVqCAUUnHfskAOVRxs,2592
+sqlym/escape_utils.py,sha256=r5XMQpLL30T6EjzA1La6w5UmWHndcYgpy13p0OZr8Cc,1604
+sqlym/exceptions.py,sha256=fLcWKHLzsa758FY-DVA20zV3g0Hxwk3UQdEe2oFdHto,313
+sqlym/loader.py,sha256=53iYp7mS3mhy96RD4OjlQz9cTRxTT5EQYBv8RdfUN34,2617
+sqlym/mapper/__init__.py,sha256=5n7id9I-e6vcwgj-JBXvFEajpDwJWI2MHMEQSeh1gag,235
+sqlym/mapper/column.py,sha256=gQXP44kFc7_T9HHXINUL5YLk0I4d15sDn1JUKlA4Tvw,1005
+sqlym/mapper/dataclass.py,sha256=TozhN28hPiw47fEdFz008WqW9xrLo1clRijbQJE_U9s,3702
+sqlym/mapper/factory.py,sha256=zD2DVzDSnbmUoOWIeVImin5RxVvL5UgJlxPVZS-4p6Q,1266
+sqlym/mapper/manual.py,sha256=iZ_9VMABPwLz8yFMUFdehmIvoGyHs8efXOA4NGwAJN0,680
+sqlym/mapper/protocol.py,sha256=9UtYYv15BzR1kK26JznYvsXdjZfY-_UbGqKhkgTIaxc,512
+sqlym/mapper/pydantic.py,sha256=vba6K5m33nuyyCgza7LV6Mo22HndVTECzL_Y5QaxOmY,768
+sqlym/parser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlym/parser/line_unit.py,sha256=PlFCZ31O3LNQAHKzm-ccop_r2eP5bcqBuE4q9cY1dfA,796
+sqlym/parser/tokenizer.py,sha256=-eRWTt2EeEHSMV5OXtSJontmFHEDzxwJmSdaZNAwpx4,3051
+sqlym/parser/twoway.py,sha256=kg65LQw9OTefPv9VjpnOq_4Aw-AW_22Hk4NpNA68i8k,19538
+sqlym-0.1.0.dist-info/METADATA,sha256=1X3sOhCL62r-aefutL15sjHu7a152lZ9xXO5wz9I1qg,7137
+sqlym-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sqlym-0.1.0.dist-info/licenses/LICENSE,sha256=7vb-PbcXVPtaKh9PfRKbiAFPXA_zcRIfhE90vqCSF5A,1064
+sqlym-0.1.0.dist-info/RECORD,,

sqlym-0.1.0.dist-info/WHEEL

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

sqlym-0.1.0.dist-info/licenses/LICENSE

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