Automatically generate `__text_signature__` for all functions #2784

davidhewitt · 2022-11-27T11:34:46Z

This PR makes it so that PyO3 generates __text_signature__ by default for all functions. It also introduces #[pyo3(text_signature = false)] to disable the built-in generation.

There are a few limitations which we can improve later:

All default values are currently set to .... I think this is ok because .pyi files often do the same. Maybe for numbers, strings, None and True/False we could render these in a future PR.
No support for #[new] yet.

Alternative design ideas:

Only autogenerate for methods with #[pyo3(signature = (...))] annotation. I started with this, and then decided it made sense to do it for everything.
Opt-out with #[pyo3(text_signature = None)]. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from text_signature = false to text_signature = None.

There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review.

adamreichold · 2022-11-27T21:15:20Z

Opt-out with #[pyo3(text_signature = None)]. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from text_signature = false to text_signature = None.

To be honest, None appears be much less surprising to me compared to false, meaning I would maybe guess None but certainly not false without reading the documentation.

pyo3-macros-backend/src/pyfunction/signature.rs

guide/src/function/signature.md

davidhewitt · 2022-12-01T20:11:58Z

Will try to change this to use None for the opt-out when I get a moment 👍

davidhewitt · 2022-12-23T08:42:41Z

bors r+

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-23T09:50:25Z

Build failed:

conclusion

davidhewitt · 2022-12-24T09:45:38Z

bors r+

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. 2813: ci: run pyo3-ffi-check using nox r=davidhewitt a=davidhewitt Makes it easier to run pyo3-ffi-check locally :) Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-24T10:20:05Z

Build failed (retrying...):

conclusion

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-24T11:26:52Z

Build failed:

conclusion

davidhewitt · 2022-12-24T21:04:19Z

bors retry

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-24T21:36:58Z

Build failed:

conclusion

davidhewitt · 2022-12-25T10:05:32Z

bors r+

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. 2827: pypy: enable `PyList::get_item_unchecked` r=davidhewitt a=davidhewitt Split out from #2826. Approved previously as part of that review. Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-25T11:08:09Z

Build failed (retrying...):

conclusion

2784: Automatically generate `__text_signature__` for all functions r=davidhewitt a=davidhewitt This PR makes it so that PyO3 generates `__text_signature__` by default for all functions. It also introduces `#[pyo3(text_signature = false)]` to disable the built-in generation. There are a few limitations which we can improve later: - All default values are currently set to `...`. I think this is ok because `.pyi` files often do the same. Maybe for numbers, strings, `None` and `True`/`False` we could render these in a future PR. - No support for `#[new]` yet. Alternative design ideas: - Only autogenerate for methods with `#[pyo3(signature = (...))]` annotation. I started with this, and then decided it made sense to do it for everything. - Opt-out with `#[pyo3(text_signature = None)]`. This is slightly harder to parse in the macro, but matches the final result in Python better, so if this looks preferable to others, I can change from `text_signature = false` to `text_signature = None`. There's some small tidying up / refactoring to do before this merges (happy to take suggestions on this), however the general logic, design and docs are ready for review. Co-authored-by: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

bors · 2022-12-25T12:11:50Z

Build failed:

conclusion

davidhewitt · 2022-12-25T19:17:04Z

bors r+

bors · 2022-12-25T20:18:48Z

Build succeeded:

conclusion

davidhewitt mentioned this pull request Nov 27, 2022

0.18 release #2785

Closed

7 tasks

davidhewitt force-pushed the auto-text-signature branch from 3c7ca8f to 226f764 Compare November 27, 2022 12:04

adamreichold reviewed Nov 27, 2022

View reviewed changes

pyo3-macros-backend/src/pyfunction/signature.rs Outdated Show resolved Hide resolved

guide/src/function/signature.md Outdated Show resolved Hide resolved

davidhewitt force-pushed the auto-text-signature branch 3 times, most recently from 426023f to 663a436 Compare December 23, 2022 08:15

add automatic text signature generation

5039fd7

davidhewitt force-pushed the auto-text-signature branch from 663a436 to 5039fd7 Compare December 24, 2022 09:43

bors bot merged commit e5ae4e2 into PyO3:main Dec 25, 2022

davidhewitt mentioned this pull request Dec 28, 2022

Autogenerate __text_signature__ #310

Closed

This was referenced Jan 6, 2023

Improve default values for automatically-generated text_signature #2863

Closed

Support text_signature and autogenerated text signature for #[new] #2866

Closed

messense mentioned this pull request Mar 16, 2023

Type annotations for functions are absent #3048

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Automatically generate `__text_signature__` for all functions #2784

Automatically generate `__text_signature__` for all functions #2784

davidhewitt commented Nov 27, 2022

adamreichold commented Nov 27, 2022

davidhewitt commented Dec 1, 2022

davidhewitt commented Dec 23, 2022

bors bot commented Dec 23, 2022

davidhewitt commented Dec 24, 2022

bors bot commented Dec 24, 2022

bors bot commented Dec 24, 2022

davidhewitt commented Dec 24, 2022

bors bot commented Dec 24, 2022

davidhewitt commented Dec 25, 2022

bors bot commented Dec 25, 2022

bors bot commented Dec 25, 2022

davidhewitt commented Dec 25, 2022

bors bot commented Dec 25, 2022

Automatically generate __text_signature__ for all functions #2784

Automatically generate __text_signature__ for all functions #2784

Conversation

davidhewitt commented Nov 27, 2022

adamreichold commented Nov 27, 2022

davidhewitt commented Dec 1, 2022

davidhewitt commented Dec 23, 2022

bors bot commented Dec 23, 2022

davidhewitt commented Dec 24, 2022

bors bot commented Dec 24, 2022

bors bot commented Dec 24, 2022

davidhewitt commented Dec 24, 2022

bors bot commented Dec 24, 2022

davidhewitt commented Dec 25, 2022

bors bot commented Dec 25, 2022

bors bot commented Dec 25, 2022

davidhewitt commented Dec 25, 2022

bors bot commented Dec 25, 2022

Automatically generate `__text_signature__` for all functions #2784

Automatically generate `__text_signature__` for all functions #2784