Welcome to MacroPy3’s documentation!

MacroPy3 is a port of the original MacroPy to Python 3. If you look for the Python 2 version see the python2 branch.

MacroPy is an implementation of Syntactic Macros in the Python Programming Language. MacroPy provides a mechanism for user-defined functions (macros) to perform transformations on the abstract syntax tree (AST) of a Python program at import time. This is an easy way to enhance the semantics of a Python program in ways which are otherwise impossible, for example providing an extremely concise way of declaring classes:

>>> import macropy.console
0=[]=====> MacroPy Enabled <=====[]=0
>>> from macropy.case_classes import macros, case

>>> @case
class Point(x, y): pass

>>> p = Point(1, 2)
>>> print(p.x)
1
>>> print(p)
Point(1, 2)

Try it out in the REPL, it should just work! You can also see the docs/examples/using_macros folder for a minimal example of using MacroPy’s existing macros.

MacroPy has been used to implement features such as:

As well as a number of more experimental macros such as:

Browse the high-level overview, or look at the Tutorials will go into greater detail and walk you through

Or just skip ahead to the Discussion and MacroPy: Bringing Macros to Python. We’re open to contributions, so send us your ideas/questions/issues/pull-requests and we’ll do our best to accommodate you! You can ask questions on the Google Group and on the Gitter channel or file bugs on thee issues page. See the changelist to see what’s changed recently.

Requirements

MacroPy3 is tested to run on CPython 3.4 or newer and PyPy 3.5. I has no current support for Jython. MacroPy3 is also available on PyPI.

Installation

Just execute a:

$ pip install macropy3

if you want to use macros that require external libraries in order to work, you can automatically install those dependencies by installing one of the pinq or pyxl extras like this:

$ pip install macropy3[pinq,pyxl]

then have a look at the docs at http://macropy3.readthedocs.io/en/latest/.

MacroPy: Bringing Macros to Python

Macros are always a contentious issue. On one hand, we have the LISP community, which seems to using macros for everything. On the other hand, most mainstream programmers shy away from them, believing them to be extremely powerful and potentially confusing, not to mention extremely difficult to execute.

With MacroPy, we believe that we have a powerful, flexible tool that makes it trivially easy to write AST-transforming macros with any level of complexity. We have a compelling suite of use cases demonstrating the utility of such transforms.

Credits

MacroPy was initially created as a final project for the MIT class 6.945: Adventures in Advanced Symbolic Programming, taught by Gerald Jay Sussman and Pavel Panchekha. Inspiration was taken from project such as Scala Macros, Karnickel and Pyxl.

License

MIT

Indices and tables