# wonka
<p align="center">
<img src="https://github.com/WithPrecedent/wonka/blob/main/docs/images/logo.png?raw=true" alt="logo" style="width:250px;"/>
</p>
| | |
| --- | --- |
| Version | [](https://pypi.org/project/wonka/) [](https://github.com/WithPrecedent/wonka/releases)
| Status | [](https://github.com/WithPrecedent/wonka/actions/workflows/ci.yml?query=branch%3Amain) [](https://www.repostatus.org/#active) [](https://pypi.org/project/wonka/)
| Documentation | [](https://WithPrecedent.github.io/wonka)
| Tools | [](https://squidfunk.github.io/mkdocs-material/) [](https://github.com/astral-sh/Ruff) [](https://PDM.fming.dev) [](https://github.com/TezRomacH/python-package-template/blob/master/.pre-commit-config.yaml) [](https://github.com/features/actions) [](https://editorconfig.org/) [](https://www.github.com/WithPrecedent/wonka) [](https://github.com/dependabot)
| Compatibility | [](https://pypi.python.org/pypi/wonka/) [](https://www.linux.org/) [](https://www.apple.com/macos/) [](https://www.microsoft.com/en-us/windows?r=1)
| Stats | [](https://pypi.org/project/wonka) [](https://github.com/WithPrecedent/wonka/stargazers) [](https://github.com/WithPrecedent/wonka/graphs/contributors) [](https://github.com/WithPrecedent/wonka/graphs/contributors) [](https://github.com/WithPrecedent/wonka/forks)
| | |
-----
## What is wonka?
`wonka`[^1] is an extensible library for simple implementation of class and
object constructors in Python. Out-of-the-box, `wonka` has implementations of
several common creational design patterns, including: registry factories,
prototypers, and composite builder workflows. It is also easy to extend `wonka`
by adding your own custom factories[^2] while taking advantage of `wonka`'s
convenient mixin classes and helper functions.
This readme offers a basic outline of how `wonka` works. If you would prefer to jump right into the full documentation, go [here](https://WithPrecedent.github.io/wonka).
## Why use wonka?
<p align="center">
<img src="https://media.giphy.com/media/y0SJVYxf90J1u/giphy.gif" alt="The suspense is terrible. I hope it'll last" style="width:300px;"/>
</p>
*“No other factory in the world mixes its chocolate by waterfall… But it’s the only way if you want it just right.”* - Willy Wonka
Factories are essential components of coding projects that require dynamic, runtime implementation of different strategies or options. In Python packages, despite their commmon usage, factories are often poorly implemented, fragile, or inflexible. `wonka` addresses those common shortcomings by offering convenient creation through a simple, adaptable system that has almost no learning curve[^3]. `wonka` is:
* **Intuitive**: factories use a common interface with a `create` class method for all construction operations.
* **Extensible**: core classes can be adapted and extended through inheritance or composition.
* **Flexible**: whenever possible, factories can be mixed in for class and object self-creation or be used for creating external items.
* **Lightweight**: the library has a miniscule memory footprint with few dependencies.
* **Robust**: "turn-key" factories handle edge cases and core scenarios without needing further tinkering.
* **Accessible**: `wonka` is over-documented to make it accessible to beginnning coders and readily usable for developers at all levels.
## Getting started
<p align="center">
<img src="https://media4.giphy.com/media/Tt9jctxaVjRny/giphy.gif" alt="Please, tell us more" style="width:350px;"/>
</p>
### Installation
To install `wonka`, use `pip`:
```sh
pip install wonka
```
### Usage
There are three categories of base classes in `wonka`: factories, managers, and producers. Each is described in greater detail below.
#### Factories
<p align="center">
<img src="https://media2.giphy.com/media/o4aGs2I3rVKjC/giphy.gif" alt="Come with me and you'll be in a world of pure imagination" style="width:350px;"/>
</p>
All `wonka` factory classes have a `create` class method which is used to construct new items. The only required parameter for `create` is `item`, which contains the data for building products.
Out-of-the-box, this library offers three general subtypes of its base `Factory` class. These are not subclasses, but rather describe the type of functionality in the included `Factory` subclasses.
* Registries - factories that build classes or objects from explicit or implicit registries.
* Dispatchers - factories that call appropriate creation methods or functions based on the type or content of data passed.
* Prototypers - factories that clone exsting classes or objects.
#### Managers
<p align="center">
<img src="https://media.giphy.com/media/NsBAHgohHByp2/giphy.gif" alt="Don't just stand there! Do something!" style="width:300px;"/>
</p>
For more complex construction, you can use subclasses of `Manager`, which is an iterable constructor. Every `Manager` subclass may construct items in three ways:
1. Calling its `manage` method.
2. Calling its `create` method (which just calls the `manage` method, but this allows a `Manager` subclass instance to be used anywhere a `Factory` could be used while still being distinguishable from an ordinary `Factory`).
3. Iterating it directly.
#### Producers
<p align="center">
<img src="https://media4.giphy.com/media/l0HlHSB8v5yRtBlHW/giphy.gif" alt="Willy Wonka completes a forward roll and pops up" style="width:350px;"/>
</p>
As another optional feature, `wonka` supports post-construction modification of built items through subclasses of `Producer`. This is particularly important for factories that use other resources (such as registries). `wonka` [separates concerns](https://dev.to/suspir0n/soc-separation-of-concerns-5ak7) so that the return value can be modified through a simple mixin system. This division of labor makes it incredibly easy to put together a `Factory` or `Manager` with a `Producer`.
## Contributing
Contributors are always welcome. Feel free to grab an [issue](https://www.github.com/WithPrecedent/wonka/issues) to work on or make a suggested improvement. If you wish to contribute, please read the [Contribution Guide](https://www.github.com/WithPrecedent/wonka/contributing.md) and [Code of Conduct](https://www.github.com/WithPrecedent/wonka/code_of_conduct.md).
## Similar Projects
If `wonka` does not fit your needs, you might find one of these other packages helpful. None of them does the same things that `wonka` does (which is why I created this library), but they might fit your particular project needs better.
<p align="center">
<img src="https://media.giphy.com/media/Bu8ADbj7NuRry/giphy.gif" alt="Stop. Don't. Come back." style="width:300px;"/>
</p>
* [dataclass_factory](https://github.com/reagento/dataclass-factory): factory for dataclass production from other common data types.
* [factory_boy](https://github.com/FactoryBoy/factory_boy): tool for dynamically creating objects for unit testing in Python.
* [Model Bakery](https://github.com/model-bakers/model_bakery): object factory for Django.
* [Polyfactory](https://github.com/litestar-org/polyfactory): factory framework for mock data generation.
## Acknowledgments
I would like to thank the University of Kansas School of Law for tolerating and
supporting this law professor's coding efforts, an endeavor which is well
outside the typical scholarly activities in the discipline.
Lastly, I want to extend a special thanks to the late, great Gene Wilder, whose
work inspired the name of this project and made my childhood better.
<p align="center">
<img src="https://media.giphy.com/media/3o6ZtbOoOHu28ftYiI/giphy.gif" alt="RIP, Gene Wilder, 1933-2016" style="width:200px;"/>
</p>
## License
Use of this repository is authorized under the [Apache Software License 2.0](https://www.github.com/WithPrecedent/wonka/blog/main/LICENSE).
[^1]: This project is not affiliated with Willy Wonka candy, either of the Willy Wonka films (especially the Johnny Depp one), or any other Willy Wonka product. It's just named "wonka" because all of the most obvious names for a Python package of factories and other constructors on [pypi.org](https://pypi.org) were taken and Willy Wonka's insane candy factory was the first relevant pop-culture touchstone I could think of.
[^2]: For the sake of brevity, the documentation refers to all of `wonka`'s constructors as "factories," even though many do not fit the definition of the classic [factory design pattern](https://realpython.com/factory-method-python/).
[^3]: Chocolate waterfalls are, sadly, only virtually implemented in `wonka`.
Raw data
{
"_id": null,
"home_page": null,
"name": "wonka",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "factory construction constructor design pattern",
"author": null,
"author_email": "Corey Rayburn Yung <coreyrayburnyung@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2c/dc/e23f8d845503d4f419b053a058734a01d6e17902810669939fd9bb2ec395/wonka-0.1.4.tar.gz",
"platform": null,
"description": "# wonka\n\n<p align=\"center\">\n<img src=\"https://github.com/WithPrecedent/wonka/blob/main/docs/images/logo.png?raw=true\" alt=\"logo\" style=\"width:250px;\"/>\n</p>\n\n| | |\n| --- | --- |\n| Version | [](https://pypi.org/project/wonka/) [](https://github.com/WithPrecedent/wonka/releases)\n| Status | [](https://github.com/WithPrecedent/wonka/actions/workflows/ci.yml?query=branch%3Amain) [](https://www.repostatus.org/#active) [](https://pypi.org/project/wonka/)\n| Documentation | [](https://WithPrecedent.github.io/wonka)\n| Tools | [](https://squidfunk.github.io/mkdocs-material/) [](https://github.com/astral-sh/Ruff) [](https://PDM.fming.dev) [](https://github.com/TezRomacH/python-package-template/blob/master/.pre-commit-config.yaml) [](https://github.com/features/actions) [](https://editorconfig.org/) [](https://www.github.com/WithPrecedent/wonka) [](https://github.com/dependabot)\n| Compatibility | [](https://pypi.python.org/pypi/wonka/) [](https://www.linux.org/) [](https://www.apple.com/macos/) [](https://www.microsoft.com/en-us/windows?r=1)\n| Stats | [](https://pypi.org/project/wonka) [](https://github.com/WithPrecedent/wonka/stargazers) [](https://github.com/WithPrecedent/wonka/graphs/contributors) [](https://github.com/WithPrecedent/wonka/graphs/contributors) [](https://github.com/WithPrecedent/wonka/forks)\n| | |\n\n-----\n\n## What is wonka?\n\n`wonka`[^1] is an extensible library for simple implementation of class and\nobject constructors in Python. Out-of-the-box, `wonka` has implementations of\nseveral common creational design patterns, including: registry factories,\nprototypers, and composite builder workflows. It is also easy to extend `wonka`\nby adding your own custom factories[^2] while taking advantage of `wonka`'s\nconvenient mixin classes and helper functions. \n\nThis readme offers a basic outline of how `wonka` works. If you would prefer to jump right into the full documentation, go [here](https://WithPrecedent.github.io/wonka).\n\n## Why use wonka?\n\n<p align=\"center\">\n<img src=\"https://media.giphy.com/media/y0SJVYxf90J1u/giphy.gif\" alt=\"The suspense is terrible. I hope it'll last\" style=\"width:300px;\"/>\n</p>\n\n*\u201cNo other factory in the world mixes its chocolate by waterfall\u2026 But it\u2019s the only way if you want it just right.\u201d* - Willy Wonka\n\nFactories are essential components of coding projects that require dynamic, runtime implementation of different strategies or options. In Python packages, despite their commmon usage, factories are often poorly implemented, fragile, or inflexible. `wonka` addresses those common shortcomings by offering convenient creation through a simple, adaptable system that has almost no learning curve[^3]. `wonka` is:\n\n* **Intuitive**: factories use a common interface with a `create` class method for all construction operations.\n* **Extensible**: core classes can be adapted and extended through inheritance or composition.\n* **Flexible**: whenever possible, factories can be mixed in for class and object self-creation or be used for creating external items.\n* **Lightweight**: the library has a miniscule memory footprint with few dependencies.\n* **Robust**: \"turn-key\" factories handle edge cases and core scenarios without needing further tinkering.\n* **Accessible**: `wonka` is over-documented to make it accessible to beginnning coders and readily usable for developers at all levels.\n\n## Getting started\n\n<p align=\"center\">\n<img src=\"https://media4.giphy.com/media/Tt9jctxaVjRny/giphy.gif\" alt=\"Please, tell us more\" style=\"width:350px;\"/>\n</p>\n\n### Installation\n\nTo install `wonka`, use `pip`:\n\n```sh\npip install wonka\n```\n\n### Usage\n\nThere are three categories of base classes in `wonka`: factories, managers, and producers. Each is described in greater detail below.\n\n#### Factories\n\n<p align=\"center\">\n<img src=\"https://media2.giphy.com/media/o4aGs2I3rVKjC/giphy.gif\" alt=\"Come with me and you'll be in a world of pure imagination\" style=\"width:350px;\"/>\n</p>\n\nAll `wonka` factory classes have a `create` class method which is used to construct new items. The only required parameter for `create` is `item`, which contains the data for building products.\n\nOut-of-the-box, this library offers three general subtypes of its base `Factory` class. These are not subclasses, but rather describe the type of functionality in the included `Factory` subclasses.\n\n* Registries - factories that build classes or objects from explicit or implicit registries.\n* Dispatchers - factories that call appropriate creation methods or functions based on the type or content of data passed.\n* Prototypers - factories that clone exsting classes or objects.\n\n#### Managers\n\n<p align=\"center\">\n<img src=\"https://media.giphy.com/media/NsBAHgohHByp2/giphy.gif\" alt=\"Don't just stand there! Do something!\" style=\"width:300px;\"/>\n</p>\n\nFor more complex construction, you can use subclasses of `Manager`, which is an iterable constructor. Every `Manager` subclass may construct items in three ways:\n\n1. Calling its `manage` method.\n2. Calling its `create` method (which just calls the `manage` method, but this allows a `Manager` subclass instance to be used anywhere a `Factory` could be used while still being distinguishable from an ordinary `Factory`).\n3. Iterating it directly.\n\n#### Producers\n\n<p align=\"center\">\n<img src=\"https://media4.giphy.com/media/l0HlHSB8v5yRtBlHW/giphy.gif\" alt=\"Willy Wonka completes a forward roll and pops up\" style=\"width:350px;\"/>\n</p>\n\nAs another optional feature, `wonka` supports post-construction modification of built items through subclasses of `Producer`. This is particularly important for factories that use other resources (such as registries). `wonka` [separates concerns](https://dev.to/suspir0n/soc-separation-of-concerns-5ak7) so that the return value can be modified through a simple mixin system. This division of labor makes it incredibly easy to put together a `Factory` or `Manager` with a `Producer`.\n\n## Contributing\n\nContributors are always welcome. Feel free to grab an [issue](https://www.github.com/WithPrecedent/wonka/issues) to work on or make a suggested improvement. If you wish to contribute, please read the [Contribution Guide](https://www.github.com/WithPrecedent/wonka/contributing.md) and [Code of Conduct](https://www.github.com/WithPrecedent/wonka/code_of_conduct.md).\n\n## Similar Projects\n\nIf `wonka` does not fit your needs, you might find one of these other packages helpful. None of them does the same things that `wonka` does (which is why I created this library), but they might fit your particular project needs better.\n\n<p align=\"center\">\n<img src=\"https://media.giphy.com/media/Bu8ADbj7NuRry/giphy.gif\" alt=\"Stop. Don't. Come back.\" style=\"width:300px;\"/>\n</p>\n\n* [dataclass_factory](https://github.com/reagento/dataclass-factory): factory for dataclass production from other common data types.\n* [factory_boy](https://github.com/FactoryBoy/factory_boy): tool for dynamically creating objects for unit testing in Python.\n* [Model Bakery](https://github.com/model-bakers/model_bakery): object factory for Django.\n* [Polyfactory](https://github.com/litestar-org/polyfactory): factory framework for mock data generation.\n\n## Acknowledgments\n\nI would like to thank the University of Kansas School of Law for tolerating and\nsupporting this law professor's coding efforts, an endeavor which is well\noutside the typical scholarly activities in the discipline.\n\nLastly, I want to extend a special thanks to the late, great Gene Wilder, whose\nwork inspired the name of this project and made my childhood better.\n\n<p align=\"center\">\n<img src=\"https://media.giphy.com/media/3o6ZtbOoOHu28ftYiI/giphy.gif\" alt=\"RIP, Gene Wilder, 1933-2016\" style=\"width:200px;\"/>\n</p>\n\n## License\n\nUse of this repository is authorized under the [Apache Software License 2.0](https://www.github.com/WithPrecedent/wonka/blog/main/LICENSE).\n\n[^1]: This project is not affiliated with Willy Wonka candy, either of the Willy Wonka films (especially the Johnny Depp one), or any other Willy Wonka product. It's just named \"wonka\" because all of the most obvious names for a Python package of factories and other constructors on [pypi.org](https://pypi.org) were taken and Willy Wonka's insane candy factory was the first relevant pop-culture touchstone I could think of.\n\n[^2]: For the sake of brevity, the documentation refers to all of `wonka`'s constructors as \"factories,\" even though many do not fit the definition of the classic [factory design pattern](https://realpython.com/factory-method-python/).\n\n[^3]: Chocolate waterfalls are, sadly, only virtually implemented in `wonka`.",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Flexible, accessible, extensible Python factories",
"version": "0.1.4",
"project_urls": {
"Changelog": "https://WithPrecedent.github.io/wonka/changelog",
"Documentation": "https://WithPrecedent.github.io/wonka",
"Issues": "https://github.com/WithPrecedent/wonka/issues",
"Repository": "https://github.com/WithPrecedent/wonka"
},
"split_keywords": [
"factory",
"construction",
"constructor",
"design",
"pattern"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97cd68c1f08e57c3d580afa0234d29074b9060612ae468ee14d9c03338822fc3",
"md5": "2b297f60c70e8fdc39529b9a573a85e5",
"sha256": "72ea19ccfc8654d582fe657a79cdced9983c9de3b91514fabc70e9ce468e078a"
},
"downloads": -1,
"filename": "wonka-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b297f60c70e8fdc39529b9a573a85e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22117,
"upload_time": "2024-04-10T06:53:12",
"upload_time_iso_8601": "2024-04-10T06:53:12.981666Z",
"url": "https://files.pythonhosted.org/packages/97/cd/68c1f08e57c3d580afa0234d29074b9060612ae468ee14d9c03338822fc3/wonka-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2cdce23f8d845503d4f419b053a058734a01d6e17902810669939fd9bb2ec395",
"md5": "8e80a859b8260638e46c426eb165deda",
"sha256": "33d9efb671125139c971d630847114ec6fb18813f43728fd0906e20ba90091b0"
},
"downloads": -1,
"filename": "wonka-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "8e80a859b8260638e46c426eb165deda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22506,
"upload_time": "2024-04-10T06:53:14",
"upload_time_iso_8601": "2024-04-10T06:53:14.183536Z",
"url": "https://files.pythonhosted.org/packages/2c/dc/e23f8d845503d4f419b053a058734a01d6e17902810669939fd9bb2ec395/wonka-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 06:53:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WithPrecedent",
"github_project": "wonka",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wonka"
}
JSON
