PyCC Documentation¶

Transforming Code¶

PyCC is quite a young project. As a result, you may be hesitant to simply trust the output and skip straight to the compile step. Instead, you may want to see an example of what the optimizer has produced so that you can verify that it is, indeed, both valid Python and acceptable code. This is what the pycc-transform command is for.

Usage for this command is simple:

pycc-transform <python_file.py> [–optimizer_option]

All optimization is disabled by default. Use the appropriate flags to enable the optimizations you want to apply. At the time of writing the full options listing for pycc-transform was:

usage: pycc-transform [-h] [–constants] source

PyCC Transformer

positional arguments:

source Path to the python source code. May be file or directory.

optional arguments:

-h, --help	show this help message and exit
--constants	Replace constant expressions with inline literals.

Running this command will output the optimized source code to the terminal.

If you run pycc-transform and it produces invalid Python code or it changes the code such that it no longer does what it is supposed to do then please post the original source and optimization options enabled as a bug on the project GitHub page.

Compiling Code¶

Once you are comfortable with the way PyCC alters your code you can start running the pycc-compile command:

usage: pycc-compile [-h] [–constants] [–destination DESTINATION] source

PyCC Compiler

positional arguments:

source Path to the python source code. May be file or

directory.

optional arguments:

-h, --help	show this help message and exit
--constants	Replace constant expressions with inline literals.
--destination DESTINATION
	Path to place compiled binaries in.

The compiler can be run on either individual Python modules or it can be pointed at a Python package. By default the script will drop the ‘.pyc’ files right next to the source files just like the normal Python compiler. Alternatively you may use the ‘destination’ option to direct the ‘.pyc’ files to another directory.

The Python compiler will overwrite existing ‘.pyc’ files every time a source file is updated. The ‘destination’ option is useful if you want to create a compiled version of a module or package that doesn’t get overwritten every time you make a change to the source.

Constant Inlining¶

Flag: –constants

As demonstrated on the main page, this option replaces the use of read-only, constant values with their literal values. This affects variables that are assigned only once within the given scope and are assigned to a number, string, or name value. Name values are any other symbols including True, False, and None.

This transformation does not apply to constants that are assigned to complex types such as lists, tuples, function calls, or generators.

Contributing To The Project¶

Adding a new optimizer to the core project is (hopefully) a straightforward process. You are, of course, welcome to use any kind of workflow you like. For this walkthrough I will be using my own as an example.

function optimize(module, *args, **kwargs):

    pass

parser.add_argument(
    '--my_optimizer',
    help="Makes stuff go faster.",
    action='store_const',
    default=None,
    const="pycc_my_optimizer",
)

Developing Third Party Extensions¶

Writing third party extensions that plug into the PyCC commands requires you to provide two interfaces on the right entry points.

On the pycc.optimizers entry point you must expose a callable which accepts a module.Module object as the first parameter, any number of named parameters which correspond with relevant CLI args added by your module, *args, and`**kwargs`. The name of this entry point must be prefixed with pycc_.

On the pycc.cli.args entry point you must expose a callable which accepts an argument parser from argparse. Your function must use this parser to register an argument as follows:

parser.add_argument(
    '--my_optimizer',
    help="Makes stuff go faster.",
    action='store_const',
    default=None,
    const="pycc_my_optimizer",
)

The value of the const parameter should match exactly the name give to the pycc.optimizers entry point.

You may also register arguments needed to configure your optimizer. They will be passed into your pycc.optimizers entry point addition as keyword arguments.