Package: autosig
Go straight to thedocumentation. Install withpip install autosig. Python 3 only.MotivationWhen I look at a great API I always observe a great level of consistency: similarly named and ordered arguments at a syntactic level; similar defaults, range of allowable values etc. on the semantic side. When looking at the code, one doesn’t see these regularities represented very explicitly.Imagine we are starting to develop a library with three entry points,map,reduceandfilter:from collections import Iterable


def map(function, iterable):
    assert callable(function)
    assert isinstance(iterable, Iterable)
    return (function(x) for x in iterable)


def reduce(function, iterable):
    total = next(iterable)
    for x in iterable:
        total = function(total, x)
    return total


def filter(iterable, fun):
    if not isinstance(iterable, Iterable):
        iterable = [iterable]
    if isinstance(fun, set):
        fun = lambda x: x in fun
    return (x for x in iterable if fun(x))But this is hardly well crafted. The order and naming of arguments isn’t consistent. One function checks its argument right away. The next doesn’t. The third attempts certain conversions to try and work with arguments that are not iterables or functions. There are reasons to build strict or tolerant APIs, but it’s unlikely that mixing the two within the same API is a good idea, unless it’s done deliberately (for instance offering a strict and tolerant version of every function). It wouldn’t be difficult to fix these problems in this small API but we would end up with duplicated logic that we need to keep aligned for the foreseeable future. Let’s do it instead theautosigway:from autosig import param, Signature, autosig, check
from collections import Iterable


def to_callable(x):
    return (lambda y: y in x) if isinstance(x, set) else x


def to_iterable(x):
    return x if isinstance(x, Iterable) else [x]


API_signature = Signature(
    function=param(converter=to_callable, validator=callable),
    iterable=param(converter=to_iterable, validator=Iterable))


@autosig(API_signature)
def map(function, iterable):
    return (function(x) for x in iterable)


@autosig(API_signature)
def reduce(function, iterable):
    total = next(iterable)
    for x in iterable:
        total = function(total, x)
    return total


@autosig(API_signature)
def filter(function, iterable):
    return (x for x in iterable if function(x))Let’s go through it step by step. First we defined 2 simple conversion
functions. This is a good first step independent ofautosig. Next we create
a signature object, with two parameters. These are intialized with objects that
define the checking and conversion that need to be performed on those
parameters, independent of which function is going to use that signature.
A type works as a validator, as does any callable that returnsTruewhen a value is valid, returnsFalseor raises an exception otherwise. Finally, we repeat
the definition of our three API function, attaching the signature just defined
with a decorator and then skipping all the checking and conversion logic and
going straight to the meat of the function!At the cost of a little code we have gained a lot:Explicit definition of the desired API signature, in a single place — DRY principle;association of that signature with API functions, checked at load time — no room for error;uniform application of conversion and validation logic without repeating it;autosigis the pro tool for the API designer! If you want to take a look at a real package that usesautosig, check outaltair_recipes.FeaturesDefine reusable parameters with defaults, conversion and validation logic, documentation, preferred position in the signature and whether keyword-only.Define reusable return values with conversion and validation logic and documentation.Define reusable signatures as ordered maps from names to parameters with optional return value definition.Combine signatures to create complex ones on top of simple ones.Decorate functions and methods with their signatures. Enforced at load time. Conversion and validation logic executed at call time.Not hot about signatures? You can just use parameters as in:@autosig
def reduce(function = param(...), iterable=param(...)):for more free-form APIs.Open source (BSD license)Extensive property-based testing, excellent coverageCreditsThis package is heavily based onattrs. While that may change in the future, for now it must be said this is a thin layer over that, with a bit of reflection sprinkled over. It is, I suppose, a quite original direction to takeattrsinto.