flython 0.2.0

Static functional purity analysis for Python.

Flython

---

Flython is still in an unstable development phase. Many features do not work perfectly (if at all), and interfaces are still being tweaked and played with. Bug reports, questions, feedback, fixes, and other contributions on GitHub are greatly appreciated – just open an issue or pull request!

---

About

Python is an incredibly dynamic language. While this is one of its greatest strengths, it also tends to create difficulties for engineers who wish to program in a strictly functional paradigm. Flython provides tools that statically analyze compiled CPython bytecode for near-perfect protection against statefulness, side-effects, mutation, and other sources of functional breakdown.

Flython's design is inspired by (and modeled after) mypy. If you've ever used similar static analysis tools, integrating Flython into your workflow will feel familiar and natural.

Examples

The easiest way to install Flython is with pip:

$ pip install flython

When your code is functionally pure, Flython stays invisible:

$ flython pure.py

When it's not, Flython warns you. Consider the following module, impure.py:

def modify_object(target):
    """Mutate target."""

    target.foo = "bar"
    del target.baz


def modify_object_sneaky(target):
    """Mutate target in a hard-to-catch way."""

    setter, deleter = setattr, delattr

    setter(target, "foo", "bar")
    deleter(target, "baz")


# Create some mutable objects:
my_list = [*range(3)]
my_set = {i for i in range(3, 6)}
my_dict = dict((("six", 6), ("seven", 7), ("eight", 8)))

# Mutate those objects:
my_list[0] = "zero"
my_set -= my_set
del my_dict["eight"]

When we run Flython, it catches quite a bit of the impurity:

$ flython impure.py
Attempt to store value 'bar' to variable attribute target.foo. (impure.py, line 4)
Attempt to delete variable attribute target.baz. (impure.py, line 5)
Attempt to store value 'zero' to contained item my_list[0]. (impure.py, line 23)
Attempt to modify variable. Use normal assignment (my_set = my_set - my_set) instead of augmented assignment (my_set -= my_set). (impure.py, line 24)
Attempt to delete contained item my_dict['eight']. (impure.py, line 25)

Using --strict, though, catches all of its issues:

$ flython impure.py --strict
Attempt to store value 'bar' to variable attribute target.foo. (impure.py, line 4)
Attempt to delete variable attribute target.baz. (impure.py, line 5)
Attempt to load dynamic function 'setattr'. (impure.py, line 11)
Attempt to load dynamic function 'delattr'. (impure.py, line 11)
Attempt to use mutable built-in type 'list'. (impure.py, line 18)
Attempt to use mutable built-in type 'set'. (impure.py, line 19)
Attempt to use mutable built-in type 'dict'. (impure.py, line 20)
Attempt to store value 'zero' to contained item my_list[0]. (impure.py, line 23)
Attempt to modify variable. Use normal assignment (my_set = my_set - my_set) instead of augmented assignment (my_set -= my_set). (impure.py, line 24)
Attempt to delete contained item my_dict['eight']. (impure.py, line 25)

Features

Command-Line Tool

$ flython MODULE [ MODULE ... ]

Execute the flython package directly with a list of modules to statically analyze them. It accepts some basic options:

$ flython --help

Static functional purity analysis for Python.

Options:

  --no-dynamic    Don't allow "breakpoint" (Python 3.7+), "delattr", "eval", "exec", "globals", "locals", or "setattr".
  --no-io         Don't allow "input", "open", or "print".
  --no-mutables   Don't allow mutable built-in types.
  --no-raise      Don't allow "raise" statements.
  --skip-imports  Don't check imports.
  --strict        Same as --no-dynamic --no-io --no-mutables --no-raise.

Flython Comments

... # flython: ignore

Indicate that Flython should silence any errors occurring on this line.

Note that this does not silence followed imports. Users should skip imports with # flython: skip if they do not wish for them to be analyzed.

... # flython: skip

Indicate that Flython shouldn't check any new code objects defined on this line. This includes imports, class definitions, function definitions, generator expressions, or list/dict/set comprehensions.

Programmatic Interface

flython.main(*modules: str, **options: bool) -> Generator[Union[OSError, SyntaxError], None, None]

The main function takes any number of string filepaths and yields Exception objects identical to those reported by the command-line interface.

Requirements

Flython officially supports CPython 3.4+ on Linux. It also attempts to maintain compatibility with PyPy 3.5 and all development versions of CPython 3.5+ (including unstable branches). It has no external dependencies.

Python 3.6+ is recommended for Flython development work, along with the latest versions of the packages in requirements.txt.

Contributing

Contributions are welcome! See CONTRIBUTING.md for more info.

The MIT License

Copyright © 2018 Gary Brandt Bucher, II.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.