Project Generator API Reference¶

An overview of commands for Project generator.

Info

This API is included in the ecu.test Interface Python Library ecutest-interface.

ProjectGenerator¶

class ProjectGenerator¶

Base class for user-defined project generators.

Derive your generator from this class and implement the generation lifecycle. During execution, ecu.test instantiates your class, calls PreGeneration(), iterates over GenerationIterator(), and finally calls PostGeneration().

Typical workflow:

Set mandatory class attributes ID and NAME.
Optionally declare serializable instance attributes in SERIALIZE.
Build one CycleData per generated project via CreateCycleData().
Add project steps to cycleData.projectInstance using cycleData.objectApi.
Yield each prepared cycleData from GenerationIterator().

Some fields and methods must be overridden (mandatory), others may be overridden (optional). Helper methods (without an override note) are intended to be called by your implementation and should not be overridden.

DESCRIPTION : str = ''¶: Short description of the project generator shown in the UI.

FORMAT_REV = 0¶

Format revision of persisted generator data.

Increase this only if your serialized data structure is intentionally incompatible with older revisions and you provide a migration strategy. Otherwise keep this value at 0.

ID : str = ''¶

Universally unique identifier of the project generator.

Use a UUID string and never change it after the generator is used in projects, because projects persist only this identifier.

Info

Setting this field is mandatory

NAME : str = ''¶: Display name of the project generator shown in the UI.

Info

Setting this field is mandatory

SERIALIZE : dict[str, tuple[str, str] | tuple[str, str, object]] = {}¶

Declaration of generator instance attributes that are persisted in project XML.

Add one dictionary item per instance attribute. Example:

SERIALIZE = {
    'foo': ('FOO-VAR', 'integer', 23),
    'bar': ('BAR', 'string'),
    'params': ('PARAMETERS', 'list'),
}

The declaration key must match the attribute name exactly (for example self.foo requires 'foo' as key). The value tuple must contain at least two elements:

``<variable name>: (<variable alias>, <type alias>, [default value])``

Syntax and meaning of the tuple’s elements are:

<variable alias> declares the name of the xml element that is used for the variable’s xml representation.
<type alias> keyword specifying the Python variable type:
- boolean: bool
- integer: int
- long: int
- float: float
- string: str
- unicode: str
- list: list
- dict: dict

Keys of serialized dictionaries must be strings. Values in lists and dictionaries (including nested structures) must be bool, int, float, str, list or dict. long and unicode are legacy compatibility aliases and should not be used in new code.

<default value> is an optional element. It specifies the variable’s default value. If the variable’s value equals its default value during export the variable is not exported at all. Conversely, the variable is assigned its default value during import if the XML data does not provide a value for the attribute.

api = None¶

Access to the internal ecu.test API.

This reference is assigned at runtime. Use it for settings or helper services from within the generator.

See also

Internal APIs

projectPath : str | None = None¶

Absolute path of the project file associated with the current run.

During direct execution this is the executed project file. During static generation this is the destination project file.

sourceProjectPath : str | None = None¶

Absolute path of the source project that contains this generator.

This attribute is only set when a source project context is available.

classmethod GetDescription()¶

Returns the description of the project generator. The description can be specified by setting the class variable DESCRIPTION.

Returns:: Description text of the project generator.
Return type:: str

classmethod GetFormatRev()¶

Returns the format revision of the project generator. The format revision can be specified by setting the class variable FORMAT_REV. This is an optional parameter.

Returns:: Format revision number, or None if not defined.
Return type:: int | None

classmethod GetId()¶

Returns the universally unique identifier of the project generator. The identifier should be specified by setting the class variable ID.

Returns:: Unique identifier of the project generator.
Return type:: str

classmethod GetName()¶

Returns the name of the project generator. The name should be specified by setting the class variable NAME.

Returns:: Display name of the project generator.
Return type:: str

Check()¶

Validate the generator configuration.

Returns:: A list of error messages or an empty list if everything is fine.
Return type:: list[str]

Info

Overriding this method is optional

CreateCycleData(name=None, template=None)¶

Create a CycleData object for one generated project.

In ecu.test, this helper returns a runtime-specific cycle object. When template is given, its project is opened as the starting point; otherwise, ecu.test creates an empty project. Populate cycleData.projectInstance through cycleData.objectApi before yielding it.

Parameters:

name : str | None¶: Optional display name for this cycle in the report.
template : str | None¶: Optional path to a template project used as the project base.

Returns:

Cycle object that contains Object API access and project data for one run.

Return type:

CycleData

DryGenerationEnabled()¶

Return whether dry generation mode is active.

In dry generation mode, yielded cycles are converted to static project calls instead of being executed immediately.

Returns:: True if dry generation mode is active, otherwise False.
Return type:: bool

abstractmethod GenerationIterator()¶

Generate projects cycle by cycle.

This method must be an iterator that yields CycleData instances. Create each cycle via CreateCycleData(), fill cycleData.projectInstance with project steps, then yield cycleData.

Example:

def GenerationIterator(self):
    cycleData = self.CreateCycleData('MyProject')
    packageCall = cycleData.objectApi.ProjectApi.ComponentApi.CreatePackageCall('hallo.pkg')
    cycleData.projectInstance.AppendComponent(packageCall)
    yield cycleData

During normal execution each yielded cycle is executed immediately. During static generation, each yielded cycle is exported to a separate project and inserted as a project call.

Info

Overriding this method is mandatory

GetDialog()¶

Return a configuration dialog for editing generator settings.

Use this dialog to edit instance attributes referenced by SERIALIZE.

Returns:: Configuration dialog instance, or None if no dialog is required.
Return type:: wx.Dialog | None

Info

Overriding this method is optional

GetParameterText()¶

Return a short one-line text representation of the current generator settings.

The returned text is displayed in the project properties column.

Returns:: parameter text
Return type:: str

Info

Overriding this method is optional

GetTargetItemCount()¶

Return the expected number of cycles for progress reporting.

This method can be called repeatedly while generation is running, so the value may be computed dynamically.

Returns:: Expected number of generated project cycles.
Return type:: int

PostGeneration()¶

Hook that runs after generation finished or failed.

This method is called even if an exception occurred in PreGeneration() or GenerationIterator(). It is not guaranteed to run when execution is aborted externally (for example manual abort or abort-on-error behavior).

Info

Overriding this method is optional

PreGeneration()¶

Hook that runs once before GenerationIterator() is consumed.

Use it for validation, setup, or preparing expensive resources.

Info

Overriding this method is optional

class CycleData¶

Container for one generated project cycle.

Create instances via ProjectGenerator.CreateCycleData() in your generator. Fill projectInstance with components and then yield the instance from ProjectGenerator.GenerationIterator().

Name¶

Return the display name of this cycle.

Returns:: Cycle display name.

objectApi : ObjectApi | None = None¶

Object API used to create project components, such as package calls or project calls.

ecu.test assigns this attribute to cycles created through ProjectGenerator.CreateCycleData(). It is not normally available on an interface CycleData instance constructed directly.

projectInstance : Project | None = None¶

Project instance to populate for this cycle.

ecu.test creates this instance empty or opens it from the template passed to ProjectGenerator.CreateCycleData(). Add or modify components before yielding the cycle.

GetName()¶

Return the display name of this cycle.

Returns:: Cycle display name.
Return type:: str

SetName(value)¶

Set the display name of this cycle.

Parameters:

value : str¶: Cycle display name.