catalogue: Super lightweight Function Registries

2.0.10 · active · verified Sun Mar 29

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.

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

pip install catalogue Install with pip

Imports

catalogue
```
import catalogue
```
The primary way to interact with the library is through the top-level 'catalogue' module.
create
```
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

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

view raw JSON →