CodeVetter · Repo Unpack · Contributor handoff
sqlalchemy/sqlalchemy
Begin with the package configuration and the subsystem's public entrypoint, then follow the execution path into its state owners. Keep dialect behavior, Core execution, ORM state management, and async adaptation distinct when choosing an edit location. Tests and CI were inspected, not executed; the suggested checks are future actions requiring authorization and suitable database environments. Treat this brief as a bounded source map and verify new facts against the pinned repository before widening scope.
- Read pyproject.toml and setup.py before packaging changes: lib is the package root, version comes from sqlalchemy.__version__, Python >=3.11 is required, and Cython builds have explicit enable/require controls.
- For engine changes, first read create_engine, Connection.execute, _execute_clauseelement, and _execute_context; these separate configuration, parameter validation, compilation, and transaction initiation.
- For persistence changes, read Session._flush, UOWTransaction.execute, and persistence._save_obj together; preserve dependency ordering and distinguish flush work from the outer transaction commit.
- A failed flush leaves a rollback requirement, and commit normally expires mapped state; transaction regressions should cover recovery and object lifecycle rather than only emitted SQL.
- For async changes, inspect AsyncConnection.start/execute and greenlet_spawn/await_ before editing; the adapter proxies synchronous machinery and requires actual async driver work.
- When execution is authorized, begin with the matching test file, such as pytest test/engine/test_execute.py or pytest test/orm/test_transaction.py; use documented --db/--dburi selection for vendor-specific checks and Nox for broader environments.
- Follow the existing formatting tools: Black uses 79 columns, zimports handles import formatting, isort is deliberately disabled, and the pre-commit configuration includes Black, zimports, and Flake8.
- Tests and CI in this brief were inspected, not executed. Before claiming coverage, account for SQLite-only github-* sessions, capability-gated async tests, collection exclusions, and Nox cleanup that can invoke reap_dbs.py and delete its identifier file.