apm-agent-python icon indicating copy to clipboard operation
apm-agent-python copied to clipboard

Documentation uses reexports that are not included in `__all__`

Open linde12 opened this issue 11 months ago • 1 comments

Describe the bug: The documentation for this library references decorators like @elasticapm.capture_span() or functions (e.g. elasticapm.instrument()) however they are not included in the __all__ variable. This causes type checkers (e.g. pyright/mypy) to complain because they expect explicit reexports via __all__. What's weird is that __all__ is defined, but the intended reexports (at least from looking at the documentation) are not added.

This makes it extremely confusing for someone that is new elasticapm, and the code becomes littered with# pyright: ignore comments or imports from various subpackages.

To Reproduce

  1. Install pyright
  2. Follow documentation (e.g. use a capture_span like so https://www.elastic.co/guide/en/apm/agent/python/current/instrumenting-custom-code.html#instrumenting-custom-code-spans)
  3. Verify that pyright will complain that "capture_span" is not exported from module "elasticapm" (Pyright reportPrivateImportUsage)

Environment (please complete the following information)

  • Agent version: 6.23.0

linde12 avatar Jan 17 '25 10:01 linde12

That's strange, __all__ specifies the stuff you can import with * not what is exported https://docs.python.org/3/tutorial/modules.html#importing-from-a-package

xrmx avatar Jan 17 '25 10:01 xrmx