wonka 0.1.2

Flexible, accessible, extensible Python factories

wonka

Version
Status
Documentation
Tools
Compatibility
Stats

---

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.

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 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

Installation

To install wonka, use pip:

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

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

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 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 to work on or make a suggested improvement. If you wish to contribute, please read the Contribution Guide and Code of Conduct.

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: factory for dataclass production from other common data types.
• factory_boy: tool for dynamically creating objects for unit testing in Python.
• Model Bakery: object factory for Django.
• 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.

[^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 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.

[^3]: Chocolate waterfalls are, sadly, only virtually implemented in wonka.