elastic / elastic/apm-agent-python

Documentation uses reexports that are not included in `__all__`

Open
#2,197 1 comment 0 reactions 0 assignees View on GitHub
agent-python community triage
Dominant language
Python
Stars
431
Forks
239
Avg merge
5d 10h
Merged PRs (30d)
7

Description

**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

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the documented capture_span example with pyright, then inspect the elasticapm __all__ definition and compare it with the documented top-level decorators and functions. Done means the documented imports are explicitly exported and pyright no longer reports private-import usage.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.