metaclass-registry Documentation

Zero-boilerplate metaclass-driven plugin registry system with lazy discovery and caching

Contents:

• Quick start guide
  • Installation
  • Preferred nominal-family workflow
  • Explicit RegistryConfig workflow
  • Secondary registries are derived indexes
  • Next steps
• API orientation
  • Core declarations
• Examples
  • Basic Plugin System
  • Microscope Handler System
  • Storage Backend System
  • Custom Key Extractor
  • Multi-Level Inheritance
• Registry Patterns
  • Pattern A: Metaclass Registry (AutoRegisterMeta)
  • Pattern B: Service Pattern
  • Pattern C: Functional Registry
  • Pattern D: Manual Registration
  • Comparison Table
  • Advanced Pattern A Features
  • Migration Guide
  • Best Practices

Overview

metaclass-registry is a Python library that provides a reusable metaclass infrastructure for creating automatic plugin registration systems. It eliminates the need for custom metaclasses and manual registry management by providing a configuration-driven approach that works out of the box.

Key Features

• Zero Boilerplate: No custom metaclasses, no manual registry creation, just class attributes

• Lazy Discovery: Plugins discovered automatically on first access

• Registry Inheritance: Child classes inherit parent’s registry for clean interface hierarchies

• Secondary Registries: Auto-populate related registries from primary registry

• Persistent Caching: Cache discovery results across process restarts

• Auto-Configuration: Automatic inference of discovery packages and recursive settings

• Nominal Families: Explicit stable key axes through RegistryFamily and RegistryKeyAttribute

• Registered Enums: RegisteredEnumMeta composes enum and registry semantics

• Type-Safe: Full type hints and mypy support

Installation

pip install metaclass-registry

Quick Example

from metaclass_registry import AutoRegisterMeta, RegistryFamily

# Declare the nominal family and the attribute that owns its keys.
class PluginBase(metaclass=AutoRegisterMeta):
    __registry_family__ = RegistryFamily(
        "plugin_name",
        registry_name="plugin",
    )
    plugin_name = None

# Access the auto-created registry
PLUGINS = PluginBase.__registry__

# Define plugins - they auto-register!
class MyPlugin(PluginBase):
    plugin_name = 'my_plugin'

    def run(self):
        return "Hello from my plugin!"

# Use the registry
print(list(PLUGINS.keys()))  # ['my_plugin']
plugin = PLUGINS['my_plugin']()
print(plugin.run())  # "Hello from my plugin!"

Indices and tables

• Index

• Module Index

• Search Page