# 🐎 Colt
[](https://github.com/altescy/colt/actions?query=workflow%3ACI)
[](https://github.com/altescy/colt/actions?query=workflow%3Apublish)
[](https://github.com/altescy/colt)
[](https://pypi.org/project/colt/)
[](https://github.com/altescy/colt/blob/master/LICENSE)
Effortlessly configure and construct Python objects with `colt`, a lightweight library inspired by [AllenNLP](https://github.com/allenai/allennlp) and [Tango](https://github.com/allenai/tango)
## Quick Links
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Influences](#influences)
- [kaggle Titanic Example](https://github.com/altescy/colt/tree/master/examples/titanic)
## Introduction
`colt` is a lightweight configuration utility for Python objects, allowing you to manage complex configurations for your projects easily.
Written solely using the Python standard library, `colt` can construct class objects from JSON-convertible dictionaries, making it simple to manage your settings using JSON or YAML files. The library is particularly suitable for the [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection) design pattern.
Some key features of colt include:
- No external dependencies, as it is built using the Python standard library.
- Construct class objects from JSON-convertible dictionaries.
- Manage complex configurations using JSON or YAML files.
- Well-suited for dependency injection design patterns.
Inspired by [AllenNLP](https://github.com/allenai/allennlp) and [Tango](https://github.com/allenai/tango), `colt` aims to offer similar functionality while focusing on a more lightweight and user-friendly design.
### Differences between `colt` and AllenNLP/Tango
While both AllenNLP and Tango construct objects based on the class signature, colt focuses on building objects from the type specified in the configuration. Although colt is aware of the class signature, it primarily uses it for validation when passing objects created from the configuration.
This means that with colt, you don't necessarily need to have the target class available for configuration. As a result, you can conveniently build objects using the colt.build method without requiring the specific class to be present. This distinction makes colt more flexible and easier to work with in various scenarios.
## Installation
To install colt, simply run the following command:
```shell
pip install colt
```
## Usage
### Basic Example
Here is a basic example of how to use `colt` to create class objects from a configuration dictionary:
```python
import typing as tp
import colt
@colt.register("foo")
class Foo:
def __init__(self, message: str) -> None:
self.message = message
@colt.register("bar")
class Bar:
def __init__(self, foos: tp.List[Foo]) -> None:
self.foos = foos
if __name__ == "__main__":
config = {
"@type": "bar", # specify type name with `@type`
"foos": [
{"message": "hello"}, # type of this is inferred from type-hint
{"message": "world"},
]
}
bar = colt.build(config)
assert isinstance(bar, Bar)
print(" ".join(foo.message for foo in bar.foos))
# => "hello world"
```
### Functionality
#### Guiding Object Construction with a Target Class
You can guide the object construction process in `colt` by passing the desired class as the second argument to the `colt.build` method.
Here's an example demonstrating this functionality:
```python
@colt.register("foo")
class Foo:
def __init__(self, x: str) -> None:
self.x = x
config = {"x": "abc"}
# Pass the desired class as the second argument
obj = colt.build(config, Foo)
assert isinstance(obj, Foo)
assert obj.x == "abc"
```
By providing the target class to `colt.build`, you can ensure the constructed object is of the desired type while still using the configuration for parameter values.
#### `Registrable` class
`colt` provides the Registrable class, which allows you to divide the namespace for each class.
This can be particularly useful when working with larger projects or when you need to manage multiple classes with the same name but different functionality.
Here is an example of how to use the `Registrable` class to manage different namespaces for `Foo` and `Bar`:
```python
import colt
class Foo(colt.Registrable):
pass
class Bar(colt.Registrable):
pass
@Foo.register("baz")
class FooBaz(Foo):
pass
@Bar.register("baz")
class BarBaz(Bar):
pass
@colt.register("my_class")
class MyClass:
def __init__(self, foo: Foo, bar: Bar):
self.foo = foo
self.bar = bar
if __name__ == "__main__":
config = {
"@type": "my_class",
"foo": {"@type": "baz"},
"bar": {"@type": "baz"}
}
obj = colt.build(config)
assert isinstance(obj.foo, FooBaz)
assert isinstance(obj.bar, BarBaz)
```
#### `Lazy` class
`colt` offers a `Lazy` class for deferring object creation until needed, which can be useful in cases where constructing an object is computationally expensive or should be delayed until certain conditions are met.
Here's a concise example demonstrating the `Lazy` class usage with `colt`:
```python
import dataclasses
import colt
from colt import Lazy
@dataclasses.dataclass
class Foo:
x: str
y: int
@dataclasses.dataclass
class Bar:
foo: Lazy[Foo]
bar = colt.build({"foo": {"x": "hello"}}, Bar)
# Additional parameters can be passed when calling the construct() method
foo = bar.foo.construct(y=10)
```
In this example, `Bar` contains a `Lazy` instance of `Foo`, which will only be constructed when `construct()` is called.
When calling `construct()`, you can pass additional parameters required for the object's construction.
This approach allows you to control when an object is created, optimizing resource usage and computations while providing flexibility in passing parameters.
### Advanced Examples
#### scikit-learn Configuration
Here's an example of how to use `colt` to configure a [scikit-learn](https://scikit-learn.org/) model:
```python
import colt
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
if __name__ == "__main__":
config = {
# these types are imported automatically if type name is not registerd
"@type": "sklearn.ensemble.VotingClassifier",
"estimators": [
("rfc", { "@type": "sklearn.ensemble.RandomForestClassifier",
"n_estimators": 10 }),
("svc", { "@type": "sklearn.svm.SVC",
"gamma": "scale" }),
]
}
X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)
model = colt.build(config)
model.fit(X_train, y_train)
valid_accuracy = model.score(X_valid, y_valid)
print(f"valid_accuracy: {valid_accuracy}")
```
In this example, `colt` is used to configure a `VotingClassifier` from scikit-learn, combining a `RandomForestClassifier` and an `SVC`.
The colt configuration dictionary makes it easy to manage the settings of these classifiers and modify them as needed.
## Influences
`colt` is heavily influenced by the following projects:
- [AllenNLP](https://github.com/allenai/allennlp): A popular natural language processing library, which provides a powerful configuration system for managing complex experiments.
- [Tango](https://github.com/allenai/tango): A lightweight and flexible library for running machine learning experiments, designed to work well with AllenNLP and other libraries.
These projects have demonstrated the value of a robust configuration system for managing machine learning experiments and inspired the design of `colt`.
Raw data
{
"_id": null,
"home_page": "https://github.com/altescy/colt",
"name": "colt",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "config, python, object",
"author": "altescy",
"author_email": "altescy@fastmail.com",
"download_url": "https://files.pythonhosted.org/packages/45/bb/0e5b130d94877272722d0b9ac4f4feb2d99f2b0332d7677f3d1ce2175904/colt-0.11.2.tar.gz",
"platform": null,
"description": "# \ud83d\udc0e Colt\n\n[](https://github.com/altescy/colt/actions?query=workflow%3ACI)\n[](https://github.com/altescy/colt/actions?query=workflow%3Apublish)\n[](https://github.com/altescy/colt)\n[](https://pypi.org/project/colt/)\n[](https://github.com/altescy/colt/blob/master/LICENSE)\n\nEffortlessly configure and construct Python objects with `colt`, a lightweight library inspired by [AllenNLP](https://github.com/allenai/allennlp) and [Tango](https://github.com/allenai/tango)\n\n## Quick Links\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Influences](#influences)\n- [kaggle Titanic Example](https://github.com/altescy/colt/tree/master/examples/titanic)\n\n## Introduction\n\n`colt` is a lightweight configuration utility for Python objects, allowing you to manage complex configurations for your projects easily.\nWritten solely using the Python standard library, `colt` can construct class objects from JSON-convertible dictionaries, making it simple to manage your settings using JSON or YAML files. The library is particularly suitable for the [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection) design pattern.\n\nSome key features of colt include:\n\n- No external dependencies, as it is built using the Python standard library.\n- Construct class objects from JSON-convertible dictionaries.\n- Manage complex configurations using JSON or YAML files.\n- Well-suited for dependency injection design patterns.\n\nInspired by [AllenNLP](https://github.com/allenai/allennlp) and [Tango](https://github.com/allenai/tango), `colt` aims to offer similar functionality while focusing on a more lightweight and user-friendly design.\n\n### Differences between `colt` and AllenNLP/Tango\n\nWhile both AllenNLP and Tango construct objects based on the class signature, colt focuses on building objects from the type specified in the configuration. Although colt is aware of the class signature, it primarily uses it for validation when passing objects created from the configuration.\n\nThis means that with colt, you don't necessarily need to have the target class available for configuration. As a result, you can conveniently build objects using the colt.build method without requiring the specific class to be present. This distinction makes colt more flexible and easier to work with in various scenarios.\n\n## Installation\n\nTo install colt, simply run the following command:\n\n```shell\npip install colt\n```\n\n## Usage\n\n### Basic Example\n\nHere is a basic example of how to use `colt` to create class objects from a configuration dictionary:\n\n```python\nimport typing as tp\nimport colt\n\n@colt.register(\"foo\")\nclass Foo:\n def __init__(self, message: str) -> None:\n self.message = message\n\n@colt.register(\"bar\")\nclass Bar:\n def __init__(self, foos: tp.List[Foo]) -> None:\n self.foos = foos\n\nif __name__ == \"__main__\":\n config = {\n \"@type\": \"bar\", # specify type name with `@type`\n \"foos\": [\n {\"message\": \"hello\"}, # type of this is inferred from type-hint\n {\"message\": \"world\"},\n ]\n }\n\n bar = colt.build(config)\n\n assert isinstance(bar, Bar)\n\n print(\" \".join(foo.message for foo in bar.foos))\n # => \"hello world\"\n```\n\n### Functionality\n\n#### Guiding Object Construction with a Target Class\n\nYou can guide the object construction process in `colt` by passing the desired class as the second argument to the `colt.build` method.\nHere's an example demonstrating this functionality:\n\n```python\n@colt.register(\"foo\")\nclass Foo:\n def __init__(self, x: str) -> None:\n self.x = x\n\nconfig = {\"x\": \"abc\"}\n\n# Pass the desired class as the second argument\nobj = colt.build(config, Foo)\n\nassert isinstance(obj, Foo)\nassert obj.x == \"abc\"\n```\n\nBy providing the target class to `colt.build`, you can ensure the constructed object is of the desired type while still using the configuration for parameter values.\n\n#### `Registrable` class\n\n`colt` provides the Registrable class, which allows you to divide the namespace for each class.\nThis can be particularly useful when working with larger projects or when you need to manage multiple classes with the same name but different functionality.\n\nHere is an example of how to use the `Registrable` class to manage different namespaces for `Foo` and `Bar`:\n\n```python\nimport colt\n\nclass Foo(colt.Registrable):\n pass\n\nclass Bar(colt.Registrable):\n pass\n\n@Foo.register(\"baz\")\nclass FooBaz(Foo):\n pass\n\n@Bar.register(\"baz\")\nclass BarBaz(Bar):\n pass\n\n@colt.register(\"my_class\")\nclass MyClass:\n def __init__(self, foo: Foo, bar: Bar):\n self.foo = foo\n self.bar = bar\n\nif __name__ == \"__main__\":\n config = {\n \"@type\": \"my_class\",\n \"foo\": {\"@type\": \"baz\"},\n \"bar\": {\"@type\": \"baz\"}\n }\n\n obj = colt.build(config)\n\n assert isinstance(obj.foo, FooBaz)\n assert isinstance(obj.bar, BarBaz)\n```\n\n#### `Lazy` class\n\n`colt` offers a `Lazy` class for deferring object creation until needed, which can be useful in cases where constructing an object is computationally expensive or should be delayed until certain conditions are met.\n\nHere's a concise example demonstrating the `Lazy` class usage with `colt`:\n\n```python\nimport dataclasses\nimport colt\nfrom colt import Lazy\n\n@dataclasses.dataclass\nclass Foo:\n x: str\n y: int\n\n@dataclasses.dataclass\nclass Bar:\n foo: Lazy[Foo]\n\nbar = colt.build({\"foo\": {\"x\": \"hello\"}}, Bar)\n\n# Additional parameters can be passed when calling the construct() method\nfoo = bar.foo.construct(y=10)\n```\n\nIn this example, `Bar` contains a `Lazy` instance of `Foo`, which will only be constructed when `construct()` is called.\nWhen calling `construct()`, you can pass additional parameters required for the object's construction.\nThis approach allows you to control when an object is created, optimizing resource usage and computations while providing flexibility in passing parameters.\n\n### Advanced Examples\n\n#### scikit-learn Configuration\n\nHere's an example of how to use `colt` to configure a [scikit-learn](https://scikit-learn.org/) model:\n\n```python\nimport colt\n\nfrom sklearn.datasets import load_iris\nfrom sklearn.model_selection import train_test_split\n\nif __name__ == \"__main__\":\n config = {\n # these types are imported automatically if type name is not registerd\n \"@type\": \"sklearn.ensemble.VotingClassifier\",\n \"estimators\": [\n (\"rfc\", { \"@type\": \"sklearn.ensemble.RandomForestClassifier\",\n \"n_estimators\": 10 }),\n (\"svc\", { \"@type\": \"sklearn.svm.SVC\",\n \"gamma\": \"scale\" }),\n ]\n }\n\n X, y = load_iris(return_X_y=True)\n X_train, X_valid, y_train, y_valid = train_test_split(X, y)\n\n model = colt.build(config)\n model.fit(X_train, y_train)\n\n valid_accuracy = model.score(X_valid, y_valid)\n print(f\"valid_accuracy: {valid_accuracy}\")\n```\n\nIn this example, `colt` is used to configure a `VotingClassifier` from scikit-learn, combining a `RandomForestClassifier` and an `SVC`.\nThe colt configuration dictionary makes it easy to manage the settings of these classifiers and modify them as needed.\n\n## Influences\n\n`colt` is heavily influenced by the following projects:\n\n- [AllenNLP](https://github.com/allenai/allennlp): A popular natural language processing library, which provides a powerful configuration system for managing complex experiments.\n- [Tango](https://github.com/allenai/tango): A lightweight and flexible library for running machine learning experiments, designed to work well with AllenNLP and other libraries.\n\nThese projects have demonstrated the value of a robust configuration system for managing machine learning experiments and inspired the design of `colt`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A configuration utility for Python object.",
"version": "0.11.2",
"project_urls": {
"Homepage": "https://github.com/altescy/colt",
"Issues": "https://github.com/altescy/colt/issues"
},
"split_keywords": [
"config",
" python",
" object"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb5992db3cc01f26bfe688794ea8f10797048ad60cb10ec2bffab40e979b95c0",
"md5": "cc8c32cc8c5d4dd5832cce84cbd76fe9",
"sha256": "079cd8bb6cec9d62c472ad59ef4cec2524f59ec7ec9865c6f8ea84d0c0602136"
},
"downloads": -1,
"filename": "colt-0.11.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc8c32cc8c5d4dd5832cce84cbd76fe9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 10889,
"upload_time": "2024-03-25T12:32:03",
"upload_time_iso_8601": "2024-03-25T12:32:03.386881Z",
"url": "https://files.pythonhosted.org/packages/eb/59/92db3cc01f26bfe688794ea8f10797048ad60cb10ec2bffab40e979b95c0/colt-0.11.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45bb0e5b130d94877272722d0b9ac4f4feb2d99f2b0332d7677f3d1ce2175904",
"md5": "3c4875978039b9657ca4f0d21c93e0bf",
"sha256": "b4be6a992b78204ae1b889a6894db04967c6aaf05fb6f2f4d3b78aa2ba24add5"
},
"downloads": -1,
"filename": "colt-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "3c4875978039b9657ca4f0d21c93e0bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 11984,
"upload_time": "2024-03-25T12:32:04",
"upload_time_iso_8601": "2024-03-25T12:32:04.549680Z",
"url": "https://files.pythonhosted.org/packages/45/bb/0e5b130d94877272722d0b9ac4f4feb2d99f2b0332d7677f3d1ce2175904/colt-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 12:32:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "altescy",
"github_project": "colt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "colt"
}
JSON
