Skip to content

chore: rename internal modules with _ prefix per Python convention #701

@planetf1

Description

@planetf1

Problem

Two modules are implementation details that don't follow Python's _ prefix convention for private modules. The _ prefix is how Python signals "this is not public API" — to users, IDEs, type checkers, and static analysis tools. This is a code hygiene issue; the fact that it was surfaced via the doc generator is incidental.

mellea/formatters/granite/intrinsics/json_util.py — used only internally within the same package. intrinsics/__init__.py does not export it. Should be _json_util.py.

mellea/telemetry/backend_instrumentation.pytelemetry/__init__.py has an explicit __all__ that does not include it, yet six backend modules import it directly via cross-package relative imports, bypassing the package interface. Should be _backend_instrumentation.py.

There is a secondary question for backend_instrumentation: should its functions (instrument_generate_from_raw, start_generate_span etc.) be exported through telemetry/__init__.py so backends access them via the package interface rather than reaching into a submodule the package doesn't expose? That would be the cleaner design but is a separate decision.

Neither name appears in any __init__.py __all__, so there is no public API breakage. All callers are internal import sites within mellea/ that need updating.

Side effect

The doc generator has a _CONFIRMED_INTERNAL_MODULES hardcoded workaround specifically because these two modules aren't _-prefixed. Once renamed, that workaround can be removed.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions