Skip to content

Technical Design — Naming Refactor (Replace “BasicX”)

Status: Proposed Owner: Reflection maintainers Last updated: 2025-09-27

Goals

  • Replace “BasicX” names with clear, expressive names that convey behavior and intended default usage.
  • Perform direct renames/removals (alpha-stage, no external consumers).

Non-goals

  • Changing public Protocol names (unless necessary for clarity).
  • Behavioral changes beyond class renames and minor doc clarifications.

Proposed naming

  • BasicImportResolver -> PythonImportResolver (expresses runtime import semantics)
  • BasicScanner -> PackageScanner (focus on package/module scanning)
  • BasicTypeResolver -> RuntimeTypeResolver (clarifies runtime object -> TypeInfo)
  • BasicCallableInvoker -> SafeCallableInvoker (clarifies safe binding/invocation)
  • BasicInstanceFactory -> TypeInstanceFactory (clarifies purpose)
  • BasicAnnotationProvider -> DecoratorAnnotationProvider (clarifies origin)
  • BasicTypeHintProvider -> SimpleTypeHintProvider (contrasts with HighFidelity)

Public API approach

  • Rename classes and update all imports/usages across the codebase and tests.
  • Remove the old symbols entirely; no alias shims and no deprecation period.
  • Update docs and examples in the same change.

Testing

  • Ensure tests and examples use the new names exclusively.
  • Add a smoke test to import the top-level package and instantiate the renamed classes.

Risks

  • Missed import updates causing breakage. Mitigation: project-wide search/replace and CI runs.
  • Name bikeshedding. Mitigation: finalize the naming table above and hold to it.

Acceptance criteria

  • New names exported; old names removed from the codebase.
  • README and docs updated with new names and examples.
  • Tests green with only the new names present.