Skip to main content

Library that enables the creation of alternate constructor-likevariant forms for arbitrary functions.

Project description

https://img.shields.io/pypi/v/variants.svg https://img.shields.io/travis/python-variants/variants.svg Documentation Status

variants is 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 .variant decorator 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:

import variants

@variants.primary
def print_text(txt):
    print(txt)

@print_text.variant('from_file')
def print_text(fobj):
    print_text(fobj.read())

@print_text.variant('from_filepath')
def print_text(fpath):
    with open(fpath, 'r') as f:
        print_text.from_file(f)

@print_text.variant('from_url')
def print_text(url):
    import requests
    r = requests.get(url)
    print_text(r.text)

print_text and its variants can be used as such:

print_text('Hello, world!')                 # Hello, world!

# Create a text file
with open('hello_world.txt', 'w') as f:
    f.write('Hello, world (from file)')

# Print from an open file object
with open('hello_world.txt', 'r') as f:
    print_text.from_file(f)                 # Hello, world (from file)

# Print from the path to a file object
print_text.from_filepath('hello_world.txt') # Hello, world (from file)

# Print from a URL
hw_url = 'https://ganssle.io/files/hello_world.txt'
print_text.from_url(hw_url)                 # Hello, world! (from url)

Differences from singledispatch

While variants and singledispatch are both intended to provide alternative implementations to a primary function, the overall aims are slightly different. singledispatch transparently dispatches to variant functions based on the type of the argument, whereas variants provides explicit alternative forms of the function. Note that in the above example, both print_text.from_filepath and print_text.from_url take a string, one representing a file path and one representing a URL.

Additionally, the variants is compatible with singledispatch, so you can have the best of both worlds; an example that uses both:

@variants.primary
@singledispatch
def add(x, y):
    return x + y

@add.variant('from_list')
@add.register(list)
def add(x, y):
    return x + [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)
      8 def add(x, y):
----> 9     return x + [y]

TypeError: unsupported operand type(s) for +: 'int' and 'list'

It is important to note that the variants decorators must be the outer decorators.

Installation

To install variants, run this command in your terminal:

$ pip install variants

Requirements

This is a library for Python, with support for versions 2.7 and 3.4+.

Version 0.2.0 (2018-05-03)

Features

  • Added the variants.inspect module, which provides a public API for inspecting variant function groups. It currently provides two functions: is_primary and is_primary_method. (GH #29)

  • Added python_requires to setup, indicating Python version support. (GH #34)

Bugfixes

  • Updated MANIFEST.in to include NEWS.rst (GH #34)

Improved Documentation

  • Updated 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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

variants-0.2.0.tar.gz (19.7 kB view details)

Uploaded Source

Built Distribution

variants-0.2.0-py2.py3-none-any.whl (5.6 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file variants-0.2.0.tar.gz.

File metadata

  • Download URL: variants-0.2.0.tar.gz
  • Upload date:
  • Size: 19.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for variants-0.2.0.tar.gz
Algorithm Hash digest
SHA256 511f75b4cf7483c27e4d86d9accf2b5317267900c166d17636beeed118929b90
MD5 6b5967772affa7838782fc3c97469647
BLAKE2b-256 60de8fe198896ac7d4fb7dddb0b1a1d3ac8bb632a053ffede0d4bc469f2d905a

See more details on using hashes here.

File details

Details for the file variants-0.2.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for variants-0.2.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 c1fb0a35dd9d822d371860ba08f9bc3d544772c225e7fc34ae8591a941609a81
MD5 5c9a8b03aa592a9b9fbbbc0c1b133562
BLAKE2b-256 336a28e8d20e2e7406c2a93f43c1c74be972b18a29edd8554dfe5926ea9eb5c0

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page