{"author":"Explosion","author_email":"contact@explosion.ai","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Environment :: Console","Intended Audience :: Developers","Intended Audience :: Science/Research","License :: OSI Approved :: MIT License","Operating System :: MacOS :: MacOS X","Operating System :: Microsoft :: Windows","Operating System :: POSIX :: Linux","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.6","Programming Language :: Python :: 3.7","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering"],"description":"

\n\n# catalogue: Super lightweight function registries for your library\n\n`catalogue` is a tiny, zero-dependencies library that makes it easy to **add\nfunction (or object) registries** to your code. Function registries are helpful\nwhen you have objects that need to be both easily serializable and fully\ncustomizable. Instead of passing a function into your object, you pass in an\nidentifier name, which the object can use to lookup the function from the\nregistry. This makes the object easy to serialize, because the name is a simple\nstring. If you instead saved the function, you'd have to use Pickle for\nserialization, which has many drawbacks.\n\n[![tests](https://github.com/explosion/catalogue/actions/workflows/tests.yml/badge.svg)](https://github.com/explosion/catalogue/actions/workflows/tests.yml)\n[![Current Release Version](https://img.shields.io/github/v/release/explosion/catalogue.svg?style=flat-square&include_prereleases&logo=github)](https://github.com/explosion/catalogue/releases)\n[![pypi Version](https://img.shields.io/pypi/v/catalogue.svg?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/catalogue/)\n[![conda Version](https://img.shields.io/conda/vn/conda-forge/catalogue.svg?style=flat-square&logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/catalogue)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/ambv/black)\n\n## ⏳ Installation\n\n```bash\npip install catalogue\n```\n\n```bash\nconda install -c conda-forge catalogue\n```\n\n> ⚠️ **Important note:** `catalogue` v2.0+ is only compatible with Python 3.6+.\n> For Python 2.7+ compatibility, use `catalogue` v1.x.\n\n## 👩‍💻 Usage\n\nLet's imagine you're developing a Python package that needs to load data\nsomewhere. You've already implemented some loader functions for the most common\ndata types, but you want to allow the user to easily add their own. Using\n`catalogue.create` you can create a new registry under the namespace\n`your_package` → `loaders`.\n\n```python\n# YOUR PACKAGE\nimport catalogue\n\nloaders = catalogue.create(\"your_package\", \"loaders\")\n```\n\nThis gives you a `loaders.register` decorator that your users can import and\ndecorate their custom loader functions with.\n\n```python\n# USER CODE\nfrom your_package import loaders\n\n@loaders.register(\"custom_loader\")\ndef custom_loader(data):\n # Load something here...\n return data\n```\n\nThe decorated function will be registered automatically and in your package,\nyou'll be able to access all loaders by calling `loaders.get_all`.\n\n```python\n# YOUR PACKAGE\ndef load_data(data, loader_id):\n print(\"All loaders:\", loaders.get_all()) # {\"custom_loader\": }\n loader = loaders.get(loader_id)\n return loader(data)\n```\n\nThe user can now refer to their custom loader using only its string name\n(`\"custom_loader\"`) and your application will know what to do and will use their\ncustom function.\n\n```python\n# USER CODE\nfrom your_package import load_data\n\nload_data(data, loader_id=\"custom_loader\")\n```\n\n## ❓ FAQ\n\n#### But can't the user just pass in the `custom_loader` function directly?\n\nSure, that's the more classic callback approach. Instead of a string ID,\n`load_data` could also take a function, in which case you wouldn't need a\npackage like this. `catalogue` helps you when you need to produce a serializable\nrecord of which functions were passed in. For instance, you might want to write\na log message, or save a config to load back your object later. With\n`catalogue`, your functions can be parameterized by strings, so logging and\nserialization remains easy – while still giving you full extensibility.\n\n#### How do I make sure all of the registration decorators have run?\n\nDecorators normally run when modules are imported. Relying on this side-effect\ncan sometimes lead to confusion, especially if there's no other reason the\nmodule would be imported. One solution is to use\n[entry points](https://packaging.python.org/specifications/entry-points/).\n\nFor instance, in [spaCy](https://spacy.io) we're starting to use function\nregistries to make the pipeline components much more customizable. Let's say one\nuser, Jo, develops a better tagging model using new machine learning research.\nEnd-users of Jo's package should be able to write\n`spacy.load(\"jo_tagging_model\")`. They shouldn't need to remember to write\n`import jos_tagged_model` first, just to run the function registries as a\nside-effect. With entry points, the registration happens at install time – so\nyou don't need to rely on the import side-effects.\n\n## 🎛 API\n\n### function `catalogue.create`\n\nCreate a new registry for a given namespace. Returns a setter function that can\nbe used as a decorator or called with a name and `func` keyword argument. If\n`entry_points=True` is set, the registry will check for\n[Python entry points](https://packaging.python.org/tutorials/packaging-projects/#entry-points)\nadvertised for the given namespace, e.g. the entry point group\n`spacy_architectures` for the namespace `\"spacy\", \"architectures\"`, in\n`Registry.get` and `Registry.get_all`. This allows other packages to\nauto-register functions.\n\n| Argument | Type | Description |\n| -------------- | ---------- | ---------------------------------------------------------------------------------------------- |\n| `*namespace` | str | The namespace, e.g. `\"spacy\"` or `\"spacy\", \"architectures\"`. |\n| `entry_points` | bool | Whether to check for entry points of the given namespace and pre-populate the global registry. |\n| **RETURNS** | `Registry` | The `Registry` object with methods to register and retrieve functions. |\n\n```python\narchitectures = catalogue.create(\"spacy\", \"architectures\")\n\n# Use as decorator\n@architectures.register(\"custom_architecture\")\ndef custom_architecture():\n pass\n\n# Use as regular function\narchitectures.register(\"custom_architecture\", func=custom_architecture)\n```\n\n### class `Registry`\n\nThe registry object that can be used to register and retrieve functions. It's\nusually created internally when you call `catalogue.create`.\n\n#### method `Registry.__init__`\n\nInitialize a new registry. If `entry_points=True` is set, the registry will\ncheck for\n[Python entry points](https://packaging.python.org/tutorials/packaging-projects/#entry-points)\nadvertised for the given namespace, e.g. the entry point group\n`spacy_architectures` for the namespace `\"spacy\", \"architectures\"`, in\n`Registry.get` and `Registry.get_all`.\n\n| Argument | Type | Description |\n| -------------- | ---------- | -------------------------------------------------------------------------------- |\n| `namespace` | Tuple[str] | The namespace, e.g. `\"spacy\"` or `\"spacy\", \"architectures\"`. |\n| `entry_points` | bool | Whether to check for entry points of the given namespace in `get` and `get_all`. |\n| **RETURNS** | `Registry` | The newly created object. |\n\n```python\n# User-facing API\narchitectures = catalogue.create(\"spacy\", \"architectures\")\n# Internal API\narchitectures = Registry((\"spacy\", \"architectures\"))\n```\n\n#### method `Registry.__contains__`\n\nCheck whether a name is in the registry.\n\n| Argument | Type | Description |\n| ----------- | ---- | ------------------------------------ |\n| `name` | str | The name to check. |\n| **RETURNS** | bool | Whether the name is in the registry. |\n\n```python\narchitectures = catalogue.create(\"spacy\", \"architectures\")\n\n@architectures.register(\"custom_architecture\")\ndef custom_architecture():\n pass\n\nassert \"custom_architecture\" in architectures\n```\n\n#### method `Registry.__call__`\n\nRegister a function in the registry's namespace. Can be used as a decorator or\ncalled as a function with the `func` keyword argument supplying the function to\nregister. Delegates to `Registry.register`.\n\n#### method `Registry.register`\n\nRegister a function in the registry's namespace. Can be used as a decorator or\ncalled as a function with the `func` keyword argument supplying the function to\nregister.\n\n| Argument | Type | Description |\n| ----------- | -------- | --------------------------------------------------------- |\n| `name` | str | The name to register under the namespace. |\n| `func` | Any | Optional function to register (if not used as decorator). |\n| **RETURNS** | Callable | The decorator that takes one argument, the name. |\n\n```python\narchitectures = catalogue.create(\"spacy\", \"architectures\")\n\n# Use as decorator\n@architectures.register(\"custom_architecture\")\ndef custom_architecture():\n pass\n\n# Use as regular function\narchitectures.register(\"custom_architecture\", func=custom_architecture)\n```\n\n#### method `Registry.get`\n\nGet a function registered in the namespace.\n\n| Argument | Type | Description |\n| ----------- | ---- | ------------------------ |\n| `name` | str | The name. |\n| **RETURNS** | Any | The registered function. |\n\n```python\ncustom_architecture = architectures.get(\"custom_architecture\")\n```\n\n#### method `Registry.get_all`\n\nGet all functions in the registry's namespace.\n\n| Argument | Type | Description |\n| ----------- | -------------- | ---------------------------------------- |\n| **RETURNS** | Dict[str, Any] | The registered functions, keyed by name. |\n\n```python\nall_architectures = architectures.get_all()\n# {\"custom_architecture\": }\n```\n\n#### method `Registry.get_entry_points`\n\nGet registered entry points from other packages for this namespace. The name of\nthe entry point group is the namespace joined by `_`.\n\n| Argument | Type | Description |\n| ----------- | -------------- | --------------------------------------- |\n| **RETURNS** | Dict[str, Any] | The loaded entry points, keyed by name. |\n\n```python\narchitectures = catalogue.create(\"spacy\", \"architectures\", entry_points=True)\n# Will get all entry points of the group \"spacy_architectures\"\nall_entry_points = architectures.get_entry_points()\n```\n\n#### method `Registry.get_entry_point`\n\nCheck if registered entry point is available for a given name in the namespace\nand load it. Otherwise, return the default value.\n\n| Argument | Type | Description |\n| ----------- | ---- | ------------------------------------------------ |\n| `name` | str | Name of entry point to load. |\n| `default` | Any | The default value to return. Defaults to `None`. |\n| **RETURNS** | Any | The loaded entry point or the default value. |\n\n```python\narchitectures = catalogue.create(\"spacy\", \"architectures\", entry_points=True)\n# Will get entry point \"custom_architecture\" of the group \"spacy_architectures\"\ncustom_architecture = architectures.get_entry_point(\"custom_architecture\")\n```\n\n#### method `Registry.find`\n\nFind the information about a registered function, including the module and path\nto the file it's defined in, the line number and the docstring, if available.\n\n| Argument | Type | Description |\n| ----------- | -------------------------- | ----------------------------------- |\n| `name` | str | Name of the registered function. |\n| **RETURNS** | Dict[str, Union[str, int]] | The information about the function. |\n\n```python\nimport catalogue\n\narchitectures = catalogue.create(\"spacy\", \"architectures\", entry_points=True)\n\n@architectures(\"my_architecture\")\ndef my_architecture():\n \"\"\"This is an architecture\"\"\"\n pass\n\ninfo = architectures.find(\"my_architecture\")\n# {'module': 'your_package.architectures',\n# 'file': '/path/to/your_package/architectures.py',\n# 'line_no': 5,\n# 'docstring': 'This is an architecture'}\n```\n\n### function `catalogue.check_exists`\n\nCheck if a namespace exists.\n\n| Argument | Type | Description |\n| ------------ | ---- | ------------------------------------------------------------ |\n| `*namespace` | str | The namespace, e.g. `\"spacy\"` or `\"spacy\", \"architectures\"`. |\n| **RETURNS** | bool | Whether the namespace exists. |\n","description_content_type":"text/markdown","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/explosion/catalogue","keywords":"","license":"MIT","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"catalogue","package_url":"https://pypi.org/project/catalogue/","platform":null,"project_url":"https://pypi.org/project/catalogue/","project_urls":{"Homepage":"https://github.com/explosion/catalogue"},"provides_extra":null,"release_url":"https://pypi.org/project/catalogue/2.0.10/","requires_dist":["zipp >=0.5 ; python_version < \"3.8\"","typing-extensions >=3.6.4 ; python_version < \"3.8\""],"requires_python":">=3.6","summary":"Super lightweight function registries for your library","version":"2.0.10","yanked":false,"yanked_reason":null}

Dependencies of catalogue (2).
Dependency	Optional
typing-extensions	false
zipp	false

Package search

catalogue

project_urls

Dependencies

All package metadata

Releases