Allows custom signatures for #[getter] and #[setter] in order to provide type hints by varchasgopalaswamy · Pull Request #5738 · PyO3/pyo3

varchasgopalaswamy · 2026-01-16T20:17:38Z

Without the automatic type stub generation, it makes sense that the signature of getters and setters should not be overriden. However, with stub generation there can be a need to provide custom type hints. This PR relaxes the requirement that custom signatures not be allowed for getters and setters to enable this use case.

Tpt

Thank you for this!

Allowing signature might be slightly confusing to the user: the getter/setter are not exposed as method to cpython so things like argument name do not exist outside of stub generation. But indeed, it would be very convenient for stubs.

It might be nice to have some testing:

add a class with such custom signature in pytests/src/pyclasses.rs to generate the stubs and check they are valid (run nox -s test-introspection to run the introspection tests)
maybe make sure very wrong signatures (e.g. extra arguments) are still prevented by the macro with a compile error test in pyo3/tests/test_compile_error.rs

Tpt · 2026-01-16T20:54:55Z

pyo3-macros-backend/src/method.rs

    if let Some(text_signature) = text_signature {
        match fn_type {
-            FnType::Getter(_) => {
-                bail_spanned!(text_signature.kw.span() => "`text_signature` not allowed with `getter`")


Do we have a use case for text_signature? I don't think it's even possible to expose them to cpython

Reverted it! I didn't quite realize the difference between text_signature and signature.

varchasgopalaswamy · 2026-01-16T21:07:32Z

Allowing signature might be slightly confusing to the user: the getter/setter are not exposed as method to cpython so things like argument name do not exist outside of stub generation. But indeed, it would be very convenient for stubs.

A fair point, but I guess the alternative would be another attribute macro? I thought about it, but I reasoned that the tradeoff is the mental load of remembering more attribute names would be worse.

I'll push up some tests when I get some more free time!

Tpt · 2026-01-16T21:08:46Z

I thought about it, but I reasoned that the tradeoff is the mental load of remembering more attribute names would be worse.

Yes! Agreed.

I'll push up some tests when I get some more free time!

Thank you!

Icxolu · 2026-01-16T22:45:12Z

I'm not sure we should so this if we can not make it work the same as for other functions as well. I feel like it would be very surprising if one for example specifies a signature with a default value which is then not respected, or overwriting a text_signature which is then not exposed to Python. Additionally these do not accept arbitrary signatures, so we would to cover that as well.

I feel like a general mechanism to override/adapt the type hints would be a better fit for this functionality. That would make it clear that it only affects type hint generation and not runtime behavior.

varchasgopalaswamy · 2026-01-16T23:00:04Z

@Icxolu that's also a fair point. But doesnt signature already check to make sure that it's consistent with the function it's applied to? Getters and setters do not have arguments other than self, so you should get a compiler error when that happens, no?

The cost of adding a new attribute would then be having multiple ways to specify the same thing, which I think is something python gets right in strongly recommending against. By this I mean that signature already allows one to specify type hints, so if we add e.g. hints, that's two ways to specify type hints.

Should it only work on getters/setters? I think that would be quite counter intuitive
Should it be mutually exclusive with signature? I think that's acceptable, if a little clunky
Should it override/be overriden by signature? I think that's a bad idea
Should signature not take type hints? I think that's also not great, since it's not how python would work and I think be annoying for people coming from python

Icxolu · 2026-01-16T23:36:16Z

But doesnt signature already check to make sure that it's consistent with the function it's applied to? Getters and setters do not have arguments other than self, so you should get a compiler error when that happens, no?

It does that for normal functions, but it might not do it for these, because it currently can't be placed there. Also a setter does have a second argument, namely the value to be set.

The cost of adding a new attribute would then be having multiple ways to specify the same thing, which I think is something python gets right in strongly recommending against. By this I mean that signature already allows one to specify type hints, so if we add e.g. hints, that's two ways to specify type hints.

I generally agree that we should not offer competing ways to do the same thing. These are all good questions and I don't have direct answer to which is best. I just think that we may need to explore some designs here first, especially since stub generation is still pretty experimental.

davidhewitt · 2026-01-18T15:07:34Z

What's the use case when this is needed?

For types exposed by PyO3, the type hints should hopefully be good enough. For custom types, maybe a FromPyObject or IntoPyObject implementation just needs the TYPE_HINT constant applied there? Doing it on the traits would hopefully make all functions have the right hint without needing to override their signatures one by one.

Tpt · 2026-01-18T15:46:14Z

For types exposed by PyO3, the type hints should hopefully be good enough

There is likely still a small need when the field type is something like Py<PyAny> even if it's actually only a very specific Python type. But 100% agreed that for most cases the built-in type hint generation should be enough.

An other option is to encourage users to use a "new type" approach, writing struct MyType(Py<PyAny>) and implement FromPyObject and IntoPyObject on them (or PyTypeCheck?), removing the need for this pattern. But it would be a bit inconsistent with regular functions that allow custom type annotations in their signatures.

davidhewitt · 2026-01-19T10:11:38Z

Agreed.

For what it's worth, I think I'm ok with having #[pyo3(signature)] permitted for #[getter] and #[setter], as long as we have full checks to enforce that the signature makes sense.

varchasgopalaswamy · 2026-01-20T18:14:09Z

What's the use case when this is needed?

My use case is exactly what @Tpt laid out. I'm returning a Py<PyAny> (actually, it's exactly what I asked a question about a month ago! #5675) that is only meant for the python side of the application to use. I recognize this is not a common use case and that it would be preferable in most cases to have pyo3 infer the type.

For what it's worth, I think I'm ok with having #[pyo3(signature)] permitted for #[getter] and #[setter], as long as we have full checks to enforce that the signature makes sense.

Great! I'll work on some tests for this over the next few weeks when I get some free time to do so.

…ub.com/varchasgopalaswamy/pyo3 into introspection-allow-property-signature

… and made the test for stub generation a little easier to look at

…etters and setters

varchasgopalaswamy · 2026-02-04T20:13:20Z

@Tpt Could you take a look at the updates I've made when you have some time?

Added a test to make sure the auto-generated and manually-specified stubs are correct.
I also found the error message from pyo3-introspection/tests/test.rs to be really difficult to understand since it dumps the entire expected/recieved stub as a single line each, so I changed it to produce a diff instead.
Added a test into test_compile_errors.rs that checks the cases where a getter has an argument, a setter has multiple arguments, no arguments, or a badly named argument.

Let me know if you want anything else!

Tpt

Thank you for this work.

It looks good to me. I just would like to get an approval from @davidhewitt if he is fine with having custom signatures on getter/setter and with the additional dev dependencies

Tpt · 2026-02-04T20:33:10Z

pyo3-introspection/tests/test.rs

                    .strip_prefix(base_dir_path)?
                    .into(),
-                fs::read_to_string(entry.path())?,
+                format_with_ruff(&fs::read_to_string(entry.path())?)?,


All stubs file checked out in the repository should be already formatted with ruff (there is a CI job for that)

Tpt · 2026-02-04T20:33:38Z

pyo3-introspection/tests/test.rs

+            similar::TextDiff::from_lines(&expected_file_content_fixed, &actual_file_content_fixed);
+        if diff
+            .iter_all_changes()
+            .any(|f| f.tag() == similar::ChangeTag::Delete || f.tag() == similar::ChangeTag::Insert)


I guess we can do it more simply with just expected_file_content_fixed == actual_file_content_fixed

Tpt · 2026-02-04T20:34:23Z

pyo3-introspection/tests/test.rs

+                    print!("{}{}", style.apply_to(sign).bold(), style.apply_to(change));
+                }
+            }
+            panic!(


Sometime cargo test do not display what is written to stdout. What about inserting the diff in the panic message (line jump are fine there)

relax requirements on signature overrides

e76816f

Tpt reviewed Jan 16, 2026

View reviewed changes

varchasgopalaswamy and others added 6 commits February 4, 2026 13:40

Merge branch 'PyO3:main' into introspection-allow-property-signature

73f9ae0

disable text sig

2b6633c

Merge branch 'introspection-allow-property-signature' of https://gith…

a6b7d90

…ub.com/varchasgopalaswamy/pyo3 into introspection-allow-property-signature

added a test for manual signature generation for getters and setters,…

18f5217

… and made the test for stub generation a little easier to look at

added check to make sure automatic stub generation still works with g…

63fcc50

…etters and setters

added tests for bad signature specifications for getters and setters

ab00724

Tpt reviewed Feb 4, 2026

View reviewed changes

better checks and messaging

ef664f2

Conversation

varchasgopalaswamy commented Jan 16, 2026

Uh oh!

Tpt left a comment

Choose a reason for hiding this comment

Uh oh!

Tpt Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

varchasgopalaswamy Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

varchasgopalaswamy commented Jan 16, 2026

Uh oh!

Tpt commented Jan 16, 2026

Uh oh!

Icxolu commented Jan 16, 2026

Uh oh!

varchasgopalaswamy commented Jan 16, 2026

Uh oh!

Icxolu commented Jan 16, 2026

Uh oh!

davidhewitt commented Jan 18, 2026

Uh oh!

Tpt commented Jan 18, 2026

Uh oh!

davidhewitt commented Jan 19, 2026

Uh oh!

varchasgopalaswamy commented Jan 20, 2026

Uh oh!

varchasgopalaswamy commented Feb 4, 2026

Uh oh!

Tpt left a comment

Choose a reason for hiding this comment

Uh oh!

Tpt Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

varchasgopalaswamy Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Tpt Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

varchasgopalaswamy Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Tpt Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

varchasgopalaswamy Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

varchasgopalaswamy Feb 4, 2026 •

edited

Loading