|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this |
| 4 | +repository. |
| 5 | + |
| 6 | +## What this is |
| 7 | + |
| 8 | +pyodbc is a Python module implementing the DB API 2.0 spec on top of ODBC. It is a **C++ |
| 9 | +extension** (everything in `src/` compiles into a single `pyodbc` shared library); there is no |
| 10 | +Python source for the runtime — `src/pyodbc.pyi` is only a type stub. The package targets |
| 11 | +Python 3.10+ and links against an ODBC driver manager (unixODBC/iODBC on Unix, built-in on |
| 12 | +Windows, via `odbc_config`). |
| 13 | + |
| 14 | +## Build & test |
| 15 | + |
| 16 | +Fast development loop (build in place, then run pytest from the repo root so the freshly built |
| 17 | +library is on the path): |
| 18 | + |
| 19 | +```sh |
| 20 | +python setup.py build_ext --inplace |
| 21 | +pytest tests/sqlite_test.py -vxk test_text # single test by name substring |
| 22 | +``` |
| 23 | + |
| 24 | +To debug a crash, build with tracing and pass `-s` (pytest otherwise swallows output on a |
| 25 | +segfault): |
| 26 | + |
| 27 | +```sh |
| 28 | +python setup.py build_ext --inplace -D PYODBC_TRACE |
| 29 | +pytest tests/sqlite_test.py -vxs -k test_text |
| 30 | +``` |
| 31 | + |
| 32 | +Full multi-version test matrix uses tox (`pipx install tox`), covering py310–py314: |
| 33 | + |
| 34 | +```sh |
| 35 | +tox # all interpreters + all databases |
| 36 | +tox -e py312 # one interpreter |
| 37 | +tox -e py312 -- -rA # pass pytest args after -- |
| 38 | +``` |
| 39 | + |
| 40 | +Lint: `flake8` (max line length 95; see `.flake8`) and `pylint`. Install dev deps with `pip |
| 41 | +install -r requirements-dev.txt`. |
| 42 | + |
| 43 | +### Test database configuration |
| 44 | + |
| 45 | +There is one test file per backend (`tests/sqlite_test.py`, `sqlserver_test.py`, |
| 46 | +`postgresql_test.py`, `mysql_test.py`). Each reads its connection string from an environment |
| 47 | +variable, falling back to a DSN default: |
| 48 | + |
| 49 | +- `PYODBC_SQLITE`, `PYODBC_SQLSERVER`, `PYODBC_POSTGRESQL`, `PYODBC_MYSQL` |
| 50 | + |
| 51 | +Set these in the shell or in a `pytest.ini` (with `pytest-env`); `tox.ini`'s header has an |
| 52 | +example. SQLite needs no server (`driver={SQLite3 ODBC Driver};Database=:memory:`) and is the |
| 53 | +easiest target for quick iteration. The real database must be running and the matching ODBC |
| 54 | +driver installed before tests pass — see `.github/workflows/ubuntu_build.yml` for the exact |
| 55 | +driver names and connection strings CI uses. `tests/old/` holds legacy, unmaintained test |
| 56 | +scripts; ignore them. |
| 57 | + |
| 58 | +Setting `PYODBC_TESTLOCAL=1` makes `tests/conftest.py` add the `build/` directory to |
| 59 | +`sys.path`, so you can test a `build_ext` output without pip-installing (do not have pyodbc |
| 60 | +installed in that environment if you use this). |
| 61 | + |
| 62 | +## Scratch scripts vs. project tooling |
| 63 | + |
| 64 | +Decide by **audience**, not by who happens to type the command: |
| 65 | + |
| 66 | +- **Scripts only Claude runs** — issue-repro scripts, one-off experiments, debug helpers — go |
| 67 | + in **`.claude/scratch/`**. That directory is git-ignored (`/.claude/scratch/` in |
| 68 | + `.gitignore`) and must **never** be committed. It is local scratch space, not part of the |
| 69 | + project. |
| 70 | +- **Scripts a human would ever run** (e.g. a "build + test across Python versions" convenience |
| 71 | + wrapper) are ordinary project tooling. They belong in **`utils/`** (alongside the existing |
| 72 | + `build-releases.sh`/`.cmd`), committed and reviewed like any other code with a neutral name — |
| 73 | + not in an "AI" directory. The moment a script has to be readable/maintained for a human, it |
| 74 | + is bucket two. |
| 75 | + |
| 76 | +Before writing a human-facing test runner, note that **`tox` already builds and tests across |
| 77 | +all supported Python versions** (see "Build & test"); a custom runner is only a thin |
| 78 | +convenience and often unnecessary. |
| 79 | + |
| 80 | +## Architecture |
| 81 | + |
| 82 | +Each major ODBC object is a `PyTypeObject` defined in its own `.cpp`/`.h` pair. The object |
| 83 | +lifecycle is **Connection → Cursor → Row**: |
| 84 | + |
| 85 | +- **`pyodbcmodule.cpp`** — module entry point (`PyInit_pyodbc`), the `connect()` factory, |
| 86 | + global state (the shared `HENV`, pooling, `lowercase`, ODBC version), exception class |
| 87 | + definitions, and per-thread caching of exception classes via `GetClassForThread`. |
| 88 | +- **`connection.cpp`** — the `Connection` type. Owns the `HDBC`, autocommit/transaction |
| 89 | + control, and the four `TextEnc` encodings used for the connection (read SQL_CHAR, read |
| 90 | + SQL_WCHAR, write unicode, read metadata — see "text encoding" below). Output-converter |
| 91 | + registration lives here. |
| 92 | +- **`cursor.cpp`** — the `Cursor` type (the largest/most central file). Drives |
| 93 | + `execute`/`executemany`/`fetch*`, builds the DB API `description`, the column-name→index map |
| 94 | + shared with rows, and `messages`. |
| 95 | +- **`params.cpp`** — binding Python parameters *into* SQL statements (`SQLBindParameter`), type |
| 96 | + detection, NULL handling via `SQLDescribeParam`, table-valued parameters (TVPs), and the |
| 97 | + array-binding "fast executemany" path. (Note: a header comment flags fast-executemany as |
| 98 | + being re-ported across the 4.x→5.x rewrite.) |
| 99 | +- **`getdata.cpp`** — the reverse direction: converting fetched SQL column data *out* into |
| 100 | + Python objects, including user-defined output converters (`GetUserConvIndex`). |
| 101 | +- **`row.cpp`** — the `Row` type: tuple-like, also supports access by column name via the |
| 102 | + shared name→index map, usable after the cursor/connection closes. |
| 103 | +- **`cnxninfo.cpp`** — caches per-connection-string driver capabilities (`CnxnInfo`: ODBC |
| 104 | + version, whether `SQLDescribeParam` is supported, datetime precision, type max-lengths, |
| 105 | + `need_long_data_len`) so they aren't re-probed on every connect. |
| 106 | +- **`errors.cpp`** — maps ODBC `SQLSTATE` codes to the DB API exception hierarchy |
| 107 | + (`RaiseErrorFromHandle`, `RaiseErrorV`). |
| 108 | +- **`textenc.cpp`** / **`decimal.cpp`** — text encode/decode helpers and `Decimal` support. |
| 109 | +- **`dbspecific.h`** — constants for non-standard driver types (SQL Server variant/XML/TIME2, |
| 110 | + DB2 DECFLOAT). **`wrapper.h`** — `Object`, an RAII wrapper for `PyObject*` refcounts; |
| 111 | + **`pyodbc.h`** — the umbrella header (platform shims, ODBC headers, `TRACE`). |
| 112 | + |
| 113 | +### Text encoding is the subtle part |
| 114 | + |
| 115 | +Drivers disagree wildly about Unicode, so encoding is *not* uniform. A separate `TextEnc` is |
| 116 | +configured for reading SQL_CHAR, reading SQL_WCHAR, writing unicode strings, and **reading |
| 117 | +metadata** (column names). Metadata gets its own encoding because PostgreSQL/MySQL return |
| 118 | +column names as UTF-16LE from `SQLDescribeCol` regardless of connection |
| 119 | +settings. `setencoding()`/`setdecoding()` on the Connection adjust these. The code deliberately |
| 120 | +uses `uint16_t`/`SQLWCHAR` rather than `wchar_t` because unixODBC may define `SQLWCHAR` as |
| 121 | +32-bit `wchar_t` while the buffer data is still 16-bit (see `HACKING.md`). When touching |
| 122 | +encoding code, consult `notes.txt` for the ODBC length-argument rules (count-of-characters |
| 123 | +vs. count-of-bytes). |
| 124 | + |
| 125 | +## Versioning |
| 126 | + |
| 127 | +The single source of truth for the version is the `version = "..."` line in |
| 128 | +`pyproject.toml`. `setup.py` parses it with a regex (to avoid a TOML dependency on old Pythons) |
| 129 | +and passes it to the compiler as the `PYODBC_VERSION` macro, which becomes |
| 130 | +`pyodbc.version`. cibuildwheel also reads `pyproject.toml` directly. Bump the version there |
| 131 | +only. |
0 commit comments