目录：为您的库提供超轻量级功能注册

catalogue 是一个微型、无依赖库，它使得向代码中 添加功能（或对象）注册表 变得容易。当您有需要既易于序列化又可完全自定义的对象时，功能注册表非常有用。您不需要将函数传递给对象，而是传递一个标识符名称，对象可以使用该名称从注册表中查找函数。这使得对象易于序列化，因为名称是一个简单的字符串。如果您保存了函数，则必须使用 Pickle 进行序列化，这有很多缺点。

⏳ 安装

pip install catalogue

conda install -c conda-forge catalogue

⚠️ 重要提示： catalogue v2.0+ 仅与 Python 3.6+ 兼容。对于 Python 2.7+ 兼容性，请使用 catalogue v1.x。

👩‍💻 使用

让我们假设您正在开发一个需要加载数据的 Python 包。您已经为最常见的数据类型实现了一些加载函数，但您希望用户可以轻松添加自己的。使用 catalogue.create，您可以在命名空间 your_package → loaders 下创建一个新的注册表。

# YOUR PACKAGE
import catalogue

loaders = catalogue.create("your_package", "loaders")

这为您提供了一个 loaders.register 装饰器，用户可以导入并使用它来装饰他们的自定义加载函数。

# USER CODE
from your_package import loaders

@loaders.register("custom_loader")
def custom_loader(data):
    # Load something here...
    return data

装饰后的函数将被自动注册，在您的包中，您可以通过调用 loaders.get_all 来访问所有加载器。

# YOUR PACKAGE
def load_data(data, loader_id):
    print("All loaders:", loaders.get_all()) # {"custom_loader": <custom_loader>}
    loader = loaders.get(loader_id)
    return loader(data)

现在，用户只需使用其字符串名称（"custom_loader"）即可引用他们的自定义加载器，并且您的应用程序将知道如何操作并使用他们的自定义函数。

# USER CODE
from your_package import load_data

load_data(data, loader_id="custom_loader")

❓ 常见问题解答

用户不能直接传递 custom_loader 函数吗？

当然可以，这是一种更经典的回调方法。在这种情况下，load_data 也可以接受一个函数，这样您就不需要这样的包。catalogue 帮助您在需要记录传递了哪些函数时。例如，您可能想要记录日志消息或保存配置，以便稍后加载对象。使用 catalogue，您的函数可以通过字符串进行参数化，这样日志记录和序列化仍然很容易 - 同时仍然提供完整的可扩展性。

我如何确保所有注册装饰器都已运行？

装饰器通常在导入模块时运行。依赖这种副作用有时会导致混淆，尤其是在没有其他原因导入模块的情况下。一种解决方案是使用 入口点。

例如，在 spaCy 中，我们开始使用功能注册表来使管道组件更加可定制。假设用户 Jo 开发了一个更好的标签模型，使用了新的机器学习研究。Jo 的包的最终用户应该能够编写 spacy.load("jo_tagging_model")。他们不需要记住先导入 jos_tagged_model，只是为了作为副作用运行功能注册表。使用入口点，注册发生在安装时 - 因此您不需要依赖导入副作用。

🎛 API

函数 catalogue.create

为给定的命名空间创建一个新的注册表。返回一个设置函数，可以用作装饰器或通过名称和 func 关键字参数调用。如果设置 entry_points=True，则注册表将检查给定命名空间声明的 Python 入口点，例如命名空间 "spacy", "architectures" 的入口点组 spacy_architectures，在 Registry.get 和 Registry.get_all 中。这允许其他包自动注册函数。

architectures = catalogue.create("spacy", "architectures")

# Use as decorator
@architectures.register("custom_architecture")
def custom_architecture():
    pass

# Use as regular function
architectures.register("custom_architecture", func=custom_architecture)

类 Registry

可以用于注册和检索函数的注册表对象。它通常在调用 catalogue.create 时内部创建。

方法 Registry.__init__

初始化一个新的注册表。如果设置了 entry_points=True，注册表将检查给定命名空间中声明的 Python 入口点，例如，对于命名空间 "spacy", "architectures" 的入口点组 spacy_architectures，在 Registry.get 和 Registry.get_all 中。

# User-facing API
architectures = catalogue.create("spacy", "architectures")
# Internal API
architectures = Registry(("spacy", "architectures"))

方法 Registry.__contains__

检查一个名称是否在注册表中。

architectures = catalogue.create("spacy", "architectures")

@architectures.register("custom_architecture")
def custom_architecture():
    pass

assert "custom_architecture" in architectures

方法 Registry.__call__

在注册表的命名空间中注册一个函数。可以用作装饰器或以带 func 关键字参数的函数调用的方式使用，该参数提供要注册的函数。委托给 Registry.register。

方法 Registry.register

在注册表的命名空间中注册一个函数。可以用作装饰器或以带 func 关键字参数的函数调用的方式使用。

architectures = catalogue.create("spacy", "architectures")

# Use as decorator
@architectures.register("custom_architecture")
def custom_architecture():
    pass

# Use as regular function
architectures.register("custom_architecture", func=custom_architecture)

方法 Registry.get

获取命名空间中注册的函数。

custom_architecture = architectures.get("custom_architecture")

方法 Registry.get_all

获取注册表中命名空间中的所有函数。

all_architectures = architectures.get_all()
# {"custom_architecture": <custom_architecture>}

方法 Registry.get_entry_points

获取为该命名空间从其他包注册的入口点。入口点组的名称是命名空间通过 _ 连接。

architectures = catalogue.create("spacy", "architectures", entry_points=True)
# Will get all entry points of the group "spacy_architectures"
all_entry_points = architectures.get_entry_points()

方法 Registry.get_entry_point

检查注册的入口点是否在命名空间中给定名称可用，并加载它。否则，返回默认值。

architectures = catalogue.create("spacy", "architectures", entry_points=True)
# Will get entry point "custom_architecture" of the group "spacy_architectures"
custom_architecture = architectures.get_entry_point("custom_architecture")

方法 Registry.find

查找关于注册函数的信息，包括定义它的模块和文件路径、行号以及可选的文档字符串。

import catalogue

architectures = catalogue.create("spacy", "architectures", entry_points=True)

@architectures("my_architecture")
def my_architecture():
    """This is an architecture"""
    pass

info = architectures.find("my_architecture")
# {'module': 'your_package.architectures',
#  'file': '/path/to/your_package/architectures.py',
#  'line_no': 5,
#  'docstring': 'This is an architecture'}

函数 catalogue.check_exists

检查命名空间是否存在。