{"id":13738163,"url":"https://github.com/cthoyt/class-resolver","last_synced_at":"2025-04-04T10:08:49.353Z","repository":{"id":39152988,"uuid":"343741010","full_name":"cthoyt/class-resolver","owner":"cthoyt","description":"🔍 Lookup classes and instantiate them with style","archived":false,"fork":false,"pushed_at":"2024-10-07T08:50:54.000Z","size":253,"stargazers_count":62,"open_issues_count":6,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-14T02:23:38.040Z","etag":null,"topics":["optuna","python","pytorch","utility"],"latest_commit_sha":null,"homepage":"https://class-resolver.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cthoyt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-02T10:52:09.000Z","updated_at":"2024-10-03T16:46:44.000Z","dependencies_parsed_at":"2024-09-14T23:39:50.882Z","dependency_job_id":"b452632e-1773-4dee-b1d7-9e58eb4a041f","html_url":"https://github.com/cthoyt/class-resolver","commit_stats":{"total_commits":192,"total_committers":6,"mean_commits":32.0,"dds":"0.11458333333333337","last_synced_commit":"c236a23165c6d6f5b59b4e0449cfde11e45d230d"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cthoyt%2Fclass-resolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cthoyt%2Fclass-resolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cthoyt%2Fclass-resolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cthoyt%2Fclass-resolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cthoyt","download_url":"https://codeload.github.com/cthoyt/class-resolver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157275,"owners_count":20893219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["optuna","python","pytorch","utility"],"created_at":"2024-08-03T03:02:12.892Z","updated_at":"2025-04-04T10:08:49.326Z","avatar_url":"https://github.com/cthoyt.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003c!--\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/source/logo.png\" height=\"150\"\u003e\n\u003c/p\u003e\n--\u003e\n\n\u003ch1 align=\"center\"\u003e\n  Class Resolver\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/cthoyt/class-resolver/actions?query=workflow%3ATests\"\u003e\n        \u003cimg alt=\"Tests\" src=\"https://github.com/cthoyt/class-resolver/workflows/Tests/badge.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/cthoyt/cookiecutter-python-package\"\u003e\n        \u003cimg alt=\"Cookiecutter template from @cthoyt\" src=\"https://img.shields.io/badge/Cookiecutter-snekpack-blue\" /\u003e \n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/class_resolver\"\u003e\n        \u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/class_resolver\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/class_resolver\"\u003e\n        \u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/class_resolver\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/cthoyt/class-resolver/blob/main/LICENSE\"\u003e\n        \u003cimg alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/class-resolver\" /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://class_resolver.readthedocs.io/en/latest/?badge=latest'\u003e\n        \u003cimg src='https://readthedocs.org/projects/class_resolver/badge/?version=latest' alt='Documentation Status' /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/cthoyt/class-resolver/branch/main\"\u003e\n        \u003cimg src=\"https://codecov.io/gh/cthoyt/class-resolver/branch/main/graph/badge.svg\" alt=\"Codecov status\" /\u003e\n    \u003c/a\u003e  \n    \u003ca href=\"https://zenodo.org/badge/latestdoi/343741010\"\u003e\n        \u003cimg src=\"https://zenodo.org/badge/343741010.svg\" alt=\"DOI\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/psf/black\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code style: black\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nLookup and instantiate classes with style.\n\n## 💪 Getting Started\n\n```python\nfrom class_resolver import ClassResolver\nfrom dataclasses import dataclass\n\nclass Base: pass\n\n@dataclass\nclass A(Base):\n   name: str\n\n@dataclass\nclass B(Base):\n   name: str\n\n# Index\nresolver = ClassResolver([A, B], base=Base)\n\n# Lookup\nassert A == resolver.lookup('A')\n\n# Instantiate with a dictionary\nassert A(name='hi') == resolver.make('A', {'name': 'hi'})\n\n# Instantiate with kwargs\nassert A(name='hi') == resolver.make('A', name='hi')\n\n# A pre-instantiated class will simply be passed through\nassert A(name='hi') == resolver.make(A(name='hi'))\n```\n\n## 🤖 Writing Extensible Machine Learning Models with `class-resolver`\n\nAssume you've implemented a simple multi-layer perceptron in PyTorch:\n\n```python\nfrom itertools import chain\n\nfrom more_itertools import pairwise\nfrom torch import nn\n\nclass MLP(nn.Sequential):\n    def __init__(self, dims: list[int]):\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                nn.ReLU(),\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nThis MLP uses a hard-coded rectified linear unit as the non-linear activation\nfunction between layers. We can generalize this MLP to use a variety of\nnon-linear activation functions by adding an argument to its\n`__init__()` function like in:\n\n```python\nfrom itertools import chain\n\nfrom more_itertools import pairwise\nfrom torch import nn\n\nclass MLP(nn.Sequential):\n    def __init__(self, dims: list[int], activation: str = \"relu\"):\n        if activation == \"relu\":\n            activation = nn.ReLU()\n        elif activation == \"tanh\":\n            activation = nn.Tanh()\n        elif activation == \"hardtanh\":\n            activation = nn.Hardtanh()\n        else:\n            raise KeyError(f\"Unsupported activation: {activation}\")\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                activation,\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nThe first issue with this implementation is it relies on a hard-coded set of\nconditional statements and is therefore hard to extend. It can be improved\nby using a dictionary lookup:\n\n```python\nfrom itertools import chain\n\nfrom more_itertools import pairwise\nfrom torch import nn\n\nactivation_lookup: dict[str, nn.Module] = {\n   \"relu\": nn.ReLU(),\n   \"tanh\": nn.Tanh(),\n   \"hardtanh\": nn.Hardtanh(),\n}\n\nclass MLP(nn.Sequential):\n    def __init__(self, dims: list[int], activation: str = \"relu\"):\n        activation = activation_lookup[activation]\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                activation,\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nThis approach is rigid because it requires pre-instantiation of the activations.\nIf we needed to vary the arguments to the `nn.HardTanh` class, the previous\napproach wouldn't work. We can change the implementation to lookup on the \nclass *before instantiation* then optionally pass some arguments:\n\n```python\nfrom itertools import chain\n\nfrom more_itertools import pairwise\nfrom torch import nn\n\nactivation_lookup: dict[str, type[nn.Module]] = {\n   \"relu\": nn.ReLU,\n   \"tanh\": nn.Tanh,\n   \"hardtanh\": nn.Hardtanh,\n}\n\nclass MLP(nn.Sequential):\n    def __init__(\n        self, \n        dims: list[int], \n        activation: str = \"relu\", \n        activation_kwargs: None | dict[str, any] = None,\n    ):\n        activation_cls = activation_lookup[activation]\n        activation = activation_cls(**(activation_kwargs or {}))\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                activation,\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nThis is pretty good, but it still has a few issues:\n1. you have to manually maintain the `activation_lookup` dictionary,\n2. you can't pass an instance or class through the `activation` keyword\n3. you have to get the casing just right\n4. the default is hard-coded as a string, which means this has to get copied\n   (error-prone) in any place that creates an MLP\n5. you have to re-write this logic for all of your classes\n\nEnter the `class_resolver` package, which takes care of all of these\nthings using the following:\n\n```python\nfrom itertools import chain\n\nfrom class_resolver import ClassResolver, Hint\nfrom more_itertools import pairwise\nfrom torch import nn\n\nactivation_resolver = ClassResolver(\n    [nn.ReLU, nn.Tanh, nn.Hardtanh],\n    base=nn.Module,\n    default=nn.ReLU,\n)\n\nclass MLP(nn.Sequential):\n    def __init__(\n        self, \n        dims: list[int], \n        activation: Hint[nn.Module] = None,  # Hint = Union[None, str, nn.Module, type[nn.Module]]\n        activation_kwargs: None | dict[str, any] = None,\n    ):\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                activation_resolver.make(activation, activation_kwargs),\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nBecause this is such a common pattern, we've made it available through contrib\nmodule in `class_resolver.contrib.torch`:\n\n```python\nfrom itertools import chain\n\nfrom class_resolver import Hint\nfrom class_resolver.contrib.torch import activation_resolver\nfrom more_itertools import pairwise\nfrom torch import nn\n\nclass MLP(nn.Sequential):\n    def __init__(\n        self, \n        dims: list[int], \n        activation: Hint[nn.Module] = None,\n        activation_kwargs: None | dict[str, any] = None,\n    ):\n        super().__init__(chain.from_iterable(\n            (\n                nn.Linear(in_features, out_features),\n                activation_resolver.make(activation, activation_kwargs),\n            )\n            for in_features, out_features in pairwise(dims)\n        ))\n```\n\nNow, you can instantiate the MLP with any of the following:\n\n```python\nMLP(dims=[10, 200, 40])  # uses default, which is ReLU\nMLP(dims=[10, 200, 40], activation=\"relu\")  # uses lowercase\nMLP(dims=[10, 200, 40], activation=\"ReLU\")  # uses stylized\nMLP(dims=[10, 200, 40], activation=nn.ReLU)  # uses class\nMLP(dims=[10, 200, 40], activation=nn.ReLU())  # uses instance\n\nMLP(dims=[10, 200, 40], activation=\"hardtanh\", activation_kwargs={\"min_val\": 0.0, \"max_value\": 6.0})  # uses kwargs\nMLP(dims=[10, 200, 40], activation=nn.HardTanh, activation_kwargs={\"min_val\": 0.0, \"max_value\": 6.0})  # uses kwargs\nMLP(dims=[10, 200, 40], activation=nn.HardTanh(0.0, 6.0))  # uses instance\n```\n\nIn practice, it makes sense to stick to using the strings in combination with\nhyper-parameter optimization libraries like [Optuna](https://optuna.org/).\n\n## ⬇️ Installation\n\nThe most recent release can be installed from\n[PyPI](https://pypi.org/project/class_resolver/) with:\n\n```bash\n$ pip install class_resolver\n```\n\nThe most recent code and data can be installed directly from GitHub with:\n\n```bash\n$ pip install git+https://github.com/cthoyt/class-resolver.git\n```\n\nTo install in development mode, use the following:\n\n```bash\n$ git clone git+https://github.com/cthoyt/class-resolver.git\n$ cd class-resolver\n$ pip install -e .\n```\n\n## 🙏 Contributing\n\nContributions, whether filing an issue, making a pull request, or forking, are appreciated. See\n[CONTRIBUTING.rst](https://github.com/cthoyt/class-resolver/blob/master/CONTRIBUTING.rst) for more\ninformation on getting involved.\n\n## 👋 Attribution\n\n### ⚖️ License\n\nThe code in this package is licensed under the MIT License.\n\n### 🍪 Cookiecutter\n\nThis package was created with [@audreyfeldroy](https://github.com/audreyfeldroy)'s\n[cookiecutter](https://github.com/cookiecutter/cookiecutter) package using [@cthoyt](https://github.com/cthoyt)'s\n[cookiecutter-snekpack](https://github.com/cthoyt/cookiecutter-snekpack) template.\n\n## 🛠️ For Developers\n\n\u003cdetails\u003e\n  \u003csummary\u003eSee developer instructions\u003c/summary\u003e\n\n\nThe final section of the README is for if you want to get involved by making a code contribution.\n\n### ❓ Testing\n\nAfter cloning the repository and installing `tox` with `pip install tox`, the unit tests in the `tests/` folder can be\nrun reproducibly with:\n\n```shell\n$ tox\n```\n\nAdditionally, these tests are automatically re-run with each commit in a [GitHub Action](https://github.com/{{cookiecutter.github_organization_name}}/{{cookiecutter.github_repository_name}}/actions?query=workflow%3ATests).\n\n### 📦 Making a Release\n\nAfter installing the package in development mode and installing\n`tox` with `pip install tox`, the commands for making a new release are contained within the `finish` environment\nin `tox.ini`. Run the following from the shell:\n\n```shell\n$ tox -e finish\n```\n\nThis script does the following:\n\n1. Uses BumpVersion to switch the version number in the `setup.cfg` and\n   `src/{{cookiecutter.package_name}}/version.py` to not have the `-dev` suffix\n2. Packages the code in both a tar archive and a wheel\n3. Uploads to PyPI using `twine`. Be sure to have a `.pypirc` file configured to avoid the need for manual input at this\n   step\n4. Push to GitHub. You'll need to make a release going with the commit where the version was bumped.\n5. Bump the version to the next patch. If you made big changes and want to bump the version by minor, you can\n   use `tox -e bumpversion minor` after.\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcthoyt%2Fclass-resolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcthoyt%2Fclass-resolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcthoyt%2Fclass-resolver/lists"}