sqlym 0.1.0__tar.gz

sqlym-0.1.0/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

sqlym-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,63 @@
+{
+	"name": "sqly",
+	"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+	"containerEnv": {
+		"PYTHONUNBUFFERED": "1",
+		"PYTHONDONTWRITEBYTECODE": "1",
+		"UV_CACHE_DIR": "/home/vscode/.cache/uv",
+		"UV_LINK_MODE": "copy",
+		"UV_PROJECT_ENVIRONMENT": "/home/vscode/.venv",
+		"UV_COMPILE_BYTECODE": "1",
+		"CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
+		"SQLY_TEST_POSTGRESQL_URL": "host=localhost port=5432 dbname=sqly_test user=sqly password=sqly_test_pass",
+		"SQLY_TEST_MYSQL_URL": "mysql://sqly:sqly_test_pass@localhost:3306/sqly_test",
+		"SQLY_TEST_ORACLE_DSN": "localhost:1521/XEPDB1"
+	},
+	"features": {
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		"ghcr.io/devcontainers/features/common-utils:2": {
+			"configureZshAsDefaultShell": true
+		},
+		"ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
+			"packages": "curl,wget,git,jq,ca-certificates,build-essential,ripgrep,fd-find"
+		},
+		"ghcr.io/va-h/devcontainers-features/uv:1": {
+			"shellAutocompletion": true
+		},
+		"ghcr.io/devcontainers/features/node:1": {},
+		"ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
+	},
+	"runArgs": [
+		"--init",
+		"--rm"
+	],
+	"hostRequirements": {
+		"gpu": "optional"
+	},
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"python.defaultInterpreterPath": "/home/vscode/.venv/bin/python",
+				"python.testing.pytestEnabled": true
+			},
+			"extensions": [
+				"ms-python.python",
+				"charliermarsh.ruff",
+				"eamodio.gitlens",
+				"tamasfe.even-better-toml",
+				"yzhang.markdown-all-in-one"
+			]
+		}
+	},
+	"remoteUser": "vscode",
+	"containerUser": "vscode",
+	"forwardPorts": [5432, 3306, 1521],
+	"initializeCommand": "mkdir -p ${localEnv:HOME}/.claude && touch ${localEnv:HOME}/.claude/CLAUDE.md && docker compose up -d --wait postgresql mysql oracle",
+	"mounts": [
+		"source=shell_history-${devcontainerId},target=/shell_history,type=volume",
+		"source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind",
+		"source=${localEnv:HOME}/.claude/CLAUDE.md,target=/home/vscode/.claude/CLAUDE.md,type=bind"
+	],
+	"postCreateCommand": "uv sync --dev",
+	"postStartCommand": "uv run pre-commit install"
+}

sqlym-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  test-sqlite:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run pytest -m "not postgresql and not mysql and not oracle" -v
+
+  test-postgresql:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: sqly
+          POSTGRES_PASSWORD: sqly_test_pass
+          POSTGRES_DB: sqly_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U sqly -d sqly_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      SQLY_TEST_POSTGRESQL_URL: postgresql://sqly:sqly_test_pass@localhost:5432/sqly_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run pytest -m postgresql -v
+
+  test-mysql:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: sqly_test_pass
+          MYSQL_USER: sqly
+          MYSQL_PASSWORD: sqly_test_pass
+          MYSQL_DATABASE: sqly_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h localhost -u sqly -psqly_test_pass"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      SQLY_TEST_MYSQL_URL: mysql+pymysql://sqly:sqly_test_pass@localhost:3306/sqly_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run pytest -m mysql -v
+
+  test-oracle:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    services:
+      oracle:
+        image: gvenzl/oracle-xe:21-slim
+        env:
+          ORACLE_PASSWORD: sqly_test_pass
+          APP_USER: sqly
+          APP_USER_PASSWORD: sqly_test_pass
+        ports:
+          - 1521:1521
+        options: >-
+          --health-cmd "healthcheck.sh"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      SQLY_TEST_ORACLE_DSN: localhost:1521/XEPDB1
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --dev
+      - run: uv run pytest -m oracle -v

sqlym-0.1.0/.gitignore

@@ -0,0 +1,134 @@
+# Claude Code
+.claude/settings.local.json
+
+# Created by https://www.toptal.com/developers/gitignore/api/linux,macos,visualstudiocode,vim,python,jupyternotebooks,venv,virtualenv
+
+### JupyterNotebooks ###
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+profile_default/
+ipython_config.py
+
+### Linux ###
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+### macOS ###
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+*.icloud
+
+### Python ###
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Packaging
+__pypackages__/
+.pdm.toml
+poetry.toml
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/
+pyrightconfig.json
+
+# Ruff
+.ruff_cache/
+
+### Vim ###
+[._]*.s[a-v][a-z]
+!*.svg
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+Session.vim
+Sessionx.vim
+.netrwhist
+tags
+[._]*.un~
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+*.vsix
+.ionide

sqlym-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.8.22
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

