#fluent interface

Fluent interfaces provide a set of chained methods to manipulate a value in an object. It can help turn complex operations involving many steps into a relatively straightforward set of operations while providing a lot of flexibility. Many libraries like jQuery, Mongo DB and so on use this. To demonstrate, here is a simple string manipulator:

function Formatter(message) { const self = this; self.value = message; self.lastAction = function() {}; const wrap = function(callback) { return function() { const argsAsArray = [].slice.call(arguments); callback.apply(self, argsAsArray); self.lastAction = callback.bind(callback, argsAsArray); return self; } } self.prefix = wrap(function(prefix) { self.value = prefix + self.value; }); self.suffix = wrap(function(suffix) { self.value += suffix; }); this.times = wrap(function(times) { // -1 since the action has already been done once for (let i = 0; i < times - 1; i += 1) { self.lastAction(); } }); }; const value = new Formatter('My exciting sentence') .suffix('!') .times(5) .prefix('[') .suffix(']') .value console.log(value); // [My exciting sentence!!!!!]

It is important to use a wrapper function, so that further functions do not accidentally lack self returns due to copy and pasting errors.

Fluent Interface is an implementation of API which improves readability.

Example

Poem('The Road Not Taken').indent(4).suffix('Robert Frost').

Fluent Interface is similar to method chaining. I was wondering how to implement this in Python. Returning self during method call seemed good idea .

class Poem(object): def __init__(self, content): self.content = content def indent(self, spaces=4): self.content = " " * spaces + self.content return self def suffix(self, content): self.content += " - {}".format(content) return self def __str__(self): return self.content >>>print Poem('Road Not Taken').indent(4).suffix('Rober Frost').content Road Not Taken - Rober Frost

Everything seems to be ok here.

Side effects

Above approach has side effect. We are mutating the same object during every method call. Consider the following code

>>>p = Poem('Road Not Taken') >>>q = p.indent(4) >>>r = p.indent(2) >>>print str(q) == str(r) True >>>print id(q), id(r) 4459640464 4459640464

Clearly this isn't expected. q and r is pointing to same instance. Ideally we should create a new instance during every method call and return the object.

New object

Decorator is a function which takes a function as argument and returns a function (most cases).

from functools import wraps def newobj(method): @wraps(method) # Well, newobj can be decorated with function, but we will cover the case # where it decorated with method def inner(self, *args, **kwargs): obj = self.__class__.__new__(self.__class__) obj.__dict__ = self.__dict__.copy() method(obj, *args, **kwargs) return obj return inner class NPoem(object): def __init__(self, content): self.content = content @newobj def indent(self, spaces=4): self.content = " " * spaces + self.content @newobj def suffix(self, content): self.content += " - {}".format(content) def __str__(self): return self.content >>>p = NPoem("foo") >>>q = p.indent(4) >>>r = p.indent(2) >>>print str(q) == str(r) False >>>print(q) foo >>>print(r) foo >>>print id(q), id(r) 4459642640 4459639248

In the above approach newobj decorator creates a new instance, copies all the atrributes, calls the method with arguments and returns new instance. Rather than using decorator private function can do the same.

Fluent Interface is used heavily in SQLAlchemy and Django. Django uses _clone method to create new QuerySet and SQLAlchemy uses decorator based approach to create new Query instance.

Thanks Mike Bayer and Daniel Roy Greenfeld helping me understand this.