Skip to content

Definition Time Guide

Guide Maps

graph LR
  prepare["__prepare__"] --> body["Class body executes"]
  body --> setname["Descriptors receive __set_name__"]
  setname --> new["PluginMeta.__new__"]
  new --> registry["Registry and signature become visible"]
flowchart LR
  question["What happens before any plugin instance exists?"] --> step["Trace the definition-time steps"]
  step --> owner["Name the owning file or hook"]
  owner --> proof["Choose the matching test or inspection route"]

Use this guide when the capstone's runtime seems clear but the class-definition behavior still feels like hidden magic. The goal is to make the definition-time sequence explicit before you reason about invocation.

Definition-time sequence

  1. PluginMeta.__prepare__ returns DefinitionNamespace.
  2. The class body executes and places fields and wrapped actions into that namespace.
  3. Descriptors receive __set_name__ and learn their storage keys.
  4. PluginMeta.__new__ gathers inherited and local fields and action specs.
  5. A constructor signature is generated from the collected fields.
  6. Concrete plugins receive their group and public plugin name.
  7. Concrete plugins are registered in the deterministic runtime registry.

Why this matters

  • duplicate tracked members are rejected during class-body execution
  • descriptors become meaningful before instance creation because names and storage keys are fixed
  • generated constructor signatures make field declarations visible to tooling
  • manifest and registry output depend on definition-time work staying deterministic

Best proof surfaces

  • tests/test_registry.py for constructor signatures, duplicate protection, and wrapped metadata
  • manifest and registry output for the public consequences of definition-time work
  • framework.py and fields.py for the owning implementation path

Best companion guides