Phase 8-D: pme API facade & execution context refactor

[Pluglug]

Summary

Introduce api/ package as the canonical public API facade for PME. This allows external tools and user scripts to use a stable import pme interface that works regardless of the underlying package path (including Blender Extensions).

Status: Phase 8-E Complete ✅

Completed

• Phase 8-D: Basic API facade (execute, evaluate, find_pm, etc.)
• Phase 8-E: pme.props, pme.preferences, pme.dev submodule

Remaining

• Test Extensions-style package path
• Future: pme.context cleanup → pme.globals or pme.namespace
• Future: UserData enhancements (named instances, registry)

Final Public API Surface

import pme

# Execution API
pme.execute("print(C.mode)")
pme.evaluate("C.mode")

# Menu API
pme.find_pm("My Menu")
pme.list_pms()
pme.invoke_pm("My Menu")

# User Properties (NEW in 8-E)
pme.props.MyCounter = 10

# Preferences (NEW in 8-E)
pme.preferences.debug_mode = True

# Context (backward compat)
pme.context.add_global("func", func)

# Developer API (NEW in 8-E)
pme.dev.is_public("C")
pme.dev.get_stability("C")
pme.dev.namespace_report()

Autocomplete

>>> pme.
    ExecuteResult
    PMHandle
    context
    dev
    evaluate
    execute
    find_pm
    invoke_pm
    list_pms
    preferences
    props

>>> pme.dev.
    PUBLIC_NAMES
    Stability
    get_public_names_by_stability
    get_stability
    is_internal
    is_public
    namespace_report
    validate_namespace

Architecture

api/__init__.py          # Public facade (__all__ + __dir__)
api/_types.py            # ExecuteResult, PMHandle
api/dev.py               # Developer utilities (NEW)
infra/runtime_context.py # PMEContext, UserData, context
pme.py                   # Legacy shim (backward compat)

Removed from Public API (8-E)

• PMEProp, PMEProps - confused with pme.props
• schema, SchemaRegistry, SchemaProp, ParsedData - internal only
• Stability functions moved to pme.dev

References

• Design doc: _docs/design/api/pme_api_facade.md
• API reference: _docs/design/api/api.rst
• Commits: bee8938, e672503, 2c3475d

Future Work

pme.context Cleanup

# Current
pme.context.add_global("func", func)
pme.context.globals["C"]

# Future option A: pme.globals
pme.globals.add("func", func)
pme.globals["C"]

# Future option B: pme.namespace
pme.namespace.add("func", func)
pme.namespace.get("C")

UserData Enhancements

# Named instances
my_data = pme.create_user_data("my_addon")
my_data.counter = 0

# Registry
for name, data in pme.user_data_registry.items():
    print(f"{name}: {data.__dict__}")

[Pluglug]

Phase 8-E Complete 🎉

Commit: 2c3475d

New Features

• pme.props - Access user-defined properties (PropertyGroup)
• pme.preferences - Access PME addon preferences
• pme.dev - Developer utilities submodule

Cleaned Up

• Removed deprecated aliases (PMEProp, PMEProps)
• Moved schema API to internal (not user-facing)
• Moved stability functions to pme.dev
• Added __dir__() for clean autocomplete

Documentation

• _docs/design/api/api.rst - Complete API reference (RST)

Future Work (not in 8-E scope)

• pme.context cleanup → consider pme.globals or pme.namespace
• UserData enhancements (named instances, registry)