Introduction — cygenja 0.5.1 documentation

# Introduction

cygenja is a small Python2 library to generate typed source files from Jinja2 source templates. We use it extensively to generate our Cython projects. See Limitations to see if this tool is for you.

## What cygenja can do

From a bunch of templated (source) files, cygenja can generate several (source) files. The translation part is given to the powerful Jinja2 template engine. cygenja is a layer above this template engine and is in charge of dispatching translation rules to the right subdirectories and apply them to the right bunch of files. A file is only generated if it is older than the template file used to produce it, i.e. a change in a template file triggers a regeneration of the corresponding files [1].

## How cygenja works

Within a root directory, you provide some translation rules: each rule is attached to a subdirectory and a file pattern. You can define several rules for one subdirectory. These rules (called actions in cygenja) are user defined callbacks. Once all rules are registered, the cygenja engine is given a directory pattern and a file pattern: only the matching rules are triggered. See Usage or look at the Examples for more.

## Limitations

Here is a small list of limitations [2]. It is of course not exhaustive but it can already give you a hint if this tool is for you or not.

### cygenja only parses subdirectories

cygenja can only parse subdirectories from a root directory. This means that it cannot generate files located at the root directory level (or outside the root directory).

### cygenja generates files in place

Files can only be generated in the same subdirectories as their corresponding templates.

### Templates and generated files must have different extensions

Templates are identified by specific extensions. The corresponding generated files will be given specific corresponding extensions too. This extension correspondance is defined by the user but both extensions must be different. For instance, *.cpd templated files are transformed into *.pxd files. Both extensions, .cpd and .pxd are be different.

### File patterns: only fnmatch patterns

Translation rules can only be applied to files corresponding to fnmatch patterns. While this covers most cases, it might be a limitation for some.

We also use the same kind of file patterns to trigger the translation.

### Directory patterns: only glob patterns

To select the subdirectory(ies) within which the rules will be applied by cygenja‘s engine, only glob patterns can be used.

### Contradictory actions are not filtered nor monitored

Nothing prevents you from registering conflicting actions. In this case, only the first registered action is guaranteed to be triggered.

## License

cygenja is distributed under the GPLv3.

Footnotes

[1] | Of course, you can force a file generation.

[2] | Most limitations described here can easily be overcome.