What’s the point?

It’s entirely that the imperative form is easier to read, and that pyrsistent’s API is tedious for nested collections, at least compared to native Python syntax.

Also, I’m working on a language that uses this technique more extensively, so this was an opportunity to turn a prototype into something more generally useful.

Installing

Installation should just be:

# Install via pip, preferred.
pip3 install pyrsistent-mutable

# Install traditionally.
python3 setup.py install

Usage

Beyond the example shown above, the main things to keep in mind when using this module:

• You function still needs to return values.

• A “copy” can be made by simple assignment.

• Lists, dicts and sets literals and comprehensions are transformed.

• Tuples are not transformed, nor are generators.

• Method calls are only transformed if they are standalone expressions.

• Rewritten operations should fall back to normal behavior for non-pyrsistent values.

• The decorated function can’t allow nonlocal names.

• global may not work.

Don’t forget to return

This only munges assignments and expression statements.

Read the __source__

The transformed code is written into your function under __source__ which may be helpful in debugging.

Known limits

Most of these are because I’ve only done very preliminary work to map imperative operations to pyrsistent values.

• Assignment of slices uses the evolver framework, which doesn’t handle complex slices.

• Deletion of slices similarly doesn’t work.

• Augmented assignment generally requires a pyrsistent value on the rhs.

  • This is mitigated now that the module translates literals.

• It is not tested on asynchronous functions or generators. It shouldn’t care about them, though.

• It’s all or nothing.

• The top level function can’t have nonlocal names. Embedded functions can, though.

Debugging

By default, the decorator will write the transformed source to your function as __source__. I just pulled that name out my hat. You can call the decorator with write_source=False to disable this.