microsoft / microsoft/typeagent-py

Standardize import style (module-qualified vs direct-symbol) across the codebase

Open
#298 7 comments 0 reactions 1 assignee View on GitHub

@bmerkle is already working on this.

Since Aug 1, 2026.

Dominant language
Python
Stars
884
Forks
75
Avg merge
3h 2m
Merged PRs (30d)
2

Description

Context

Follow-up to #112, specifically the discussion started in this comment (import/naming inconsistency slows down both humans and LLM-assisted contributors trying to understand the codebase) and the detailed per-module audit in this comment (module-qualified vs. direct-symbol import style is mixed across knowledge_schema/kplib, secindex, convknowledge, propindex, reltermsindex, semrefindex, textlocindex).

AGENTS.md now documents the decision rule (added in this effort):

Default to Module-Qualified Imports: Prefer importing whole modules and using qualified calls to prevent namespace pollution, avoid name clashes, and provide immediate context for where functions or objects originate.
Use Direct Symbol Imports Cautiously: Restrict direct imports to specific scenarios: classes/exceptions/constants, avoiding severe repetitive clutter, or standard-library patterns.
Prohibit Wildcard Imports.

This issue tracks applying that rule consistently, based on an AST-based census of actual import sites across src/typeagent, tests/, and tools/.

Current state (as audited)

Module Exports Target style Compliance today
knowledge_schema (kplib) 7 classes only direct-symbol ❌ split: 20 sites alias it as kplib (10 in src, 10 in tests/tools), 32 sites already direct
secindex 1 class + 2 functions module-qualified ✅ already 100% qualified in src (6/6); tests use direct-symbol (separate, idiomatic convention)
convknowledge 1 class only either (already consistent) ✅ already 100% qualified everywhere (4/4)
textlocindex 2 classes only direct-symbol ✅ already 100% direct everywhere (5/5)
propindex (memory variant) 1 enum + 10 functions + 1 class module-qualified ❌ opposite of target: 23/25 sites are direct-symbol today
reltermsindex (memory variant) 4 classes + 3 functions module-qualified ❌ 100% direct-symbol today (14/14)
semrefindex (memory variant) 18 functions + 1 class module-qualified ❌ only 1/22 sites qualified (conversation_base.py); everything else (incl. add_messages.py, mcp/server.py, storage/memory/provider.py) is direct-symbol
propindex/reltermsindex/semrefindex (sqlite variants) 1 class each direct-symbol ✅ already 100% direct everywhere

Plan

Phase 0: Land the AGENTS.md rule itself (docs-only).

Phase 1knowledge_schema/kplib cleanup (bounded, low-risk, directly matches the issue's original complaint):

  • Convert the 20 from . import knowledge_schema as kplib + kplib.X sites to from .knowledge_schema import X, Y, Z, in src/typeagent (10 files) and in tests/tools (10 files, same mechanical fix).
  • One PR.

Phase 1b: No code changes needed — secindex, convknowledge, textlocindex are already compliant/internally consistent.

Phase 2 (deferred, separate sign-off after Phase 1 lands): reltermsindexpropindexsemrefindex, each its own PR, in that order (ascending size/centrality — semrefindex touches add_messages.py and conversation_base.py, the highest-churn files in the repo per the code-health hotspot data, so it goes last after the mechanical pattern is validated on the smaller modules).

Scope decision: test/tool files get the mechanical kplib-alias fix (Phase 1) since it's zero-risk, but Phase 2's function-import style is not forced onto test files — importing a function directly to call it in an assertion is idiomatic pytest style and is being treated as its own justified exception, independent of what src/typeagent does.

Non-goals

This issue is about import style consistency only. Actually renaming modules (the original ask in #112, e.g. secindex → something more descriptive) is separate and still awaiting a draft rename list, per gvanrossum's request in #112.

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.