catalogue: Super lightweight Function Registries

2.0.10 verified Tue May 12 auth: no python install: verified

catalogue is a tiny, zero-dependencies library designed to simplify the creation of function (or object) registries within your Python code. These registries are particularly useful for making objects easily serializable and customizable, allowing you to reference functions by string identifiers instead of direct object references. Currently at version 2.0.10, it maintains an active release cadence with a focus on Python 3.6+ compatibility.

pip install catalogue

Common errors

error ModuleNotFoundError: No module named 'catalogue' ↓

cause The 'catalogue' package is not installed in the current Python environment or is not accessible within the Python path.

fix

Install the package using pip: pip install catalogue

error catalogue.RegistryError: [E893] Could not find function '...' in function registry '...' ↓

cause An attempt was made to retrieve a function from a 'catalogue' registry using a name that has not been registered, or the module defining the registered function was not imported, preventing its registration.

fix

Ensure the function is correctly decorated with @your_registry_name.register("your_function_name") and that the Python module containing this definition is imported and executed before attempting to retrieve it from the registry.

error AttributeError: 'Catalog' object has no attribute 'component' ↓

cause This error indicates that an object, likely an instance of a custom 'Catalog' class (which might internally use or be conceptually related to `catalogue`), was accessed for an attribute named 'component' that does not exist on that object.

fix

Examine the code interacting with the 'Catalog' object to verify the correct attribute name or method call, referring to the API of the specific 'Catalog' class in use.

error TypeError: register() missing 1 required positional argument: 'name' ↓

cause The `@registry.register()` decorator or method was called without providing the mandatory string 'name' argument, which is used to identify the function or object being registered. The `catalogue` library's `register` method explicitly requires a name.

fix

Provide a string name to the register decorator or method, for example: @your_registry.register("my_function_name").

Warnings

breaking catalogue v2.0 and newer versions are not compatible with Python 2.7. For Python 2.7 compatibility, users must stick to catalogue v1.x. ↓

fix Upgrade to Python 3.6+ or downgrade `catalogue` to a 1.x version if Python 2.7 support is strictly required.

gotcha A `v2.1.0` release was briefly tagged and then yanked from PyPI, with development continuing on the `2.0.x` branch. This might lead to confusion if relying solely on GitHub tags for version discovery, or if package managers inadvertently picked up the yanked `2.1.0`. ↓

fix Always refer to the official PyPI release for the latest stable version. If encountering issues with `2.1.0`, ensure you are on the `2.0.x` branch (currently `2.0.10`).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.11s 17.9M

3.10 alpine (musl) - - 0.11s 17.9M

3.10 slim (glibc) wheel 1.5s 0.07s 18M

3.10 slim (glibc) - - 0.07s 18M

3.11 alpine (musl) wheel - 0.14s 19.8M

3.11 alpine (musl) - - 0.16s 19.8M

3.11 slim (glibc) wheel 1.5s 0.12s 20M

3.11 slim (glibc) - - 0.12s 20M

3.12 alpine (musl) wheel - 0.12s 11.6M

3.12 alpine (musl) - - 0.13s 11.6M

3.12 slim (glibc) wheel 1.4s 0.13s 12M

3.12 slim (glibc) - - 0.13s 12M

3.13 alpine (musl) wheel - 0.08s 11.4M

3.13 alpine (musl) - - 0.09s 11.3M

3.13 slim (glibc) wheel 1.4s 0.08s 12M

3.13 slim (glibc) - - 0.08s 12M

3.9 alpine (musl) wheel - 0.05s 17.4M

3.9 alpine (musl) - - 0.06s 17.4M

3.9 slim (glibc) wheel 1.7s 0.05s 18M

3.9 slim (glibc) - - 0.05s 18M

Imports

catalogue
```
import catalogue
```
The primary way to interact with the library is through the top-level 'catalogue' module.
create
wrong
```
import catalogue.create
```
correct
```
from catalogue import create
```
While 'create' is a function within the module, it's typically accessed directly after 'import catalogue' as 'catalogue.create()'. Direct import like `from catalogue import create` is also valid for convenience.

Quickstart last tested: 2026-04-24

This example demonstrates how to create a new registry, register functions using the provided decorator, and then retrieve and use those functions by their string identifiers. This pattern enables extensible and serializable configurations for your library.

import catalogue

# YOUR PACKAGE - Define a registry
loaders = catalogue.create("my_package", "loaders")

# USER CODE - Register custom functions
@loaders.register("file_loader")
def load_from_file(path):
    print(f"Loading data from file: {path}")
    return f"Data from {path}"

@loaders.register("db_loader")
def load_from_db(query):
    print(f"Loading data from DB with query: {query}")
    return f"Data for {query}"

# YOUR PACKAGE - Access registered functions
def get_data(loader_id, source):
    loader = loaders.get(loader_id)
    if loader:
        return loader(source)
    else:
        raise ValueError(f"Unknown loader: {loader_id}")

print(get_data("file_loader", "/path/to/data.txt"))
print(get_data("db_loader", "SELECT * FROM users"))

# List all registered loaders
print("All registered loaders:", loaders.get_all())