catalogue

Introduction to the Catalogue Library

The catalogue library is a streamlined, lightweight tool designed to help developers add function (or object) registries to their Python code. It eliminates the hassle of handling complex serialization processes by allowing objects to refer to functions using simple string identifiers. This approach promotes ease of serialization and full customization of functions within your code.

Key Features

• Light and Dependency-Free: Being minimalistic, catalogue doesn't require any external dependencies. It's straightforward to integrate into your existing projects.
• Function Registries: The core functionality of catalogue is to enable efficient and simple registration and retrieval of functions via registries organized by namespaces. With function registries, you can assign identifiers to functions rather than using the functions directly, simplifying serialization.
• Ease of Customization: By using identifiers, developers can log function usage or save configurations without dealing with complex function objects directly.

Installation

Getting catalogue is as simple as running the following commands:

pip install catalogue

Or, if you prefer using conda:

conda install -c conda-forge catalogue

It's worth noting that catalogue version 2.0+ is compatible with Python 3.6 and above. Users working with Python 2.7 should opt for version 1.x.

How It Works

Consider you are building a data-loading Python package. While you've implemented some standard loaders, you want to allow users to add their custom loaders. Here's how catalogue helps:

1. Create a Registry: First, you create a registry with a specific namespace.

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

2. Register Functions: Users can define and register their custom functions within this namespace using a simple decorator.

   from your_package import loaders
   
   @loaders.register("custom_loader")
   def custom_loader(data):
       # Custom loading logic
       return data
   

3. Function Usage: The registered functions can be retrieved and used with ease, using their identifiers.

   def load_data(data, loader_id):
       loader = loaders.get(loader_id)
       return loader(data)
   
   load_data(data, loader_id="custom_loader")
   

Frequently Asked Questions

• Can the user just pass in the custom_loader function directly?

  Yes, direct passage is possible; however, using the string identifier approach aids in creating a record of the functions used, supporting logging and serialization needs without losing extensibility.

• How to ensure registration decorators have executed?

  Decorators typically register functions when modules are imported. To avoid import-related side-effects, using entry points is recommended, ensuring registration during package installation. This method is implemented, for example, within spaCy to enhance its modular architecture.

API Overview

The catalogue library provides a comprehensive API allowing various operations on function registries, from creation to retrieval, entry point integration, and even detailed function information retrieval.

• catalogue.create: Initializes a registry for a given namespace.
• Registry.__call__ and Registry.register: Allow registration of functions in the namespace.
• Registry.get and Registry.get_all: Retrieve functions from a registry.
• Registry.find: Fetch detailed information about a registered function, such as file location and docstring.

The catalogue library, thus, offers an efficient and straightforward mechanism for function registration and management, enhancing the modularity and flexibility of Python applications.