Registry / phx-class-registry

phx-class-registry

library5.2.2pypypi✓ verified 85d ago

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.

pip install phx-class-registry

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PHX-CLASS-REGISTRY

phx-class-registry

pythonv5.2.2

Install

1.6s avg

Import

127ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.130s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.124s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClassRegistry

✓ from class_registry import ClassRegistry

RegistryKeyError

✓ from class_registry import RegistryKeyError

AutoRegister (as a base class mixin)

✓ from class_registry.base import AutoRegister

✗ from class_registry.auto_register 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`.

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()}")

Debug

Known issues

breakingClassRegistry 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.

affects: >=5.0.0

breakingClassRegistry 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).

affects: >=5.1.0

deprecatedThe `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.

affects: >=5.0.0

gotchaUsers 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`.

affects: All

breakingIn 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`.

affects: >=4.0.3

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'class_registry'

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'

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'

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.

Upgrade

Version history

5.2.2latest on PyPI · released May 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/todofixthis/class-registry ↗

packagehttps://pypi.org/project/phx-class-registry/ ↗

docshttps://class-registry.readthedocs.io/ ↗

changeloghttps://github.com/todofixthis/class-registry/releases ↗