macropy: syntactic macros for Python

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 .

MacroPyis 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:

• Case Classes , easy Algebraic Data Types from Scala, and Enums ;
• Quick Lambdas from Scala and Groovy, and the Lazy and Interned utility macros;
• String Interpolation , a common feature in many programming languages;
• Tracing and Smart Asserts , and show_expanded , to help in the debugging effort;
• MacroPEG Parser Combinators , Parser Combinators inspired by Scala’s,

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

• Pattern Matching from the Functional Programming world
• Tail-call Optimization , preventing unnecessary stack overflows
• PINQ to SQLAlchemy , a shameless clone of LINQ to SQL from C#
• Pyxl Snippets , XML interpolation within your Python code
• JS Snippets , cross compiling snippets of Python into equivalent JavaScript

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

• Writing Your First Macro
• Making your Macros Hygienic
• Exporting your Expanded Code

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.

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.