https://github.com/withprecedent/wonka
Fleixble, accessible, extensible Python factories
https://github.com/withprecedent/wonka
Last synced: 4 months ago
JSON representation
Fleixble, accessible, extensible Python factories
- Host: GitHub
- URL: https://github.com/withprecedent/wonka
- Owner: WithPrecedent
- License: other
- Created: 2023-03-31T21:27:44.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-29T23:26:11.000Z (about 1 year ago)
- Last Synced: 2025-07-07T12:06:41.907Z (12 months ago)
- Language: Python
- Size: 1.31 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# wonka
| | |
| --- | --- |
| 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 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?
*“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 projects with dynamic, runtime implementation of different strategies. 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.
* **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
### Installation
To install `wonka`, use `pip`:
```sh
pip install wonka
```
### Usage
There are three categories of base classes in `wonka`: factories, managers, and producers.
#### Factories
All `wonka` factory classes have a `create` class method which is used to construct new items. The only required argument for `create` is `item`, which contains the construction data.
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
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
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.
* [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.
## 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`.