aio-libs / multidict / 35844764317

87%

push

github

Add a public C API capsule, with optional Cython support (#1480)

<!-- Thank you for your contribution! -->

## What do these changes do?

Adds a public C API capsule (`multidict._multidict.CAPI`, reached
through `multidict_capi.h` / `multidict_capi_struct.h`) so other C
extensions can create and manipulate `MultiDict`, `CIMultiDict`,
their proxies, and `istr` directly, without going through the
Python-level API. Covers type checks and constructors for all four
mapping types plus `istr`, `getversion()` and `len()`, and
`add()`, `clear()`, `setdefault()`, and single-item access (`in`,
`[]`, `del`, `pop()`) for the mutable types. `GetItem`, `Pop`, and
`SetDefault` follow the `PyDict_GetItemRef` / `PyDict_SetDefaultRef`
design, reporting a missing key through the return code rather than
an exception. `MultiDict_ForEach` visits every item, or just the
items for one key, through a callback, without allocating a list.

The same capsule is also reachable from Cython: `multidict/__init__.pxd`
lets third-party Cython code `cimport multidict`, mirrored by a
`multidict/_testcyapi.pyx` test harness. Cython is optional and never
a real dependency of `multidict` itself; an ordinary or release build
never sees it, and a dedicated CI job exercises the opt-in path.

## Are there changes in behavior for the user?

No behavior change for existing Python-level usage. This adds a new,
opt-in C API surface for other C extensions and Cython code to use.

## Is it a substantial burden for the maintainers to support this?

The struct only ever grows at the end, so older clients keep working
against newer `multidict` builds. The Cython binding is test-only and
opt-in, so it adds no ongoing dependency burden.

## Related issue number

Supersedes and closes #1183, #1190, #1191 (earlier C API drafts).

## Checklist

- [x] I think the code is well written
- [x] Unit tests for the changes exist
- [x] Documentation reflects the changes
- [ ] If you provide code modification, please ... (continued)

765 of 1530 branches covered (50.0%)

Branch coverage included in aggregate %.

294 of 386 new or added lines in 4 files covered. (76.17%)

7153 of 7532 relevant lines covered (94.97%)

1.9 hits per line