metaclass-registry 0.1.0__tar.gz

metaclass_registry-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Documentation
+docs/_build/
+site/
+
+# OS
+.DS_Store
+Thumbs.db

metaclass_registry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tristan Simas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaclass_registry-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: metaclass-registry
+Version: 0.1.0
+Summary: Zero-boilerplate metaclass-driven plugin registry system with lazy discovery and caching
+Project-URL: Homepage, https://github.com/trissim/metaclass-registry
+Project-URL: Documentation, https://metaclass-registry.readthedocs.io
+Project-URL: Repository, https://github.com/trissim/metaclass-registry
+Project-URL: Issues, https://github.com/trissim/metaclass-registry/issues
+Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
+License: MIT
+License-File: LICENSE
+Keywords: cache,discovery,lazy-loading,metaclass,plugin,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# metaclass-registry
+
+**Zero-boilerplate metaclass-driven plugin registry system with lazy discovery and caching**
+
+[![PyPI version](https://badge.fury.io/py/metaclass-registry.svg)](https://badge.fury.io/py/metaclass-registry)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+- **Type-Safe**: Full type hints and mypy support
+
+## Quick Start
+
+```python
+from metaclass_registry import AutoRegisterMeta
+
+# Define a base class with registry configuration
+class PluginBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'plugin_name'  # Attribute to use as registry key
+    
+    plugin_name: str = None  # Subclasses set this to register
+
+# 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!"
+```
+
+## Installation
+
+```bash
+pip install metaclass-registry
+```
+
+## Why metaclass-registry?
+
+Most plugin systems require boilerplate code:
+
+**Before** (Traditional approach):
+```python
+# Custom metaclass per registry
+class PluginMeta(type):
+    def __new__(mcs, name, bases, namespace):
+        cls = super().__new__(mcs, name, bases, namespace)
+        if hasattr(cls, 'plugin_name') and cls.plugin_name:
+            PLUGINS[cls.plugin_name] = cls
+        return cls
+
+# Manual registry creation
+PLUGINS = {}
+
+# Base class with custom metaclass
+class PluginBase(metaclass=PluginMeta):
+    plugin_name = None
+```
+
+**After** (metaclass-registry):
+```python
+# Just class attributes!
+class PluginBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'plugin_name'
+
+# Access auto-created registry
+PLUGINS = PluginBase.__registry__
+```
+
+## Advanced Features
+
+### Registry Inheritance
+
+```python
+class BackendBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'backend_type'
+
+class StorageBackend(BackendBase):
+    pass  # Inherits BackendBase.__registry__
+
+class ReadOnlyBackend(BackendBase):
+    pass  # Also inherits BackendBase.__registry__
+
+# All share the SAME registry!
+assert StorageBackend.__registry__ is BackendBase.__registry__
+```
+
+### Secondary Registries
+
+```python
+METADATA_HANDLERS = {}
+
+class MicroscopeHandler(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'microscope_type'
+    __secondary_registries__ = [
+        SecondaryRegistry(
+            registry_dict=METADATA_HANDLERS,
+            key_source=PRIMARY_KEY,
+            attr_name='metadata_handler_class'
+        )
+    ]
+```
+
+### Custom Key Extractors
+
+```python
+def extract_key_from_suffix(cls):
+    """Extract 'foo' from 'FooHandler'."""
+    name = cls.__name__
+    if name.endswith('Handler'):
+        return name[:-7].lower()
+    return None
+
+class Handler(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'handler_type'
+    __key_extractor__ = extract_key_from_suffix
+```
+
+## Documentation
+
+Full documentation available at [metaclass-registry.readthedocs.io](https://metaclass-registry.readthedocs.io)
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please see CONTRIBUTING.md for guidelines.
+
+## Credits
+
+Developed by Tristan Simas as part of the OpenHCS project.

metaclass_registry-0.1.0/README.md

@@ -0,0 +1,147 @@
+# metaclass-registry
+
+**Zero-boilerplate metaclass-driven plugin registry system with lazy discovery and caching**
+
+[![PyPI version](https://badge.fury.io/py/metaclass-registry.svg)](https://badge.fury.io/py/metaclass-registry)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+- **Type-Safe**: Full type hints and mypy support
+
+## Quick Start
+
+```python
+from metaclass_registry import AutoRegisterMeta
+
+# Define a base class with registry configuration
+class PluginBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'plugin_name'  # Attribute to use as registry key
+    
+    plugin_name: str = None  # Subclasses set this to register
+
+# 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!"
+```
+
+## Installation
+
+```bash
+pip install metaclass-registry
+```
+
+## Why metaclass-registry?
+
+Most plugin systems require boilerplate code:
+
+**Before** (Traditional approach):
+```python
+# Custom metaclass per registry
+class PluginMeta(type):
+    def __new__(mcs, name, bases, namespace):
+        cls = super().__new__(mcs, name, bases, namespace)
+        if hasattr(cls, 'plugin_name') and cls.plugin_name:
+            PLUGINS[cls.plugin_name] = cls
+        return cls
+
+# Manual registry creation
+PLUGINS = {}
+
+# Base class with custom metaclass
+class PluginBase(metaclass=PluginMeta):
+    plugin_name = None
+```
+
+**After** (metaclass-registry):
+```python
+# Just class attributes!
+class PluginBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'plugin_name'
+
+# Access auto-created registry
+PLUGINS = PluginBase.__registry__
+```
+
+## Advanced Features
+
+### Registry Inheritance
+
+```python
+class BackendBase(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'backend_type'
+
+class StorageBackend(BackendBase):
+    pass  # Inherits BackendBase.__registry__
+
+class ReadOnlyBackend(BackendBase):
+    pass  # Also inherits BackendBase.__registry__
+
+# All share the SAME registry!
+assert StorageBackend.__registry__ is BackendBase.__registry__
+```
+
+### Secondary Registries
+
+```python
+METADATA_HANDLERS = {}
+
+class MicroscopeHandler(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'microscope_type'
+    __secondary_registries__ = [
+        SecondaryRegistry(
+            registry_dict=METADATA_HANDLERS,
+            key_source=PRIMARY_KEY,
+            attr_name='metadata_handler_class'
+        )
+    ]
+```
+
+### Custom Key Extractors
+
+```python
+def extract_key_from_suffix(cls):
+    """Extract 'foo' from 'FooHandler'."""
+    name = cls.__name__
+    if name.endswith('Handler'):
+        return name[:-7].lower()
+    return None
+
+class Handler(metaclass=AutoRegisterMeta):
+    __registry_key__ = 'handler_type'
+    __key_extractor__ = extract_key_from_suffix
+```
+
+## Documentation
+
+Full documentation available at [metaclass-registry.readthedocs.io](https://metaclass-registry.readthedocs.io)
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please see CONTRIBUTING.md for guidelines.
+
+## Credits
+
+Developed by Tristan Simas as part of the OpenHCS project.

metaclass_registry-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metaclass-registry"
+version = "0.1.0"
+description = "Zero-boilerplate metaclass-driven plugin registry system with lazy discovery and caching"
+authors = [{name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+keywords = ["metaclass", "registry", "plugin", "discovery", "lazy-loading", "cache"]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/trissim/metaclass-registry"
+Documentation = "https://metaclass-registry.readthedocs.io"
+Repository = "https://github.com/trissim/metaclass-registry"
+Issues = "https://github.com/trissim/metaclass-registry/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metaclass_registry"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "--cov=metaclass_registry --cov-report=term-missing --cov-report=html"
+
+[tool.black]
+line-length = 100
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

metaclass_registry-0.1.0/src/metaclass_registry/__init__.py

@@ -0,0 +1,45 @@
+"""
+metaclass-registry: Zero-boilerplate metaclass-driven plugin registry system.
+
+This package provides a generic metaclass infrastructure for automatic plugin
+registration with lazy discovery, caching, and zero boilerplate.
+"""
+
+__version__ = "0.1.0"
+
+from .core import (
+    AutoRegisterMeta,
+    RegistryConfig,
+    PRIMARY_KEY,
+    SecondaryRegistry,
+    LazyDiscoveryDict,
+    SecondaryRegistryDict,
+    extract_key_from_handler_suffix,
+    extract_key_from_backend_suffix,
+    make_suffix_extractor,
+)
+from .discovery import discover_registry_classes, discover_registry_classes_recursive
+from .cache import RegistryCacheManager
+from .exceptions import RegistryError, DiscoveryError, CacheError
+
+__all__ = [
+    # Core
+    "AutoRegisterMeta",
+    "RegistryConfig",
+    "PRIMARY_KEY",
+    "SecondaryRegistry",
+    "LazyDiscoveryDict",
+    "SecondaryRegistryDict",
+    "extract_key_from_handler_suffix",
+    "extract_key_from_backend_suffix",
+    "make_suffix_extractor",
+    # Discovery
+    "discover_registry_classes",
+    "discover_registry_classes_recursive",
+    # Cache
+    "RegistryCacheManager",
+    # Exceptions
+    "RegistryError",
+    "DiscoveryError",
+    "CacheError",
+]

metaclass_registry-0.1.0/src/metaclass_registry/_home.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def get_home_dir() -> str:
+    """
+    Get the user's home directory in a cross-platform manner.
+    
+    Uses pathlib.Path.home() which works reliably on Unix and Windows.
+    
+    Returns:
+        str: The user's home directory path.
+    """
+    return str(Path.home())