pybind / pybind/pybind11-stubgen

On using `pybind11_stubgen`-defined classes in generated stubs

Open
#200 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
361
Forks
75
PR merge metrics
No merged PRs in 30d

Description

Is there a specific philosophy that this repo has about using pybind11_stubgen-defined classes in the generated stubs?

At the moment, I see that this is done mainly for --numpy-array-wrap-with-annotated with pybind11_stubgen.typing_ext.FixedSize and pybind11_stubgen.typing_ext.DynamicSize("m", "n"), although I am also seeing it in #199.

My main concern with not making this choice explicit is that a lot of projects incorporating pybind11_stubgen into their builds might only include pybind11_stubgen as a build dependency and not as a required dependency of the whole project. This would mean users installing these projects would not have pybind11_stubgen installed, and type checkers would fail to resolve these expressions, in part or in full.

There are a few non-mutually exclusive options that I can think of:

  1. Do not use pybind11_stubgen-defined classes at all in generated stubs. I think this is the safest default approach.
  2. Inject definitions for these pybind11_stubgen-defined classes into the generated stubs. Maybe as Protocols? Would this mean re-defining a FixedSize protocol in every file it is used in?
  3. Allow importing from pybind11_stubgen, with the user explicitly acknowledging that they must mark pybind11_stubgen as a required dependency of their project in order to fully utilize the generated stubs.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing how generated stubs handle --numpy-array-wrap-with-annotated and the related discussion in issue #199. Compare the three dependency and definition options raised here, then establish which policy the project wants. Done means the policy and its effect on generated stubs and downstream dependencies are explicit.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.