{"id":31444014,"url":"https://github.com/mawuva/regman","last_synced_at":"2025-09-30T20:41:16.791Z","repository":{"id":316690922,"uuid":"1064454449","full_name":"mawuva/regman","owner":"mawuva","description":"A lightweight, thread-safe registry framework for Python. It allows you to create and manage registries for plugins, strategies, handlers, or any reusable objects with optional decorators and a central registry manager.","archived":false,"fork":false,"pushed_at":"2025-09-26T04:53:16.000Z","size":45,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-26T06:15:10.457Z","etag":null,"topics":["concurrency","design-patterns","framework","library","lightweight","open-source","plugin","python","registry","registry-manager","registry-pattern","thread-safe","utilities"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/regman/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mawuva.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-26T04:10:18.000Z","updated_at":"2025-09-26T04:27:45.000Z","dependencies_parsed_at":"2025-09-26T06:15:29.091Z","dependency_job_id":"617e2a44-5e58-4ae8-8287-a440c86cc4b1","html_url":"https://github.com/mawuva/regman","commit_stats":null,"previous_names":["mawuva/regman"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mawuva/regman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawuva%2Fregman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawuva%2Fregman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawuva%2Fregman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawuva%2Fregman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mawuva","download_url":"https://codeload.github.com/mawuva/regman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawuva%2Fregman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277140221,"owners_count":25767977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-26T02:00:09.010Z","response_time":78,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","design-patterns","framework","library","lightweight","open-source","plugin","python","registry","registry-manager","registry-pattern","thread-safe","utilities"],"created_at":"2025-09-30T20:41:14.684Z","updated_at":"2025-09-30T20:41:16.785Z","avatar_url":"https://github.com/mawuva.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Regman : Thread-Safe Registry Framework for Python\n\n[![CI](https://github.com/mawuva/regman/actions/workflows/ci.yml/badge.svg)](https://github.com/mawuva/regman/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/regman.svg)](https://pypi.org/project/regman/)\n[![Python Version](https://img.shields.io/pypi/pyversions/regman.svg)](https://pypi.org/project/regman/)\n[![GitHub License](https://img.shields.io/github/license/mawuva/regman)](https://github.com/mawuva/regman/blob/main/LICENSE)\n\nRegman is a lightweight and flexible Python package to manage registries in a thread-safe way. It provides a simple yet powerful infrastructure for registering and managing classes, functions, and objects in a centralized, thread-safe manner.\n\n\n## Why Regman ?\n\n### The Problem\n\nWhen building complex Python applications, you often need to:\n\n- **Manage multiple implementations** of the same interface (e.g., different payment methods, data processors, or notification channels)\n- **Dynamically select components** at runtime based on configuration or user input\n- **Implement design patterns** like Strategy, Factory, Observer, or Plugin architectures\n- **Ensure thread safety** when multiple threads access the same registry\n- **Avoid tight coupling** between components and their instantiation logic\n\n### Common Solutions and Their Limitations\n\n**Manual dictionaries:**\n```python\n# ❌ Not thread-safe, error-prone\nstrategies = {\n    \"credit_card\": CreditCardStrategy,\n    \"paypal\": PayPalStrategy\n}\nstrategy = strategies[\"credit_card\"]()  # KeyError if key doesn't exist\n```\n\n**Simple registry classes:**\n```python\n# ❌ Not thread-safe, basic functionality\nclass SimpleRegistry:\n    def __init__(self):\n        self._items = {}\n    \n    def register(self, key, value):\n        self._items[key] = value  # Race condition in multi-threaded apps\n```\n\n**Complex dependency injection frameworks:**\n```python\n# ❌ Overkill for simple use cases, heavy dependencies\nfrom some_di_framework import Container, Service\n\ncontainer = Container()\ncontainer.register(Service(IPaymentStrategy), CreditCardStrategy)\n# Too much boilerplate for simple registries\n```\n\n### The Regman Solution\n\nregman provides a **simple, thread-safe, and flexible** solution:\n\n```python\n# ✅ Thread-safe, clean, and powerful\nfrom regman import Registry, register\n\nregistry = Registry(\"payment_strategies\")\n\n@register(registry, \"credit_card\")\nclass CreditCardStrategy:\n    def pay(self, amount):\n        return f\"Paid ${amount} with credit card\"\n\n# Safe to use from multiple threads\nstrategy_class = registry.get(\"credit_card\")\nstrategy = strategy_class()\n```\n\n### Key Benefits\n\n- **Thread Safety**: Built-in locking ensures safe concurrent access\n- **Simplicity**: Clean API with minimal boilerplate\n- **Flexibility**: Works with any Python object (classes, functions, instances)\n- **Performance**: Optimized for high-frequency access patterns\n- **Type Safety**: Full type hints support for better IDE integration\n- **Design Pattern Ready**: Perfect for implementing common architectural patterns\n\n### Real-World Use Cases\n\n- **Payment Processing**: Different payment methods (credit card, PayPal, crypto)\n- **Plugin Systems**: Dynamic loading and execution of plugins\n- **Data Processing Pipelines**: Various data transformers and validators\n- **Notification Systems**: Multiple notification channels (email, SMS, push)\n- **Configuration Management**: Different configuration providers\n- **API Versioning**: Multiple API implementations for different versions\n\n## Features\n\n- **Thread-Safe Registry**: Store and manage objects with automatic locking for concurrent access\n- **Registry Manager**: Centralize multiple registries for your project\n- **Decorator Support**: Convenient `@register` decorator for easy registration\n- **Type Safety**: Full type hints support for better IDE integration\n- **Lightweight**: Minimal dependencies, fast performance\n- **Flexible**: Works with any Python object (classes, functions, instances)\n- **Design Patterns**: Perfect for implementing Strategy, Factory, Observer, and Plugin patterns\n\n## Installation\n\n```bash\npip install regman\n```\n\nOr with Poetry:\n\n```bash\npoetry add regman\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom regman import Registry, register\n\n# Create a registry\nregistry = Registry(\"my_components\")\n\n# Register a class\n@register(registry, \"calculator\")\nclass Calculator:\n    def add(self, a: int, b: int) -\u003e int:\n        return a + b\n\n# Register a function\n@register(registry, \"multiplier\")\ndef multiply(x: float, y: float) -\u003e float:\n    return x * y\n\n# Use registered objects\ncalc_class = registry.get(\"calculator\")\ncalculator = calc_class()\nresult = calculator.add(5, 3)  # 8\n\nmult_func = registry.get(\"multiplier\")\nresult = mult_func(4.5, 2.0)  # 9.0\n```\n\n### Registry Manager\n\n```python\nfrom regman import RegistryManager, register\n\n# Create a manager\nmanager = RegistryManager()\n\n# Create multiple registries\nplugins = manager.create_registry(\"plugins\")\nstrategies = manager.create_registry(\"strategies\")\n\n# Register components\n@register(plugins, \"data_processor\")\nclass DataProcessor:\n    def process(self, data):\n        return data * 2\n\n@register(strategies, \"payment_credit\")\nclass CreditCardStrategy:\n    def pay(self, amount):\n        return f\"Paid ${amount} with credit card\"\n\n# Access registries\ndata_processor = plugins.get(\"data_processor\")\npayment_strategy = strategies.get(\"payment_credit\")\n```\n\n## Advanced Usage\n\n### Strategy Pattern\n\n```python\nfrom abc import ABC, abstractmethod\nfrom regman import Registry, register\n\nclass PaymentStrategy(ABC):\n    @abstractmethod\n    def pay(self, amount: float) -\u003e str:\n        pass\n\n# Register strategies directly\nregistry = Registry(\"payment_strategies\")\n\n@register(registry, \"credit_card\")\nclass CreditCardStrategy(PaymentStrategy):\n    def pay(self, amount: float) -\u003e str:\n        return f\"Paid ${amount} with credit card\"\n\n@register(registry, \"paypal\")\nclass PayPalStrategy(PaymentStrategy):\n    def pay(self, amount: float) -\u003e str:\n        return f\"Paid ${amount} with PayPal\"\n\n# Use strategies\nstrategy_class = registry.get(\"credit_card\")\nstrategy = strategy_class()\nresult = strategy.pay(100.0)\n```\n\n### Plugin System\n\n```python\nfrom abc import ABC, abstractmethod\nfrom regman import Registry, register\n\nclass Plugin(ABC):\n    @abstractmethod\n    def execute(self, data):\n        pass\n\n# Register plugins directly\nregistry = Registry(\"plugins\")\n\n@register(registry, \"data_processor\")\nclass DataProcessor(Plugin):\n    def execute(self, data):\n        return [x * 2 for x in data]\n\n@register(registry, \"text_formatter\")\nclass TextFormatter(Plugin):\n    def execute(self, data):\n        return str(data).upper()\n\n# Execute plugins\nfor plugin_name in registry.keys():\n    plugin_class = registry.get(plugin_name)\n    plugin = plugin_class()\n    result = plugin.execute(\"hello\")\n```\n\n## API Reference\n\n### Registry\n\nThe main registry class for storing and managing objects.\n\n```python\nfrom regman import Registry\n\nregistry = Registry(\"my_registry\")\n```\n\n#### Methods\n\n- `add(key: str, value: Any) -\u003e None`: Add an object to the registry\n- `get(key: str) -\u003e Any`: Retrieve an object from the registry\n- `unregister(key: str) -\u003e None`: Remove an object from the registry\n- `keys() -\u003e List[str]`: Get all registered keys\n- `clear() -\u003e None`: Remove all objects from the registry\n- `__contains__(key: str) -\u003e bool`: Check if a key exists\n- `__len__() -\u003e int`: Get the number of registered objects\n\n### RegistryManager\n\nManages multiple registries in a centralized way.\n\n```python\nfrom regman import RegistryManager\n\nmanager = RegistryManager()\n```\n\n#### Methods\n\n- `create_registry(name: str) -\u003e Registry`: Create a new registry\n- `get_registry(name: str) -\u003e Registry`: Get an existing registry\n- `all() -\u003e Dict[str, Registry]`: Get all registries\n\n### Decorators\n\n#### @register\n\nRegister a class or function with a registry.\n\n```python\nfrom regman import register\n\n@register(registry, \"my_key\")\nclass MyClass:\n    pass\n\n@register(registry, \"my_function\")\ndef my_function():\n    pass\n```\n\n## Thread Safety\n\nregman is designed to be thread-safe. All registry operations are protected by locks, making it safe to use in multi-threaded environments.\n\n```python\nimport threading\nfrom regman import Registry, register\n\nregistry = Registry(\"thread_safe\")\n\n@register(registry, \"worker\")\nclass Worker:\n    def work(self):\n        return \"Working safely!\"\n\n# Safe to use from multiple threads\ndef worker_thread():\n    worker_class = registry.get(\"worker\")\n    worker = worker_class()\n    print(worker.work())\n\n# Start multiple threads\nthreads = []\nfor i in range(5):\n    thread = threading.Thread(target=worker_thread)\n    threads.append(thread)\n    thread.start()\n\nfor thread in threads:\n    thread.join()\n```\n\n## Examples\n\nCheck out the [examples directory](examples/) for comprehensive usage examples:\n\n- [Basic Usage](examples/basic_usage.py) - Getting started with regman\n- [Plugin System](examples/plugin_system.py) - Building a plugin architecture\n- [Strategy Pattern](examples/strategy_pattern.py) - Implementing payment strategies\n- [Observer Pattern](examples/observer_pattern.py) - Event notification system\n- [Factory Pattern](examples/factory_pattern.py) - Object creation patterns\n- [Concurrent Usage](examples/concurrent_usage.py) - Multi-threaded applications\n\nRun all examples:\n\n```bash\npython examples/run_all_examples.py\n```\n\n## Testing\n\nThe package includes comprehensive tests covering:\n\n- Unit tests for all components\n- Thread safety tests\n- Integration tests\n- Error handling tests\n\nRun tests:\n\n```bash\n# With pytest\npytest tests/\n\n# With poetry\npoetry run pytest\n\n# With coverage\npytest --cov=regman tests/\n```\n\n## Performance\n\nregman is designed for performance:\n\n- Minimal overhead with efficient locking\n- Fast object retrieval with O(1) average case\n- Memory efficient with no unnecessary allocations\n- Optimized for high-frequency access patterns\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/mawuva/regman.git\ncd regman\n\n# Install with poetry\npoetry install\n\n# Install pre-commit hooks\npoetry run pre-commit install\n```\n\n### Code Quality\n\nThe project uses several tools to maintain code quality:\n\n- **Black**: Code formatting\n- **isort**: Import sorting\n- **flake8**: Linting\n- **mypy**: Type checking\n- **pytest**: Testing\n\nRun all quality checks:\n\n```bash\npoetry run pre-commit run --all-files\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nIf you have any questions or need help, please:\n\n1. Check the [examples](examples/) directory\n2. Read the [documentation](https://github.com/mawuva/regman)\n3. Open an [issue](https://github.com/mawuva/regman/issues)\n\n## Acknowledgments\n\n- Inspired by the need for a simple, thread-safe registry system\n- Built with modern Python best practices\n- Designed for extensibility and performance\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmawuva%2Fregman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmawuva%2Fregman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmawuva%2Fregman/lists"}