django-sqlalchemy-bridge 0.0.1__tar.gz

django_sqlalchemy_bridge-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+# Tag push (v*) -> build -> publish to PyPI via trusted publishing -> GitHub release.
+# PyPI side: pypi.org > Account settings > Publishing > add a pending publisher with
+# owner itda-work, repository django-sqlalchemy-bridge, workflow release.yml, environment pypi.
+# No API token is stored anywhere.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned exactly: setup-uv dropped its floating major tags in v8.
+      - uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Check the version, the CHANGELOG and the classifiers agree
+        run: python3 scripts/release_check.py "$GITHUB_REF_NAME"
+
+      - run: uv build
+      - run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing (OIDC)
+      contents: write # GitHub release
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}

django_sqlalchemy_bridge-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.sqlite3

django_sqlalchemy_bridge-0.0.1/AGENTS.md

@@ -0,0 +1,4 @@
+# django-sqlalchemy-bridge AI Guide
+
+정본은 [`CLAUDE.md`](CLAUDE.md)다. 이 파일은 `AGENTS.md`를 찾는 도구를 위한 포인터일 뿐이고,
+같은 지침을 두 곳에 두지 않는다 — 두면 어긋난다.

django_sqlalchemy_bridge-0.0.1/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-25
+
+### Added
+
+- Name reservation and design README. **Experimental** project; no public API.

django_sqlalchemy_bridge-0.0.1/CLAUDE.md

@@ -0,0 +1,21 @@
+# django-sqlalchemy-bridge AI Guide
+
+> Django 연결·트랜잭션 안에서 SQLAlchemy 2.x Core 표현식을 쓰게 하는 라이브러리. **설계 단계(0.0.x)** — 공개 API 없음.
+
+## 정본
+
+| 무엇 | 정본 |
+|------|------|
+| 의존성, 지원 Python | `pyproject.toml` |
+| 아키텍처 원칙 | `README.md` "Planned architecture" |
+| 변경 이력 | `CHANGELOG.md` |
+
+## 규약
+
+- **Django 가 연결·트랜잭션 주인이다.** SQLAlchemy `Engine`/`Connection`/`Session` 을 실행 경로에 두지 않는다. 실행은 항상 Django cursor. (2026-10-25 사전 프로브: SA 가 Django DBAPI 연결을 쥐면 `atomic()` 롤백이 무시됐다.)
+- **SQLAlchemy 공개 API 를 우선한다.** `_` 접두 내부 속성 사용 금지. 예외: 외부 행으로 SA `Result` 를 만드는 경로(공개 생성법 없음, 2026-10-25 스파이크 판정)는 어댑터 모듈 한 곳에 가두고 SA 상한을 핀해 CI 로 지킨다.
+- 스키마·마이그레이션은 Django 모델이 단일 출처.
+- 커밋 메시지는 영어 Conventional Commits. 문서는 README 포함 한국어(마스터 지시 2026-10-25). README 의 수치는 `bench/` 결과 파일이 있는 것만 싣는다.
+- 작업 큐는 GitHub 이슈다. 결함은 재현한 뒤에 말하고, 수정은 "수정 전에 실패하는 테스트"로 증명한다.
+- 남의 저장소(aldjemy 포함)에는 이슈·코멘트·PR 을 만들지 않는다. 읽기만.
+- 릴리스: `pyproject.toml` version 올림 → CHANGELOG 절 추가 → `python3 scripts/release_check.py` → `v<version>` 태그 푸시. `release.yml` 이 PyPI(trusted publishing, environment `pypi`)와 GitHub Release 에 올린다. 토큰은 저장하지 않는다.

django_sqlalchemy_bridge-0.0.1/LICENSE

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

