Remove __all__ declarations from src/utils modules

Open Beginner friendly
#221 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
84/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Start by opening each listed module: src/utils/conf_path.py, logging_levels.py, observability.py, safe_serialization.py, and trace_logging.py, and remove their all blocks. Then verify pyproject.toml [tool.mypy] and import conventions in these modules, especially where observability and conf_path re-export imported names. Run pytest tests/unit, mypy, pylint, and black --check as stated in acceptance. The issue is done when no all remains in those five files and all checks pass.

Written by the indexing model from the issue text.

Description

refactoring type:tech-debt
Description of Technical Debt

Five modules under src/utils/ end with an __all__ declaration:

Module Line Names
src/utils/conf_path.py 90 4
src/utils/logging_levels.py 71 3
src/utils/observability.py 217 16
src/utils/safe_serialization.py 87 1
src/utils/trace_logging.py 53 1

__all__ controls exactly one thing: which names from module import * binds. There is no import * anywhere in src/ or tests/, and explicit imports are the convention the codebase already follows everywhere. The declarations therefore have no effect on any current call site.

Raised in review on PR #204 and agreed by both reviewer and author.

Impact of Technical Debt
  • Maintenance with no return. Every new public name in these modules means editing a second list that nothing reads. The lists are in sync today, so the cost so far has been paid entirely in review attention rather than caught bugs.
  • Misleading signal. A reader encountering __all__ reasonably infers that star imports are expected somewhere, or that the module has a curated public surface distinct from its non-underscore names. Neither is true.
  • Inconsistent with the rest of the codebase. No other package in the project declares __all__, and it is not a pattern used in sibling Python projects, so it reads as local convention where there is none.
Category

Code Quality / Refactoring

Priority

Low - Nice to have

Proposed Solution

Delete the __all__ block from all five modules. Rely on the existing convention: a leading underscore marks a name private, everything else is importable.

Two things to confirm while doing it, both currently safe:

  1. Re-exports. src/utils/observability.py lists TRACE_LEVEL and configured_log_level, which it imports from src/utils/logging_levels.py rather than defining; src/utils/conf_path.py similarly lists CONF_DIR and INVALID_CONF_ENV. Under mypy's no_implicit_reexport an imported name is only re-exported if it appears in __all__ or is aliased. The project's mypy config (pyproject.toml [tool.mypy]) does not enable strict or no_implicit_reexport, so removal changes nothing — but if that config is tightened later, importers of those names through observability would need to import them from logging_levels instead.
  2. No star imports. grep -rn "import \*" --include=*.py src/ tests/ returns nothing. Re-run before merging in case one has been added.
Effort Estimate

< 1 hour

Dependencies / Related
  • PR #204, where this was raised
  • #193
Additional Context

Acceptance:

  • No __all__ remains under src/.
  • pytest tests/unit, mypy, pylint, and black --check all pass unchanged.
  • No import statement anywhere needs editing, which is the point: if one does, that name was relying on a re-export and should be imported from its defining module.
Dominant language
Python
Stars
4
Forks
0
Avg merge
20h 22m
Merged PRs (30d)
8

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/EventGate

All issues in AbsaOSS/EventGate

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.