Lenses are just one in a whole family of related objects called optics. Optics generalise the notion of accessing data.

The heirarchy of optics looks like this:

digraph {
        "Fold" -> "Getter";
        "Fold" -> "Traversal";
        "Getter" -> "Lens";
        "Lens" -> "Isomorphism";
        "Prism" -> "Isomorphism";
        "Review" -> "Prism";
        "Setter" -> "Traversal";
        "Traversal" -> "Lens";
        "Traversal" -> "Prism";

An arrow pointing from A to B here means that all B are also A. For example, all Lenses are also Getters, and all Getters are also Folds.

When we compose two optics together, the result is the most-recent common ancestor of the two. For example, if we compose a Getter and a Traversal then the optic we get back would be a Fold because Getters and Traversals are both kinds of Fold. We cannot compose two optics that do not share a common ancestor; e.g. we cannot compose a Fold with a Setter.

You can find out the kind of a lens using the kind method:

>>> from lenses import lens
>>> my_lens = lens[0]
>>> my_lens.kind()
>>> my_prism = lens.Instance(str)
>>> my_prism.kind()
>>> my_traversal = my_lens & my_prism
>>> my_traversal.kind()


All the optics that we have seen so far have been lenses, so they always focused a single object inside a state. But it is possible for an optic to have more than one focus. One such optic is the traversal. A simple traversal can be made with the Each method. lens.Each() will focus all of the items in a data-structure analogous to iterating over it using python’s iter and next. It supports most of the built-in iterables out of the box, but if we want to use it on our own objects then we will need to add a hook explicitly.

One issue with multi-focus optics is that the get method only ever returns a single focus. It will return the first item focused by the optic. If we want to get all the items focused by that optic then we can use the collect method which will return those objects in a list:

>>> data = [0, 1, 2, 3]
>>> each = lens.Each()
>>> each.get()(data)
>>> each.collect()(data)
[0, 1, 2, 3]

Setting works with a traversal, though all foci will be set to the same object.

>>> each.set(4)(data)
[4, 4, 4, 4]

Modifying is the most useful operation we can perform. The modification will be applied to all the foci independently. All the foci must be of the same type (or at least be of a type that supports the modification that we want to make).

>>> each.modify(lambda a: a + 10)(data)
[10, 11, 12, 13]
>>> each.modify(str)([0, 1.0, 2, 3])
['0', '1.0', '2', '3']

You can of course use the same shortcut for operators that single-focus lenses allow:

>>> (each + 10)(data)
[10, 11, 12, 13]

Traversals can be composed with normal lenses. The result is a traversal with the lens applied to each of its original foci:

>>> data = [[0, 1], [2, 3]]
>>> each_then_zero = lens.Each()[0]
>>> each_then_zero.collect()(data)
[0, 2]
>>> (each_then_zero + 10)(data)
[[10, 1], [12, 3]]

Traversals can also be composed with other traversals just fine. They will simply increase the number of foci targeted. Note that collect returns a flat list of foci; none of the structure of the state is preserved.

>>> each_twice = lens.Each().Each()
>>> each_twice.collect()(data)
[0, 1, 2, 3]
>>> (each_twice + 10)(data)
[[10, 11], [12, 13]]

The Values method returns a traversal that focuses all of the values in a dictionary. If we return to our GameState example from earlier, we can use Values to move every enemy in the same level 1 pixel over to the right in one line of code:

>>> from collections import namedtuple
>>> GameState = namedtuple('GameState',
...     'current_world current_level worlds')
>>> World = namedtuple('World', 'theme levels')
>>> Level = namedtuple('Level', 'map enemies')
>>> Enemy = namedtuple('Enemy', 'x y')
>>> data = GameState(1, 2, {
...     1: World('grassland', {}),
...     2: World('desert', {
...         1: Level({}, {
...             'goomba1': Enemy(100, 45),
...             'goomba2': Enemy(130, 45),
...             'goomba3': Enemy(160, 45),
...         }),
...     }),
... })
>>> level_enemies_right = (lens.worlds[2]
...                            .levels[1]
...                            .enemies.Values().x + 1)
>>> new_data = level_enemies_right(data)

Or we could do the same thing to every enemy in the entire game (assuming that there were other enemies on other levels in the GameState):

>>> all_enemies_right = (lens.worlds.Values()
...                          .levels.Values()
...                          .enemies.Values().x + 1)
>>> new_data = all_enemies_right(data)


A Getter is an optic that knows how to retrieve a single focus from a state. You can think of a Getter as a Lens that does not have a setter function. Because it does not have a setter function, we cannot use a Getter to set values. You also cannot use modify, call, or call_mut because these all make use of the setting machinery. The only method we can meaningly perform on a Getter is get. We can call collect, but it will always give us a list containing a single focus.

The simplest way to make a Getter is with the F method. This method takes a function and returns a Getter that just calls that function on the state in order and whatever that function returns is the focus.

>>> data = 1
>>> def get_negative(state):
...     return -state
>>> neg_getter = lens.F(get_negative)
>>> neg_getter.get()(data)

If we try to call set or any other invalid method on a Getter then we will get an exception:

>>> neg_getter.set(2)(data)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: Must be an instance of Setter to .set()

You might notice that lens.F(some_function).get() is exactly equivalent to using some_function by itself. For this reason Getters on their own are not particularly useful. The utility of Getters comes when we compose them with other optics.

>>> data = [1, 2, 3]
>>> each_neg = lens.Each().F(get_negative)
>>> each_neg.collect()(data)
[-1, -2, -3]

Getters allow you to inject arbitrary behaviour into the middle of an optic at the cost of not being able to set anything:

>>> data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
>>> lens.Each().F(reversed).Each().collect()(data)
[3, 2, 1, 6, 5, 4, 9, 8, 7]


A Fold is to a Getter what a Traversal is to a Lens. That is, a Fold is a Getter that can get multiple foci. Just like Getters, you cannot set anything with a Fold. Just like Traversals, when using a Fold, you will want to prefer the collect method over get.

A Fold can be constructed from any function that returns an iterator using the Fold method. Generator functions are particularly useful for making Folds.

>>> def ends(state):
...     yield state[0]
...     yield state[-1]
>>> data = [1, 2, 3]
>>> lens.Fold(ends).collect()(data)
[1, 3]

A useful Fold is Iter. This Fold just iterates over the state directly. It’s very similar to the Each Traversal, but Each needs explicit support for custom types precisely because it needs to know how to set new values on objects of that type. Iter is a Fold, so doesn’t need to set anything, and so can just use python’s built-in iterator protocol. lens.Iter() is equivalent to lens.Fold(iter)

Just as with Getters, Folds don’t do much on their own; you will want to compose them:

>>> data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
>>> lens.Iter().Fold(ends).F(get_negative).collect()(data)
[-1, -3, -4, -6, -7, -9]


If a Getter is like a Lens that lacks the ability to set, then a Setter is like a Lens that lacks the ability to get. You cannot call get on a setter, though you can use set, modify, call, and call_mut.

The only setter available is the ForkedSetter which you can create with the Fork method. This method allows you to create a setter that can set at two different places at once. You pass it some optics and the ForkedSetter will use the set functionality from all of those optics at once:

>>> set_inner_ends = lens.Each().Fork(lens[0], lens[-1])
>>> set_inner_ends.set(0)(data)
[[0, 2, 0], [0, 5, 0], [0, 8, 0]]
>>> (set_inner_ends + 10)(data)
[[11, 2, 13], [14, 5, 16], [17, 8, 19]]


An Isomorphism is an optic that can be flipped around; it is reversable.

An ordinary Lens can be thought of as a wrapper around a pair of functions:

def getter(state) -> focus:
def setter(old_state, focus) -> new_state:

Notice the asymmetry here; the setter function requires access to the previous state in order to construct a new state. With an Isomorphism the setter function no longer takes this argument; it can construct a new state by looking only at the focus:

def getter(state) -> focus:
def setter(focus) -> state:

These two functions are inverses of one another; converting back and forth between a state and a focus without any loss of information. A good example of an isomorphism is the equivalency between a unicode string and a byte string; if you know the encoding (and the encoding is capable enough, and the bytestring is valid) you can freely convert between the two. This isomorphism can be constructed using the Decode method:

>>> utf8_decoder = lens.Decode('utf8')
>>> utf8_decoder.get()(b'Hello, \xe4\xb8\x96\xe7\x95\x8c')
'Hello, 世界'

You can use set with an iso, but it will completely ignore the old state that you pass in:

>>> utf8_decoder.set('Hello, 世界')(b'ignored')
b'Hello, \xe4\xb8\x96\xe7\x95\x8c'

The value of an isomorphism is that you can flip them; you can turn the old getter into a setter and the old setter into a getter:

>>> utf8_encoder = utf8_decoder.flip()
>>> utf8_encoder.get()('Hello, 世界')
b'Hello, \xe4\xb8\x96\xe7\x95\x8c'
>>> utf8_encoder.set(b'Hello, \xe4\xb8\x96\xe7\x95\x8c')('ignored')
'Hello, 世界'

The flipped version of an isomorphism is still an isomorphism.

If you have two functions that are inverses of one another then you can create an isomorphism using the Iso method.

>>> state = 1, 2, 3
>>> list_converter = lens.Iso(list, tuple)
>>> list_converter.get()(state)
[1, 2, 3]
>>> (list_converter + [4])(state)
(1, 2, 3, 4)


A Prism is an like an isomorphism with the extra benefit that it can choose whether or not it wants to have a focus. That is; a prism takes a state and only optionally returns a focus.

Prisms are often used in other languages to unwrap sum-types, but since python does not have native sum-types their use is more limited. Because there are no good examples of sum-types in the python standard library we will have to simulate them.

On your birthday you can recieve two kinds of things; Presents and Cards. A present is a wrapper around some other type that represents the actual gift, while a card is just a card.

>>> class Card:
...     def __repr__(self):
...         return 'Card()'
>>> class Present:
...     def __init__(self, contents):
...         self.contents = contents
...     def __repr__(self):
...         return 'Present({!r})'.format(self.contents)

Say we have a list of all the things we got on our birthday:

>>> state = [Present('doll'), Card(), Present('train set')]

Because we are ungrateful children we want to be able to unwrap the presents in the list while leaving the cards untouched. A prism is exactly the sort of optic we need to write in this situation. We can create a prism using the Prism method. It takes two functions, unwrap and wrap, that will do the job of selecting and rebuilding the presents for us. The wrap function is easy because that is just the Present constructor that we already have. We can write an unwrap like this:

>>> def unwrap_present(state):
...     if isinstance(state, Present):
...         return state.contents

This function checks if we have a present, unwraps it if we do, and implicitly returns None if we don’t. Now we can construct our prism. We need to tell the prism that our function signals the lack of a focus by returning a none value, so we set the ignore_none keyword argument.

>>> Present_prism = lens.Prism(unwrap_present, Present, ignore_none=True)
>>> each_present = lens.Each() & Present_prism

Now we are ready to get at our presents:

>>> each_present.collect()(state)
['doll', 'train set']

And break them:

>>> ('broken ' + each_present)(state)
[Present('broken doll'), Card(), Present('broken train set')]

There are a couple of useful prisms available. Instance is a prism that only focuses something when it is of a particular type, and Filter allows you to supply an arbitrary predicate function to select the focus. Technically, Instance and Filter are something called an affine traversal and not true prisms, because they don’t actually do any wrapping and unwrapping; their wrap functions are both no-ops. But they act enough like prisms that the lenses library uses them as though they were.


A Review is to a Prism as a Setter is to a Traversal.

When we first looked at isomorphisms we saw that they have a special kind of setter that only takes one argument. Technically that function should not be called a “setter function” because it doesn’t know about the old state and so it can’t really set anything. This “setter that looks like a backwards getter” is actually called a “review function”. A Review is any optic that contains a review function, but doesn’t necessarily have a getter.

There are no supported ways to create Reviews using the lenses library. But since all prisms (and isomorphisms) are also reviews, it’s important to know what they can do. Reviews have two important features.

The first is that they are flippable. You can flip a Review just like an isomorphism, but while isos flip in a way that is reversable, Reviews do not. What was previously the review function becomes a getter and there is no previous getter function to become the review. The flipped version of a Review has a getter function, but no review function (and no setter). When you flip a Review it becomes a Getter.

>>> Present_getter = Present_prism.flip()
>>> Present_getter.kind()
>>> Present_getter.get()('lump of coal')
Present('lump of coal')

The second feature is that you can use them to construct states, given only a focus. Like isomorphisms, they do not require access to a previous state in order to construct a new one. If you have a Review you can construct states with the construct method; just pass the focus that you want to use.

If we wanted to play the childrens game “pass the parcel” we would need a prize that has been wrapped up many times:

>>> (Present_prism & Present_prism & Present_prism).construct('sweets')

Obviously, making a review like this just to construct values is inefficient and less readable than constructing the value directly. The utility comes when you have many different reviews, prisms, and isos composed together and you use the resulting optic to do many different tasks, not just constructing.