sqlym-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

sqlym-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

sqlym-0.1.0/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+sqly is a SQL-first database access library for Python, inspired by Java's Clione-SQL and Doma2. It provides 2way SQL parsing (SQL files remain directly executable by DB tools) and flexible row-to-object mapping.
+
+- **Language**: Python 3.10+
+- **Dependencies**: None (stdlib only); Pydantic is optional
+- **License**: MIT
+- **Status**: v1.0 implementation complete
+
+## Architecture
+
+```
+src/sqlym/
+├── __init__.py          # Public API (parse_sql, create_mapper, Column, entity, etc.)
+├── _parse.py            # parse_sql convenience function
+├── config.py            # Error message settings
+├── dialect.py           # Dialect enum (SQLITE, POSTGRESQL, MYSQL, ORACLE)
+├── escape_utils.py      # escape_like utility for LIKE clause escaping
+├── exceptions.py        # SqlyError, SqlParseError, MappingError, SqlFileNotFoundError
+├── loader.py            # SqlLoader: file-based SQL template loading (with dialect support)
+├── parser/
+│   ├── tokenizer.py     # SQL tokenizer
+│   ├── line_unit.py     # LineUnit: line-level processing unit
+│   └── twoway.py        # TwoWaySQLParser: Clione-SQL 2way SQL engine
+└── mapper/
+    ├── protocol.py      # RowMapper Protocol (runtime_checkable)
+    ├── dataclass.py     # DataclassMapper (auto-mapping with caching)
+    ├── pydantic.py      # PydanticMapper (optional)
+    ├── column.py        # Column annotation & @entity decorator
+    ├── manual.py        # ManualMapper
+    └── factory.py       # create_mapper factory function
+```
+
+### Core Concepts
+
+**Clione-SQL 4 Rules** govern the parser:
+1. SQL is processed line-by-line (LineUnit)
+2. Indentation defines parent/child relationships
+3. If all children are removed, parent is also removed (bottom-up propagation)
+4. `$`-prefixed parameters that are None cause line removal
+
+**Parameter syntax in SQL comments**:
+- `/* $name */default` — removable (None removes the line)
+- `/* name */default` — non-removable (None binds as NULL)
+- `IN /* $ids */(1,2,3)` — auto-expands list parameters
+
+**Parser pipeline**: parse lines → build tree from indentation → evaluate params & mark removal → propagate removal upward → rebuild SQL → clean dangling WHERE/AND/OR/empty parens
+
+**Mapper hierarchy** (via `create_mapper()` factory):
+- `DataclassMapper` — auto-maps using field introspection with caching
+- `PydanticMapper` — auto-detected via `model_validate()`
+- `ManualMapper` — wraps user-provided function/lambda
+
+**Column mapping priority**: `Annotated[T, Column("X")]` > `@entity(column_map={})` > `@entity(naming="...")` > field name as-is
+
+### Placeholder formats
+Supports `?` (SQLite/JDBC), `%s` (psycopg2), `:name` (Oracle) — configurable per parser instance.
+
+## Implementation Phases (from DESIGN.md)
+
+1. Parser foundation (LineUnit, line parsing, basic parameter substitution)
+2. Parser completion (line removal, IN clause expansion, SQL cleanup)
+3. Mappers (RowMapper, DataclassMapper, Column/entity)
+4. Integration (SqlLoader, public API)
+
+## Key Design Decisions
+
+- Zero external dependencies for core — Pydantic support is optional and lazy-imported
+- Protocol-based mapper interface with `@runtime_checkable` for duck typing
+- Class-level mapping cache in DataclassMapper for performance
+- Indentation carries semantic meaning (parent/child relationships for cascading removal)
+
+## Specifications
+
+- `docs/SPEC.md` — Functional specification (Japanese)
+- `docs/DESIGN.md` — Implementation design with class-level details (Japanese)

sqlym-0.1.0/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.

sqlym-0.1.0/Makefile

@@ -0,0 +1,48 @@
+.PHONY: install test lint format lint-fix pre-commit clean db-up db-down test-postgresql test-mysql test-oracle test-db test-all
+
+install:
+	uv sync --dev
+
+test:
+	uv run pytest
+
+test-cov:
+	uv run pytest --cov=sqly --cov-report=term-missing
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff format .
+
+lint-fix:
+	uv run ruff check . --fix
+
+pre-commit:
+	uv run pre-commit run --all-files
+
+db-up:
+	docker compose up -d --wait
+
+db-down:
+	docker compose down
+
+test-postgresql:
+	uv run pytest -m postgresql -v
+
+test-mysql:
+	uv run pytest -m mysql -v
+
+test-oracle:
+	uv run pytest -m oracle -v
+
+test-db:
+	uv run pytest -m "postgresql or mysql or oracle" -v
+
+test-all:
+	uv run pytest -v
+
+clean:
+	rm -rf .venv .ruff_cache .pytest_cache .coverage htmlcov dist build
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name "*.egg-info" -exec rm -rf {} +