# Add a new \`ApiMisuseException\`

**URL:** <https://discuss.python.org/t/add-a-new-apimisuseexception/78826>\
**Category:** Core Development\
**Created:** [January 30, 2025, 9:42am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826 "2025-01-30T09:42:10Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![markshannon](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/markshannon/32/72_2.png) [@markshannon](https://discuss.python.org/u/markshannon)\
**Post date:** [January 30, 2025, 9:42am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/1 "2025-01-30T09:42:10Z")

</div>

We currently raise `SystemError` for a variety of API misuses. This is misleading to users and results in spurious bug reports to CPython.

I think we should add an `ApiMisuseException` for this, and keep `SystemError` for actual system errors.

Some examples where `ApiMisuseException` would replace `SystemError`:

- A builtin function returns non-NULL and sets the exception _or_ returns NULL and does not set the exception.
- `PyBytes_FromStringAndSize`, `PyUnicode_FromStringAndSize`, etc. is called with a negative size
- `PyFile_WriteString` is called with a `NULL` file
- `PyUnicode_New` is called with an invalid character
- One of the `PyArg_Parse` variants is passed an invalid formats or arguments

There are, no doubt, other examples.

---

<div class="post-metadata">

**Author:** ![davidhewitt](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/davidhewitt/32/3502_2.png) [@davidhewitt](https://discuss.python.org/u/davidhewitt)\
**Post date:** [January 30, 2025, 9:56am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/2 "2025-01-30T09:56:29Z")

</div>

This would be nice for downstream projects like PyO3, where we could likely assume that any such `ApiMisuseException` in packages implemented in Rust is indicative of a bug in PyO3 🙂

---

<div class="post-metadata">

**Author:** ![mgorny](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mgorny/32/34029_2.png) [@mgorny](https://discuss.python.org/u/mgorny)\
**Post date:** [January 30, 2025, 10:24am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/3 "2025-01-30T10:24:07Z")

</div>

I dare say that’s what normally qualifies as an “assertion error”, but I suppose it makes sense to keep it separate from explicit user assertions.

---

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [January 30, 2025, 10:47am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/4 "2025-01-30T10:47:25Z")

</div>

+1, but to bikeshed…: _which API_ was misused?  
Perhaps name it `BadInternalCall` (after [the function](https://docs.python.org/3.8/c-api/exceptions.html?highlight=internalcall#c.PyErr_BadInternalCall)). Perhaps slightly incorrect (it’s not always a _call_), but more obviously related to the (interpreter) internals.

---

<div class="post-metadata">

**Author:** ![philthompson](https://avatars.discourse-cdn.com/v4/letter/p/ed8c4c/32.png) [@philthompson](https://discuss.python.org/u/philthompson)\
**Post date:** [January 30, 2025, 11:25am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/5 "2025-01-30T11:25:58Z")

</div>

What about 3rd party extension modules (arguably a more likely source of  
bad API calls)?

---

<div class="post-metadata">

**Author:** ![da-woods](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/da-woods/32/7507_2.png) [@da-woods](https://discuss.python.org/u/da-woods)\
**Post date:** [January 30, 2025, 11:43am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/6 "2025-01-30T11:43:24Z")

</div>

> [@philthompson](#):
>
> What about 3rd party extension modules (arguably a more likely source of  
> bad API calls)?

I think that’s the point - it would mostly be third-party extensions that trigger this exception. And Mark’s (probably optimistic) hope its that people would report the bugs to the authors of those extensions rather than to the authors of Python.

---

<div class="post-metadata">

**Author:** ![storchaka](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/storchaka/32/217_2.png) [@storchaka](https://discuss.python.org/u/storchaka)\
**Post date:** [January 30, 2025, 2:06pm UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/7 "2025-01-30T14:06:02Z")

</div>

What are examples of `SystemError` which are not API misuses? Would not be easier and more compatibly to add `InternalSystemError` for such cases if there are any?

---

<div class="post-metadata">

**Author:** ![ZeroIntensity](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/zerointensity/32/39016_2.png) [@ZeroIntensity](https://discuss.python.org/u/ZeroIntensity)\
**Post date:** [January 30, 2025, 2:25pm UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/8 "2025-01-30T14:25:48Z")

</div>

Re: [The `SystemError` description is misleading · Issue #129407 · python/cpython · GitHub](https://github.com/python/cpython/issues/129407)

I think it makes sense to add a separate exception, but I’m a bit concerned about what weird things we might break by changing exception types (_e.g._, will tests start failing because they were expecting `SystemError`?)

Another interesting case to think about is extensions that themselves expose ABIs; in the past, I’ve raised `SystemError` from [pyawaitable](https://github.com/ZeroIntensity/pyawaitable) to denote misuse, but in practice, that caused some confusion. It would be quite helpful if a new exception could be used for extension ABIs instead of `SystemError`.

> [@encukou](#):
>
> Perhaps name it `BadInternalCall` (after [the function](https://docs.python.org/3.8/c-api/exceptions.html?highlight=internalcall#c.PyErr_BadInternalCall)). Perhaps slightly incorrect (it’s not always a _call_), but more obviously related to the (interpreter) internals.

Adding on the bikeshedding: I like something along the lines of `NativeError` more than `BadInternalCall`–IMO, we should preferably keep the phrase “internal” out of the exception if it wasn’t caused by the core.

---

<div class="post-metadata">

**Author:** ![steve.dower](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/steve.dower/32/56_2.png) [@steve.dower](https://discuss.python.org/u/steve.dower)\
**Post date:** [January 30, 2025, 2:45pm UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/9 "2025-01-30T14:45:45Z")

</div>

> [@storchaka](#):
>
> Would not be easier and more compatibly to add `InternalSystemError` for such cases if there are any?

My initial thinking is that this is the more compatible way to do it. Any `SystemError` that’s entirely internal can be a subclass of `SystemError`, which can be distinguished by handlers that care but still be handled by those that don’t.

But I suspect we don’t actually have any internal ones, as we tend to rely on plain old assertions for cases where we are sure we control the inputs. So perhaps we just need to document it more clearly?

---

<div class="post-metadata">

**Author:** ![gpshead](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/gpshead/32/54_2.png) [@gpshead](https://discuss.python.org/u/gpshead)\
**Post date:** [January 30, 2025, 11:05pm UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/10 "2025-01-30T23:05:16Z")

</div>

If we had a way to often detect if the likely cause of the error (just the C caller?) is “internals” vs “non-internals” code we could even differentiate by subtypes… being correctish even 90% of the time here is probably useful?

---

<div class="post-metadata">

**Author:** ![brettcannon](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/brettcannon/32/34895_2.png) [@brettcannon](https://discuss.python.org/u/brettcannon)\
**Post date:** [January 30, 2025, 11:07pm UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/11 "2025-01-30T23:07:52Z")

</div>

> [@markshannon](#):
>
> I think we should add an `ApiMisuseException`

FYI this doesn’t follow PEP 8 as it [says to capitalize acronyms](https://peps.python.org/pep-0008/#descriptive-naming-styles).

---

<div class="post-metadata">

**Author:** ![storchaka](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/storchaka/32/217_2.png) [@storchaka](https://discuss.python.org/u/storchaka)\
**Post date:** [January 31, 2025, 8:25am UTC](https://discuss.python.org/t/add-a-new-apimisuseexception/78826/12 "2025-01-31T08:25:29Z")

</div>

Actually, I encountered one case of an internal SystemError 2 years ago. [SystemError in re.match with a "\*+" pattern · Issue #101955 · python/cpython · GitHub](https://github.com/python/cpython/issues/101955)

```python
            PyErr_SetString(PyExc_SystemError,
                            "The span of capturing group is wrong,"
                            " please report a bug for the re module.");

```

It clearly states that it is is an internal error. But I don’t think that there are many such cases. The internals are mostly bug-free, and consistency checks are usually implemented as asserts.

Even in case of genuine internal errors, it is not always possible to differentiate them from API misuse, because the internal code uses the API, so an internal bug can lead to API misuse.
