setuptools-pyecore

Table of Contents

• Overview
• Installation
  • From Source Code
  • From PyPI
  • From GitHub Releases
• Usage
  • Integration
  • Configuration
  • Sample

Overview

A setuptools command for generating Python code from Ecore models.

This is an extension for setuptools integrating the pyecoregen code generator into the Python packaging process. It encapsulates pyecoregen and provides the user a setuptools command called pyecore to control the generation process.

In a basic setup the user doesn't have to configure the generation process at all because setuptools-pyecore discovers Ecore models located in the current working directory and triggers the code generation for each detected Ecore model. Also a meaningful output folder is chosen automatically.

Of course the user has to possibility to customize the generation process. The command line options of pyecoregen are also available through the pyecore setuptools command. The user has the choice to pass the options on the command line or configure the code generation in a dedicated section in the setup.cfg file.

Installation

setuptools-pyecore can be installed in various ways. To run it the following prerequisites have to be fulfilled:

• Python 3.4+
• setuptools

After installation, the used Python environment has a new setuptools command called pyecore.

From Source Code

> git clone https://github.com/pyecore/setuptools-pyecore.git
> cd setuptools-pyecore
> pip install .

From PyPI

> pip install setuptools-pyecore

From GitHub Releases

> pip install <setuptools-pyecore_wheel>

Usage

Integration

For a smooth user experience it's recommended to pass setuptools-pyecore using the setup_requires argument of setup function. Additionally the generated Python code depends on the pyecore library which should be added to install_requires argument:

setup(
    ...
    setup_requires=['setuptools-pyecore'],
    install_requires=['pyecore']
    ...
)

Before generating Python code from a given Ecore model setuptools will automatically check the Python environment and download setuptools-pyecore from PyPI if it's missing. During the installation of the project package pip will install pyecore into the Python environment.

Configuration

setuptools-pyecore provides two possibilities to configure the pyecore generator.

All options can be passed on the command line after the pyecore command:

> python setup.py pyecore --auto-register-package

It's also possible to pass several options to pyecoregen or execute multiple commands at once:

> python setup.py pyecore --auto-register-package --output "default=gen" bdist_wheel

See python setup.py pyecore --help for available command line options:

> python setup.py pyecore --help
...
Options for 'PyEcoreCommand' command:
  --ecore-models (-e)      specify Ecore models to generate code for
  --output (-o)            specify directories where output is generated
  --user-modules           dotted names of modules with user-provided mixins
                           to import from generated classes
  --auto-register-package  Generate package auto-registration for the PyEcore
                           'global_registry'
...

The pyecoregen documentation explains all command line options in detail.

Apart from passing options on the command line it's also possible to add a dedicated [pyecore] section to setup.cfg. The following example section contains all available options:

[pyecore]
# Specify Ecore models to generate code for; default: None
#ecore-models = <ecore-model> [<ecore-model> ...]
# Specify directories where output is generated; default: <ecore-model-dir>
output = default=gen
# Dotted names of modules with user-provided mixins to import from generated classes; default: None
#user-modules = [<ecore-model>=<user module>]
#               [<ecore-model>=<user module> ...]
# Generate package auto-registration for the PyEcore 'global_registry' (yes|no); default: no
auto-register-package = yes

A reference configuration is provided in the resources directory.

pyecoregen inherits the log level globally configured for setuptools. To set the verbosity to a certain log level pass the global options verbose or quiet straight before the pyecore command on the command line:

> python setup.py --verbose pyecore

Alternatively, you can add these options to the [global] section of your setup.cfg:

[global]
# Run verbosely (yes|no); default: yes
#verbose = yes
# Run quietly and turns verbosity off (yes|no); default: no
quiet = yes

Sample

Besides the setuptools-pyecore source code a sample project called library is provided in the samples directory. This sample consists of the Ecore model library and a setup script. During the execution of setuptools-pyecore a Python package will be generated into the library package directory representing the classes from the library Ecore model.

To generate code out of the Ecore model and build a library wheel package execute the following command:

> python setup.py pyecore bdist_wheel