Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is inspired by Keep a Changelog, and the project adheres to semantic versioning where applicable.

[Unreleased]

TD-003 — ReflectionContext Surface finalization (2025-09-28) - API alignment: - ctx.invoke.construct now accepts TypeInfo and constructs via InstanceFactory. - ctx.create.instance is a thin alias to ctx.invoke.construct with identical strictness semantics. - Removed invoke.create_instance from the public surface (tests/docs updated). - Resolve semantics: - ctx.resolve.dotted returns MemberInfo | None; strict defaults to True and raises ResolveError with payload {path, partial, reason}. - Strictness policy: - strict defaults to True at the context level for invoke.call, invoke.construct, create.instance, and resolve.dotted; pass strict=False to opt out. - ScanError policy: - Defined and implemented: scan.package and scan.module raise ScanError with payload {subject, reason} when the target cannot be resolved/imported; scan.types relies on builder errors. - Error payload schemas: - ResolveError payload locked to {path, partial: list[str], reason}. - InvocationTypeError payload locked to {subject_qualname, param, expected, actual_type, actual_value_repr?}; value repr is truncated to 120 chars with trailing ellipsis. - API conformance: - Keyword-only flags enforced (strict/public_only/kinds/name_contains); arity TypeErrors propagate for positional misuse. - Context-level strict default verified across resolve.dotted and invoke/create. - Tests and docs updated accordingly.

Milestone 5 follow‑ups: type‑hints fidelity, observability, configuration

  • Standardized error payloads for TypeHintResolutionError
  • subject (object), subject_qualname (str), slot (str|None), token (str|None), attempted (list[str])
  • Structured logging under logger name loryth.common.reflection
  • DEBUG events: get_type_hints_first_fail, tokens, import_attempt, sibling_attempt, sibling_reuse, get_type_hints_retry_fail, get_type_hints_retry_error, unresolved
  • Property/field precedence clarified and documented
  • Properties: getter > setter(value param) > class‑level > module‑level (toggle)
  • Fields: class‑level preferred; module‑level consulted only when allow_module_level_fallback=True and class lacks its own annotation
  • Toggle: allow_module_level_fallback (default True)
  • Option: cache_key_strategy = "identity" (default) or "canonical"
  • canonical builds stable keys across wrapper rebuilds (module + qualname + provider config dimension)
  • Clarified alias semantics in tolerant mode
  • Semantic equivalence guaranteed; exact alias branding not required
  • Preserved exactly: Annotated metadata, PEP 604 unions (|)
  • Documentation additions:
  • Type Hints Provider Guide (behavior, config, examples)
  • Observability Guide (logging, how to enable/verify; optional metrics note)
  • Migration Notes (how to upgrade, toggles, detection of unresolved markers)

Links

  • See ../users/guides/type-hints-provider-guide.md
  • See ../users/guides/observability-guide.md
  • See ../notes/deprecated/migration-notes-m5.md

[Unreleased] - Reflection naming refactor finalized (2025-09-27)

Summary - Finalized renaming of default reflection classes to behavior-expressive names. Old names removed without deprecation (alpha policy). - Source files renamed to match class names. - README and docs updated; added smoke test for top-level imports.

Before -> After mapping - BasicImportResolver -> PythonImportResolver - BasicScanner -> PackageScanner - BasicTypeResolver -> RuntimeTypeResolver - BasicCallableInvoker -> SafeCallableInvoker - BasicInstanceFactory -> TypeInstanceFactory - BasicAnnotationProvider -> DecoratorAnnotationProvider - BasicTypeHintProvider -> SimpleTypeHintProvider

Migration - Update imports to use loryth.common.reflection top-level exports for the new names. - No compatibility aliases provided.