django_sqlalchemy_bridge-0.0.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: django-sqlalchemy-bridge
+Version: 0.0.1
+Summary: [Experimental] Use SQLAlchemy 2.x Core expressions inside Django's own connections and transactions
+Project-URL: Repository, https://github.com/itda-work/django-sqlalchemy-bridge
+Author: itda-work
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: >=3.12
+Requires-Dist: django>=5.2
+Requires-Dist: sqlalchemy<2.2,>=2.0
+Description-Content-Type: text/markdown
+
+# django-sqlalchemy-bridge
+
+> ⚠️ **실험적 프로젝트입니다 (Experimental).** API·동작·지원 범위가 예고 없이 바뀔 수 있고, 운영 환경에서 쓰는 것을 권하지 않습니다.
+>
+> **상태: 설계 단계 (0.0.x).** 이름을 확보하고 설계를 공개한 버전입니다. 아직 공개 API가 없으니 의존하지 마세요.
+
+Django가 연 **연결과 트랜잭션 안에서** SQLAlchemy 2.x Core 표현식(대량 DML, CTE, 윈도 함수, 복잡한 조인)을 쓰게 해 주는 라이브러리입니다.
+
+## 왜 만드나
+
+[aldjemy](https://github.com/aldjemy/aldjemy)가 같은 문제를 먼저 풀었지만, SQLAlchemy 내부 비공개 풀 구조에 기대 Django 연결을 공유하는 탓에 SQLAlchemy 2 미만에 묶여 있습니다. Django 6.0부터는 SQLAlchemy 버전과 상관없이 모델 변환 단계에서도 깨집니다. 이 프로젝트는 다른 길을 갑니다.
+
+## 설계 원칙
+
+- **연결과 트랜잭션은 Django가 관리합니다.** SQLAlchemy는 SQL을 만들고 컴파일하는 데만 쓰고, 실행은 항상 Django 커서로 합니다. 그래서 `atomic()`, savepoint, `on_commit`, `execute_wrapper`, `assertNumQueries`, Django 연결 풀, PgBouncer 설정이 그대로 동작합니다.
+- **SQLAlchemy 공개 API를 우선합니다.** 공개 API만으로 안 되는 부분(외부에서 받은 행으로 SQLAlchemy `Result`를 만드는 경로)은 어댑터 모듈 한 곳에 가두고, 지원하는 SQLAlchemy 버전 범위를 좁게 고정해 CI로 지킵니다.
+- **테이블 구조의 기준은 Django 모델 하나입니다.** `sa.Table`은 Django 모델에서 만들고, 마이그레이션은 Django가 맡습니다.
+- **값 변환은 Django 필드를 따릅니다.** 쓸 때는 `get_db_prep_value`, 읽을 때는 Django ORM이 쓰는 변환기를 거칩니다. 그래서 JSON·UUID·시간대가 있는 datetime·Decimal·Enum이 ORM과 똑같이 왕복합니다. (SQLAlchemy 타입 변환을 그대로 쓰면 SQLite에서 시간이 9시간 밀리거나 Enum이 값 대신 이름으로 저장되는 문제가 있어 피합니다.)
+- **경계를 드러냅니다.** 브리지로 쓴 내용은 Django signal을 발생시키지 않습니다. API 이름과 문서에 이 점을 분명히 적습니다.
+
+## 비동기 (검토 중)
+
+Django의 async ORM(`aget()` 등)은 내부적으로 쿼리마다 `sync_to_async`로 스레드에 넘기는 구조이고, Django 문서도 "async 모드에서는 아직 트랜잭션이 동작하지 않는다"고 적고 있습니다.
+
+- **v0.1 방향(Django만으로):** 여러 쿼리와 `atomic()`을 묶어 스레드에 한 번만 넘기는 `atransaction()`·`aexecute()`를 제공합니다. 트랜잭션을 Django가 관리한다는 원칙을 지키면서 async 코드에서도 트랜잭션을 쓸 수 있게 합니다.
+- **검토 중인 대안:** SQLAlchemy `AsyncEngine`(별도 연결, 읽기 전용으로 명시적으로 켠 경우만)과 psycopg 3 비동기 연결 직접 사용. PostgreSQL 측정 결과를 보고 정합니다.
+
+## 성능과 메모리 (측정 중)
+
+이 README의 모든 수치는 저장소의 `bench/` 스크립트와 결과 파일로 다시 재현할 수 있을 때만 싣습니다. 측정할 항목은 아래와 같습니다.
+
+- PK 기준 대량 UPDATE: Django `bulk_update`, django-pgbulk, 브리지, SQLAlchemy ORM
+- 대량 INSERT: `bulk_create`, pgbulk `copy`, 브리지, SQLAlchemy `insert()`
+- 대량 읽기의 시간과 메모리: Django 모델 객체, `values()`, `values_list()`, 브리지, SQLAlchemy `Row`, SQLAlchemy ORM 객체
+- 쿼리 생성 오버헤드, async 경로, CTE·윈도 함수 리포트 쿼리
+
+브리지가 도움이 **안 되는** 경우(일반 CRUD, django-pgbulk로 충분한 경우)도 함께 적습니다.
+
+## 첫 지원 대상 (계획)
+
+SQLite, PostgreSQL(psycopg 3) · Django 5.2 이상 · SQLAlchemy 2.0 이상 2.2 미만 · Python 3.12 이상
+
+## 라이선스
+
+MIT

django_sqlalchemy_bridge-0.0.1/README.md

@@ -0,0 +1,45 @@
+# django-sqlalchemy-bridge
+
+> ⚠️ **실험적 프로젝트입니다 (Experimental).** API·동작·지원 범위가 예고 없이 바뀔 수 있고, 운영 환경에서 쓰는 것을 권하지 않습니다.
+>
+> **상태: 설계 단계 (0.0.x).** 이름을 확보하고 설계를 공개한 버전입니다. 아직 공개 API가 없으니 의존하지 마세요.
+
+Django가 연 **연결과 트랜잭션 안에서** SQLAlchemy 2.x Core 표현식(대량 DML, CTE, 윈도 함수, 복잡한 조인)을 쓰게 해 주는 라이브러리입니다.
+
+## 왜 만드나
+
+[aldjemy](https://github.com/aldjemy/aldjemy)가 같은 문제를 먼저 풀었지만, SQLAlchemy 내부 비공개 풀 구조에 기대 Django 연결을 공유하는 탓에 SQLAlchemy 2 미만에 묶여 있습니다. Django 6.0부터는 SQLAlchemy 버전과 상관없이 모델 변환 단계에서도 깨집니다. 이 프로젝트는 다른 길을 갑니다.
+
+## 설계 원칙
+
+- **연결과 트랜잭션은 Django가 관리합니다.** SQLAlchemy는 SQL을 만들고 컴파일하는 데만 쓰고, 실행은 항상 Django 커서로 합니다. 그래서 `atomic()`, savepoint, `on_commit`, `execute_wrapper`, `assertNumQueries`, Django 연결 풀, PgBouncer 설정이 그대로 동작합니다.
+- **SQLAlchemy 공개 API를 우선합니다.** 공개 API만으로 안 되는 부분(외부에서 받은 행으로 SQLAlchemy `Result`를 만드는 경로)은 어댑터 모듈 한 곳에 가두고, 지원하는 SQLAlchemy 버전 범위를 좁게 고정해 CI로 지킵니다.
+- **테이블 구조의 기준은 Django 모델 하나입니다.** `sa.Table`은 Django 모델에서 만들고, 마이그레이션은 Django가 맡습니다.
+- **값 변환은 Django 필드를 따릅니다.** 쓸 때는 `get_db_prep_value`, 읽을 때는 Django ORM이 쓰는 변환기를 거칩니다. 그래서 JSON·UUID·시간대가 있는 datetime·Decimal·Enum이 ORM과 똑같이 왕복합니다. (SQLAlchemy 타입 변환을 그대로 쓰면 SQLite에서 시간이 9시간 밀리거나 Enum이 값 대신 이름으로 저장되는 문제가 있어 피합니다.)
+- **경계를 드러냅니다.** 브리지로 쓴 내용은 Django signal을 발생시키지 않습니다. API 이름과 문서에 이 점을 분명히 적습니다.
+
+## 비동기 (검토 중)
+
+Django의 async ORM(`aget()` 등)은 내부적으로 쿼리마다 `sync_to_async`로 스레드에 넘기는 구조이고, Django 문서도 "async 모드에서는 아직 트랜잭션이 동작하지 않는다"고 적고 있습니다.
+
+- **v0.1 방향(Django만으로):** 여러 쿼리와 `atomic()`을 묶어 스레드에 한 번만 넘기는 `atransaction()`·`aexecute()`를 제공합니다. 트랜잭션을 Django가 관리한다는 원칙을 지키면서 async 코드에서도 트랜잭션을 쓸 수 있게 합니다.
+- **검토 중인 대안:** SQLAlchemy `AsyncEngine`(별도 연결, 읽기 전용으로 명시적으로 켠 경우만)과 psycopg 3 비동기 연결 직접 사용. PostgreSQL 측정 결과를 보고 정합니다.
+
+## 성능과 메모리 (측정 중)
+
+이 README의 모든 수치는 저장소의 `bench/` 스크립트와 결과 파일로 다시 재현할 수 있을 때만 싣습니다. 측정할 항목은 아래와 같습니다.
+
+- PK 기준 대량 UPDATE: Django `bulk_update`, django-pgbulk, 브리지, SQLAlchemy ORM
+- 대량 INSERT: `bulk_create`, pgbulk `copy`, 브리지, SQLAlchemy `insert()`
+- 대량 읽기의 시간과 메모리: Django 모델 객체, `values()`, `values_list()`, 브리지, SQLAlchemy `Row`, SQLAlchemy ORM 객체
+- 쿼리 생성 오버헤드, async 경로, CTE·윈도 함수 리포트 쿼리
+
+브리지가 도움이 **안 되는** 경우(일반 CRUD, django-pgbulk로 충분한 경우)도 함께 적습니다.
+
+## 첫 지원 대상 (계획)
+
+SQLite, PostgreSQL(psycopg 3) · Django 5.2 이상 · SQLAlchemy 2.0 이상 2.2 미만 · Python 3.12 이상
+
+## 라이선스
+
+MIT

django_sqlalchemy_bridge-0.0.1/django_sqlalchemy_bridge/__init__.py

@@ -0,0 +1,13 @@
+"""django-sqlalchemy-bridge — design stage, no public API yet.
+
+See README.md for the planned architecture.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("django-sqlalchemy-bridge")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

django_sqlalchemy_bridge-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "django-sqlalchemy-bridge"
+version = "0.0.1"
+description = "[Experimental] Use SQLAlchemy 2.x Core expressions inside Django's own connections and transactions"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "itda-work" }]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+]
+dependencies = [
+    "django>=5.2",
+    # <2.2: building a Result from external rows has no public constructor; widen only after CI checks the new minor.
+    "sqlalchemy>=2.0,<2.2",
+]
+
+[project.urls]
+Repository = "https://github.com/itda-work/django-sqlalchemy-bridge"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["django_sqlalchemy_bridge"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

django_sqlalchemy_bridge-0.0.1/scripts/release_check.py

@@ -0,0 +1,62 @@
+"""Refuse a release whose version is not declared everywhere it has to be.
+
+Run this before tagging; release.yml runs it again with
+the tag it is building. (Copied from itda-work/channels-nats.)
+
+Deliberately dependency-free and stdlib-only, so it runs on any Python this
+project supports, including 3.10 without tomllib.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def declared_version() -> str:
+    """The one `version = "..."` line pyproject.toml is allowed to have."""
+    text = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    found = re.findall(r'^version = "(.+?)"$', text, re.MULTILINE)
+    if len(found) != 1:
+        raise SystemExit(f"pyproject.toml has {len(found)} version lines; expected exactly one")
+    return found[0]
+
+
+def problems(tag: str | None) -> list[str]:
+    version = declared_version()
+    pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+    found = []
+
+    if tag is not None and tag != f"v{version}":
+        found.append(f"tag {tag} does not match pyproject version {version}")
+
+    if re.search(r'^\s*"License :: ', pyproject, re.MULTILINE):
+        # PEP 639: PyPI rejects an upload carrying both. `twine check` does not catch it.
+        found.append("drop the 'License :: ...' classifiers; they cannot accompany License-Expression")
+
+    if f"## [{version}]" not in changelog:
+        found.append(f"CHANGELOG.md has no '## [{version}]' section")
+
+    unreleased = re.search(r"^## \[Unreleased\]\s*\n(.*?)(?=^## |\Z)", changelog, re.MULTILINE | re.DOTALL)
+    if unreleased is not None and unreleased.group(1).strip():
+        found.append(f"CHANGELOG.md still has entries under [Unreleased]; they belong in [{version}]")
+
+    return found
+
+
+def main(argv: list[str]) -> int:
+    found = problems(argv[0] if argv else None)
+    for problem in found:
+        print(f"release check: {problem}", file=sys.stderr)
+    if found:
+        return 1
+    print(f"release check: {declared_version()} is consistent")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))