Package: wonka
wonkaVersionStatusDocumentationToolsCompatibilityStatsWhat is wonka?wonka[^1] is an extensible library for simple implementation of class and
object constructors in Python. Out-of-the-box,wonkahas implementations of
several common creational design patterns, including: registry factories,
prototypers, and composite builder workflows. It is also easy to extendwonkaby adding your own custom factories[^2] while taking advantage ofwonka's
convenient mixin classes and helper functions.This readme offers a basic outline of howwonkaworks. If you would prefer to jump right into the full documentation, gohere.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 WonkaFactories 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.wonkaaddresses those common shortcomings by offering convenient creation through a simple, adaptable system that has almost no learning curve[^3].wonkais:Intuitive: factories use a common interface with acreateclass 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:wonkais over-documented to make it accessible to beginnning coders and readily usable for developers at all levels.Getting startedInstallationTo installwonka, usepip:pipinstallwonkaUsageThere are three categories of base classes inwonka: factories, managers, and producers. Each is described in greater detail below.FactoriesAllwonkafactory classes have acreateclass method which is used to construct new items. The only required parameter forcreateisitem, which contains the data for building products.Out-of-the-box, this library offers three general subtypes of its baseFactoryclass. These are not subclasses, but rather describe the type of functionality in the includedFactorysubclasses.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.ManagersFor more complex construction, you can use subclasses ofManager, which is an iterable constructor. EveryManagersubclass may construct items in three ways:Calling itsmanagemethod.Calling itscreatemethod (which just calls themanagemethod, but this allows aManagersubclass instance to be used anywhere aFactorycould be used while still being distinguishable from an ordinaryFactory).Iterating it directly.ProducersAs another optional feature,wonkasupports post-construction modification of built items through subclasses ofProducer. This is particularly important for factories that use other resources (such as registries).wonkaseparates concernsso that the return value can be modified through a simple mixin system. This division of labor makes it incredibly easy to put together aFactoryorManagerwith aProducer.ContributingContributors are always welcome. Feel free to grab anissueto work on or make a suggested improvement. If you wish to contribute, please read theContribution GuideandCode of Conduct.Similar ProjectsIfwonkadoes not fit your needs, you might find one of these other packages helpful. None of them does the same things thatwonkadoes (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.AcknowledgmentsI 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.LicenseUse of this repository is authorized under theApache 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 onpypi.orgwere 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 ofwonka's constructors as "factories," even though many do not fit the definition of the classicfactory design pattern.[^3]: Chocolate waterfalls are, sadly, only virtually implemented inwonka.