Export our typing

[bluetech]

This is an audit of pluggy's public API, from the perspective of typing. The idea is that every type which is reachable transitively through the public API should be exported from pluggy and have a clean documented interface (and without _ prefixes), with possible exceptions.

Note: this is different from the goal of making hook calls themselves typed. That would be great, but is a separate enhancement.

• _HookRelay - through pm.hook
  • Now pluggy.HookRelay
• TagTracer - through pm.trace
  • TODO: audit of API and transitive types
• _Plugin - type alias for a plugin object - just object.
  • Actually no need to export this.
• _Namespace - type alias for ModuleType | type
  • Actually no need to export this
• DistFacade - it is compat adapter, probably shouldn't be exported
• _HookCaller - through pm.get_hookcallers, pm.subset_hook_caller
  • Now pluggy.HookCaller
• HookSpec - through _HookCaller.spec
• HookImpl - through _HookCaller.get_hookimpls
• _HookSpecOpts - through pm.parse_hookspec_opts
  • Now pluggy.HookSpecOpts
• _HookImplOpts - through pm.parse_hookimpl_opts
  • Now pluggy.HookImplOpts
• _BeforeTrace, _AfterTrace - type aliases, in pm.add_hookcall_monitoring
  • No need to export
• _Result - in old-style wrappers
  • Now pluggy.Result

Other tasks are:

• Update the sphinx version we use in RTD (currently uses <2), need recent one for typing improvements
• Mark immutable fields as Final
• Mark non-subclassable classes @final
• Make private contstructors of public types private/hidden
• Document all public types in the API reference

[RonnyPfannschmidt]

id like to recommend deprecating the current tracing/tagtracing and trying to get rid of them

my understanding is that the api in there was a initial attempt at observability from >15 years ago and missmatches any type of current best practice

i believe pytest is the only place where its used in the internals to do debug tracing

if we export it wed have to keep it, and i would like to strongly avoid that

that being said opentracing completely fails to provide performant and simple local apis while eliot lacks any way of deeper integration

[bluetech]

@RonnyPfannschmidt OK, I'll not document the tracing types for now, though it's already documented here.