Package: variants
variantsis a library that provides syntactic sugar for creating alternate forms of functions and other callables, in the same way that alternate constructors are class methods that provide alternate forms of the constructor function.To create a function with variants, simply decorate the primary form with@variants.primary, which then adds the.variantdecorator to the original function, which can be used to register new variants. Here is a simple example of a function that prints text, with variants that specify the source of the text to print:importvariants@variants.primarydefprint_text(txt):print(txt)@print_text.variant('from_file')defprint_text(fobj):print_text(fobj.read())@print_text.variant('from_filepath')defprint_text(fpath):withopen(fpath,'r')asf:print_text.from_file(f)@print_text.variant('from_url')defprint_text(url):importrequestsr=requests.get(url)print_text(r.text)print_textand its variants can be used as such:print_text('Hello, world!')# Hello, world!# Create a text filewithopen('hello_world.txt','w')asf:f.write('Hello, world (from file)')# Print from an open file objectwithopen('hello_world.txt','r')asf:print_text.from_file(f)# Hello, world (from file)# Print from the path to a file objectprint_text.from_filepath('hello_world.txt')# Hello, world (from file)# Print from a URLhw_url='https://ganssle.io/files/hello_world.txt'print_text.from_url(hw_url)# Hello, world! (from url)Differences from singledispatchWhilevariantsandsingledispatchare both intended to provide alternative implementations
to a primary function, the overall aims are slightly different.singledispatchtransparently
dispatches to variant functions based on thetypeof the argument, whereasvariantsprovidesexplicitalternative forms of the function. Note that in the above example, bothprint_text.from_filepathandprint_text.from_urltake a string, one representing a file
path and one representing a URL.Additionally, thevariantsis compatible withsingledispatch, so you can have the best of
both worlds; an example that uses both:@variants.primary@singledispatchdefadd(x,y):returnx+y@add.variant('from_list')@add.register(list)defadd(x,y):returnx+[y]Which then automatically dispatches between named variants based on type:>>>add(1,2)3>>>add([1],2)[1,2]But also exposes the explicit variant functions:>>>add.from_list([1],2)[1,2]>>>add.from_list()7@add.register(list)8defadd(x,y):---->9returnx+[y]TypeError:unsupportedoperandtype(s)for+:'int'and'list'It is important to note that thevariantsdecoratorsmust be the outer decorators.InstallationTo install variants, run this command in your terminal:$pipinstallvariantsRequirementsThis is a library for Python, with support for versions 2.7 and 3.4+.Version 0.2.0 (2018-05-03)FeaturesAdded thevariants.inspectmodule, which provides a public API for
inspecting variant function groups. It currently provides two functions:is_primaryandis_primary_method. (GH #29)Added python_requires to setup, indicating Python version support. (GH #34)BugfixesUpdated MANIFEST.in to include NEWS.rst (GH #34)Improved DocumentationUpdated permanent redirect links in documentation. (GH #28)Flattened TOC entry for changelog in documentation. (GH #32)Added section for API documentation, including documentation for the inspect
submodule. (GH #33)