ClassRegistry

5.2.1 · active · verified Thu Apr 16

ClassRegistry (phx-class-registry) is a Python library that implements a powerful Factory+Registry pattern for Python classes, enabling the definition of global factories that generate new class instances based on configurable keys. It supports service registries and integration with setuptools's entry_points system for extensibility. The current version is 5.2.1 and it maintains an active release cadence, supporting the three most recent Python versions.

Common errors

```
ModuleNotFoundError: No module named 'class_registry'
```
cause You likely installed the abandoned `class-registry` package instead of `phx-class-registry`. The `phx-class-registry` package installs the `class_registry` module.

fix Uninstall `class-registry` with `pip uninstall class-registry` and then install the correct package: `pip install phx-class-registry`.
```
AttributeError: module 'class_registry' has no attribute 'MutableRegistry'
```
cause In ClassRegistry v4.0.3, `MutableRegistry` was renamed to `BaseMutableRegistry` for clarity and to better reflect its role as a base class.

fix Update your import and usage to `from class_registry import BaseMutableRegistry` and use `BaseMutableRegistry` instead of `MutableRegistry`.
```
RegistryKeyError: No class registered for key 'my_key'
```
cause This error occurs when you try to access a key in a `ClassRegistry` that has not been registered with a corresponding class, or the key name is misspelled.

fix Ensure that the class you intend to retrieve has been correctly decorated with `@your_registry.register('my_key')` using the exact key string, and that the key used for retrieval matches it.

Warnings

breaking ClassRegistry v5.0.0 introduced backwards-incompatible changes by cleaning up the top-level `class_registry` namespace. Code upgrading from v4.x or earlier must review the 'Upgrading to ClassRegistry v5' documentation for migration instructions.
Fix: Consult the official 'Upgrading to ClassRegistry v5' guide on ReadTheDocs to adapt your imports and code structure.
breaking ClassRegistry v5.1.0 and v5.2.0 dropped support for Python 3.10 and 3.11 respectively. The library now strictly requires Python >=3.12.
Fix: Upgrade your Python environment to version 3.12 or newer. For projects requiring older Python versions, pin `phx-class-registry` to `<5.1.0` (for Python 3.10) or `<5.2.0` (for Python 3.11).
deprecated The `AutoRegister` function from `class_registry.auto_register` is deprecated in v5.x. It should now be imported as a base class mixin from `class_registry.base`.
Fix: Change `from class_registry.auto_register import AutoRegister` to `from class_registry.base import AutoRegister` and use `AutoRegister(my_registry)` as a base class for auto-registration.
gotcha Users often mistakenly install `class-registry` instead of `phx-class-registry`. The `class-registry` package is an older, unmaintained fork and will not receive updates.
Fix: Always use `pip install phx-class-registry`. If you have `class-registry` installed, uninstall it with `pip uninstall class-registry`.
breaking In v4.0.3, `class_registry.MutableRegistry` was renamed to `class_registry.BaseMutableRegistry`. This primarily impacts users who subclass `MutableRegistry`.
Fix: If you subclassed `MutableRegistry`, update your base class to `BaseMutableRegistry`.

Install

pip install phx-class-registry Install latest version

Imports

ClassRegistry

from class_registry import ClassRegistry

RegistryKeyError

from class_registry import RegistryKeyError

AutoRegister (as a base class mixin)
wrong:
```
from class_registry.auto_register import AutoRegister
```
correct:
```
from class_registry.base import AutoRegister
```
The direct import from `class_registry.auto_register` is deprecated in v5.x; `AutoRegister` is now intended for use as a base class mixin imported from `class_registry.base`.

Quickstart

This example demonstrates creating a typed ClassRegistry, registering classes using a decorator with keys, and then instantiating objects from the registry using subscript notation.

from class_registry import ClassRegistry

class Pokemon:
    pass

pokedex = ClassRegistry[Pokemon]()

@pokedex.register('fire')
class Charizard(Pokemon):
    def attack(self): return 'Flamethrower'

@pokedex.register('water')
class Squirtle(Pokemon):
    def attack(self): return 'Water Gun'

# Create instances
fire_pokemon = pokedex['fire']
water_pokemon = pokedex['water']

assert isinstance(fire_pokemon, Charizard)
assert fire_pokemon.attack() == 'Flamethrower'
assert isinstance(water_pokemon, Squirtle)
assert water_pokemon.attack() == 'Water Gun'

print(f"Created {fire_pokemon.__class__.__name__}: {fire_pokemon.attack()}")
print(f"Created {water_pokemon.__class__.__name__}: {water_pokemon.attack()}")

view raw JSON →