👌 Add CoreEvent enum as argument for Sphinx.callback

[chrisjsewell]

When creating sphinx extensions (or looking at existing ones), it is always a source of annoyance/confusion trying to remember what callback events are available, what their purpose is, and also what their signatures should be.

Here I add the sphinx.events.CoreEvent enum, and allow this to be passed to Sphinx.connect, as an alternative to a str name.
This makes it easier to write and introspect extensions, and also more type safe.

I could also add @overload functions to the EventManager.callback, with specific function signatures for each of the items,
but I will wait to get feedback first.

It would also be interesting to consider using this to "auto-generate" some of https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events, but that is likely beyond the scope of this PR.
(I am definitely a fan of co-locating API documentation close to where it is implemented 😄 )

[danieleades]

Yay typesafety!

[danieleades]

we could take this further and make the CoreEvent enum the preferred approach (without breaking existing code)

Suggested change

	def connect(self, name: str | CoreEvent, callback: Callable, priority: int) -> int:
	@deprecated(reason="...")
	@overload
	def connect(self, name: str, callback: Callable, priority: int) -> int: ...
	@overload
	def connect(self, name: CoreEvent, callback: Callable, priority: int) -> int: ...
	def connect(self, name: str | CoreEvent, callback: Callable, priority: int) -> int:

[picnixz]

The deprecated decorator is only a 3.13 feature :(

[picnixz]

(In addition, you still want to connect with your own events)

[picnixz]

I think it's fine but the issue is that people would need to import the events module if they want to use the enumeration. So you should put it in a standalone module to avoid possible circular imports.

On the other hand, you could instead use Literal strings maybe? it could probably help if you want overloads since enumerations + literals are not happy together sometimes (I had an issue with that but I don't remember whether it's fixed or not).

[AA-Turner]

We've significantly improved typing and documentation for app.connect() (largely thanks to Chris), and I would prefer to keep the simpler string interface over an enum, so I'll close this PR.

A

[timhoffm]

Would it solve the issue if we could use StrEnum (python>=3.11)? That should make usage of strings and the enum largely interchangable, i.e. anybody who wants type safety can use the enum, and anybody who prefers the simplicity of strings can use them.