Skip to content

chore: add deprecation warnings to long-deprecated items - #6275

Open
henryiii wants to merge 3 commits into
pybind:masterfrom
henryiii:chore/deprecation-warnings
Open

henryiii wants to merge 3 commits into
pybind:masterfrom
henryiii:chore/deprecation-warnings

Conversation

@henryiii

@henryiii henryiii commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

🤖 AI text below 🤖

Description

Some items were deprecated in the docs or in comments, but gave no warning. They now give a compiler warning:

  • PYBIND11_OVERLOAD* macros (deprecated in 2.6). A macro cannot carry [[deprecated]], so each macro calls a deprecated empty function. The warning shows at the user's line, also when pybind11 is included as a system header.
  • get_overload (2.6)
  • py::arg_t (2.0)
  • py::detail::_ (2.9.1)
  • py::module_::module_def (3.0)

py::module stays, without a warning.

The deprecated features table in docs/advanced/deprecated.rst now has a replacement, version, year, and warning type for each item. Items that started to warn in 3.x are kept until at least 4.0. See the 4.0 discussion in #6270.

Suggested changelog entry:

  • Added deprecation warnings for PYBIND11_OVERLOAD*, get_overload, py::arg_t, py::module_::module_def, and py::detail::_, and filled in the table of deprecated features in the docs.

📚 Documentation preview 📚: https://pybind11--6275.org.readthedocs.build/

henryiii and others added 2 commits November 14, 2026 00:16
PYBIND11_OVERLOAD* macros, get_overload, py::arg_t,
py::module_::module_def, and py::detail::_ were deprecated without a
warning. Also fill in the deprecated features table in the docs.

Assisted-by: ClaudeCode:claude-opus-5-5
@rwgk

rwgk commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator

— codex on behalf of Ralf —

Two migration rows could use more precise signatures.

  • Name the deprecated capsule overload. The two-argument py::capsule(value, destructor) row should identify PyCapsule_Destructor (void (*)(PyObject *)). The separate two-argument overload for void (*)(void *) remains supported. That distinction lets users tell whether their existing call needs migration. Table entry · Constructor overloads
  • Spell out the typed-pointer requirement for get_override. The documented replacement needs a typed pointer so it can infer the type info. The table currently leaves that prerequisite implicit for callers migrating from get_type_overload(const void *, const detail::type_info *, const char *). Table entry · Old signature · New signature

Ralf has yet to review these findings.

@henryiii

Copy link
Copy Markdown
Collaborator Author

🤖 AI text below 🤖

Both points are correct. I checked them against the headers and with a compile test. Fixed in 10951d9.

  • Capsule overload. Only capsule(const void *, PyCapsule_Destructor) has the deprecation attribute. capsule(const void *, void (*)(void *)) gives no warning. The table row now names PyCapsule_Destructor (void (*)(PyObject *)) and says that the void (*)(void *) overload is not deprecated.
  • get_override typed pointer. get_override(const T *, name) finds the type info from T, so a const void * caller must cast to the typed pointer first. The row now shows both signatures and states this. The get_type_overload warning text did not name a replacement; it now says "use get_override instead".

@henryiii
henryiii force-pushed the chore/deprecation-warnings branch from 10951d9 to c29791f Compare November 21, 2026 18:35
The capsule row now names the PyCapsule_Destructor overload. The
get_type_overload row names get_override and the typed pointer it needs,
and the warning now names get_override.

Assisted-by: ClaudeCode:claude-fable-5-2
@henryiii
henryiii force-pushed the chore/deprecation-warnings branch from c29791f to 34c28dc Compare November 21, 2026 18:35

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants