capella2polarion.converters package

Objects for synchronization of capella objects to polarion workitems.

Submodules

capella2polarion.converters.converter_config module

Module providing capella2polarion config class.

class capella2polarion.converters.converter_config.CapellaTypeConfig(p_type: str | None = None, converters: str | list[str] | dict[str, dict[str, ~typing.Any]] | None = None, links: list[~capella2polarion.converters.converter_config.LinkConfig] = <factory>, is_actor: bool | None = None, nature: str | None = None)

Bases: object

A single Capella Type configuration.

converters: str | list[str] | dict[str, dict[str, Any]] | None = None
is_actor: bool | None = None
nature: str | None = None
p_type: str | None = None
class capella2polarion.converters.converter_config.ConverterConfig

Bases: object

The overall Config for capella2polarion.

add_layer(layer: str)

Add a new layer without configuring any types.

get_type_config(layer: str, c_type: str, **attributes: Any) → CapellaTypeConfig | None

Get the type config for a given layer and capella_type.

layers_and_types() → Iterator[tuple[str, str]]

Yield the layer and Capella type of the config.

read_config_file(synchronize_config: TextIO, type_prefix: str = '', role_prefix: str = '')

Read a given yaml file as config.

set_diagram_config(diagram_config: dict[str, Any], type_prefix: str = '', role_prefix: str = '')

Set the diagram config.

set_global_config(c_type: str, type_config: dict[str, Any], type_prefix: str = '', role_prefix: str = '')

Set a global config for a specific type.

set_layer_config(c_type: str, c_type_config: dict[str, Any] | list[dict[str, Any]] | None, layer: str, type_prefix: str = '', role_prefix: str = '')

Set one or multiple configs for a type to an existing layer.

class capella2polarion.converters.converter_config.LinkConfig(capella_attr: str, polarion_role: str, include: dict[str, str] = <factory>, link_field: str = '', reverse_field: str = '')

Bases: object

A single Capella Link configuration.

capella_attr

The Attribute name on the capellambse model object.

Type:

str

polarion_role

The identifier used in the Polarion configuration for this work item link (role).

Type:

str

include

A list of identifiers that are attribute names on the Capella objects link targets. The requested objects are then included in the list display in the grouped link custom field as nested lists. They also need be migrated for working references.

Type:

dict[str, str]

capella_attr: str
include: dict[str, str]
polarion_role: str
reverse_field: str = ''
capella2polarion.converters.converter_config.add_prefix(polarion_type: str, prefix: str) → str

Add a prefix to the given polarion_type.

capella2polarion.converters.converter_config.config_matches(config: CapellaTypeConfig | None, **kwargs: Any) → bool

Check whether the given config matches the given kwargs.

capella2polarion.converters.data_session module

A module to store data during the conversion process.

class capella2polarion.converters.data_session.ConverterData(layer: str, type_config: ~capella2polarion.converters.converter_config.CapellaTypeConfig, capella_element: ~capellambse.model._obj.ModelElement | ~capellambse.model.diagram.Diagram, work_item: ~capella2polarion.data_models.CapellaWorkItem | None = None, description_references: list[str] = <factory>, errors: set[str] = <factory>)

Bases: object

Data class holding all information needed during Conversion.

capella_element: ModelElement | Diagram
description_references: list[str]
errors: set[str]
layer: str
type_config: CapellaTypeConfig
work_item: CapellaWorkItem | None = None

capella2polarion.converters.document_config module

Module with classes and a loader for document rendering configs.

class capella2polarion.converters.document_config.BaseDocumentRenderingConfig(*, template_directory: str | Path, project_id: str | None = None, text_work_item_type: str = 'text', text_work_item_id_field: str = '__C2P__id', status_allow_list: list[str] | None = None, heading_numbering: bool = False, work_item_layouts: dict[str, WorkItemLayout] = None, instances: Sequence[DocumentRenderingInstance])

Bases: BaseModel

A template config, which can result in multiple Polarion documents.

heading_numbering: bool
instances: Sequence[DocumentRenderingInstance]
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'heading_numbering': FieldInfo(annotation=bool, required=False, default=False), 'instances': FieldInfo(annotation=Sequence[DocumentRenderingInstance], required=True), 'project_id': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'status_allow_list': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None), 'template_directory': FieldInfo(annotation=Union[str, Path], required=True), 'text_work_item_id_field': FieldInfo(annotation=str, required=False, default='__C2P__id'), 'text_work_item_type': FieldInfo(annotation=str, required=False, default='text'), 'work_item_layouts': FieldInfo(annotation=dict[str, WorkItemLayout], required=False, default_factory=dict)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

project_id: str | None
status_allow_list: list[str] | None
template_directory: str | Path
text_work_item_id_field: str
text_work_item_type: str
work_item_layouts: dict[str, WorkItemLayout]
class capella2polarion.converters.document_config.DocumentConfigs(*, full_authority: list[FullAuthorityDocumentRenderingConfig] = None, mixed_authority: list[MixedAuthorityDocumentRenderingConfig] = None)

Bases: BaseModel

The overall document configuration repository.

full_authority: list[FullAuthorityDocumentRenderingConfig]
iterate_documents() → Iterator[DocumentInfo]

Yield all document paths of the config as tuples.

mixed_authority: list[MixedAuthorityDocumentRenderingConfig]
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'full_authority': FieldInfo(annotation=list[FullAuthorityDocumentRenderingConfig], required=False, default_factory=list), 'mixed_authority': FieldInfo(annotation=list[MixedAuthorityDocumentRenderingConfig], required=False, default_factory=list)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class capella2polarion.converters.document_config.DocumentRenderingInstance(*, polarion_space: str, polarion_name: str, polarion_title: str | None = None, params: dict[str, Any] = None)

Bases: BaseModel

An instance of a document that should be created in Polarion.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'params': FieldInfo(annotation=dict[str, Any], required=False, default_factory=dict), 'polarion_name': FieldInfo(annotation=str, required=True), 'polarion_space': FieldInfo(annotation=str, required=True), 'polarion_title': FieldInfo(annotation=Union[str, NoneType], required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

params: dict[str, Any]
polarion_name: str
polarion_space: str
polarion_title: str | None
class capella2polarion.converters.document_config.FullAuthorityDocumentRenderingConfig(*, template_directory: str | Path, project_id: str | None = None, text_work_item_type: str = 'text', text_work_item_id_field: str = '__C2P__id', status_allow_list: list[str] | None = None, heading_numbering: bool = False, work_item_layouts: dict[str, WorkItemLayout] = None, instances: Sequence[DocumentRenderingInstance], template: str)

Bases: BaseDocumentRenderingConfig

Full authority document config with one template per document.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'heading_numbering': FieldInfo(annotation=bool, required=False, default=False), 'instances': FieldInfo(annotation=Sequence[DocumentRenderingInstance], required=True), 'project_id': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'status_allow_list': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None), 'template': FieldInfo(annotation=str, required=True), 'template_directory': FieldInfo(annotation=Union[str, Path], required=True), 'text_work_item_id_field': FieldInfo(annotation=str, required=False, default='__C2P__id'), 'text_work_item_type': FieldInfo(annotation=str, required=False, default='text'), 'work_item_layouts': FieldInfo(annotation=dict[str, WorkItemLayout], required=False, default_factory=dict)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

template: str
class capella2polarion.converters.document_config.MixedAuthorityDocumentRenderingConfig(*, template_directory: str | Path, project_id: str | None = None, text_work_item_type: str = 'text', text_work_item_id_field: str = '__C2P__id', status_allow_list: list[str] | None = None, heading_numbering: bool = False, work_item_layouts: dict[str, WorkItemLayout] = None, instances: Sequence[SectionBasedDocumentRenderingInstance], sections: dict[str, str])

Bases: BaseDocumentRenderingConfig

Mixed authority document with multiple auto generated sections.

instances: Sequence[SectionBasedDocumentRenderingInstance]
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'heading_numbering': FieldInfo(annotation=bool, required=False, default=False), 'instances': FieldInfo(annotation=Sequence[SectionBasedDocumentRenderingInstance], required=True), 'project_id': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'sections': FieldInfo(annotation=dict[str, str], required=True), 'status_allow_list': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None), 'template_directory': FieldInfo(annotation=Union[str, Path], required=True), 'text_work_item_id_field': FieldInfo(annotation=str, required=False, default='__C2P__id'), 'text_work_item_type': FieldInfo(annotation=str, required=False, default='text'), 'work_item_layouts': FieldInfo(annotation=dict[str, WorkItemLayout], required=False, default_factory=dict)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

sections: dict[str, str]
class capella2polarion.converters.document_config.SectionBasedDocumentRenderingInstance(*, polarion_space: str, polarion_name: str, polarion_title: str | None = None, params: dict[str, Any] = None, section_params: dict[str, dict[str, Any]] = None)

Bases: DocumentRenderingInstance

An instance of a mixed authority doc with section specific params.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'params': FieldInfo(annotation=dict[str, Any], required=False, default_factory=dict), 'polarion_name': FieldInfo(annotation=str, required=True), 'polarion_space': FieldInfo(annotation=str, required=True), 'polarion_title': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'section_params': FieldInfo(annotation=dict[str, dict[str, Any]], required=False, default_factory=dict)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

section_params: dict[str, dict[str, Any]]
class capella2polarion.converters.document_config.WorkItemLayout(*, show_description: bool = True, show_title: bool = True, show_fields_as_table: bool = True, fields_at_start: list[str] = None, fields_at_end: list[str] = None)

Bases: BaseModel

Configuration for rendering layouts of work items.

fields_at_end: list[str]
fields_at_start: list[str]
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'fields_at_end': FieldInfo(annotation=list[str], required=False, default_factory=list), 'fields_at_start': FieldInfo(annotation=list[str], required=False, default_factory=list), 'show_description': FieldInfo(annotation=bool, required=False, default=True), 'show_fields_as_table': FieldInfo(annotation=bool, required=False, default=True), 'show_title': FieldInfo(annotation=bool, required=False, default=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

show_description: bool
show_fields_as_table: bool
show_title: bool
capella2polarion.converters.document_config.generate_work_item_layouts(configs: dict[str, WorkItemLayout]) → list[RenderingLayout]

Create polarion_api.RenderingLayouts for a given configuration.

capella2polarion.converters.document_config.read_config_file(config: TextIO, model: MelodyModel | None = None) → DocumentConfigs

Read a yaml containing a list of DocumentRenderingConfigs.

capella2polarion.converters.document_renderer module

A jinja renderer for Polarion documents.

capella2polarion.converters.document_renderer.AREA_END_CLS = 'c2pAreaEnd'

This class is expected for a div in a wiki macro to start a rendering area in mixed authority documents.

capella2polarion.converters.document_renderer.AREA_START_CLS = 'c2pAreaStart'

This class is expected for a div in a wiki macro to end a rendering area in mixed authority documents.

class capella2polarion.converters.document_renderer.DocumentRenderer(polarion_repository: PolarionDataRepository, model: MelodyModel, model_work_item_project_id: str, overwrite_heading_numbering: bool = False, overwrite_layouts: bool = False)

Bases: JinjaRendererMixin

A Renderer class for Polarion documents.

render_document(template_folder: str | Path, template_name: str, polarion_folder: str, polarion_name: str, document_title: str | None = None, heading_numbering: bool = False, rendering_layouts: list[RenderingLayout] | None = None, *, text_work_item_provider: TextWorkItemProvider | None = None, document_project_id: str | None = None, **kwargs: Any) → DocumentData
render_document(template_folder: str | Path, template_name: str, *, document: Document, text_work_item_provider: TextWorkItemProvider | None = None, document_project_id: str | None = None, **kwargs: Any) → DocumentData

Render a Polarion document.

render_documents(configs: DocumentConfigs, existing_documents: dict[tuple[str | None, str, str], tuple[Document | None, list[WorkItem]]]) → dict[str | None, ProjectData]

Render all documents defined in the given config.

Returns a list new documents followed by updated documents and work items, which need to be updated

setup_env(env: Environment)

Add globals and filters to the environment.

update_mixed_authority_document(document: Document, template_folder: str | Path, sections: dict[str, str], global_parameters: dict[str, Any], section_parameters: dict[str, dict[str, Any]], text_work_item_provider: TextWorkItemProvider | None = None, document_project_id: str | None = None) → DocumentData

Update a mixed authority document.

class capella2polarion.converters.document_renderer.ProjectData(new_docs: list[~capella2polarion.data_models.DocumentData] = <factory>, updated_docs: list[~capella2polarion.data_models.DocumentData] = <factory>)

Bases: object

A class holding data of a project which documents are rendered for.

new_docs: list[DocumentData]
updated_docs: list[DocumentData]
class capella2polarion.converters.document_renderer.RenderingSession(headings: list[~polarion_rest_api_client.data_models.WorkItem] = <factory>, heading_ids: list[str] = <factory>, rendering_layouts: list[~polarion_rest_api_client.data_models.RenderingLayout] = <factory>, inserted_work_items: list[~polarion_rest_api_client.data_models.WorkItem] = <factory>, text_work_items: dict[str, ~polarion_rest_api_client.data_models.WorkItem] = <factory>, document_project_id: str | None = None)

Bases: object

A data class for parameters handled during a rendering session.

document_project_id: str | None = None
heading_ids: list[str]
headings: list[WorkItem]
inserted_work_items: list[WorkItem]
rendering_layouts: list[RenderingLayout]
text_work_items: dict[str, WorkItem]

capella2polarion.converters.element_converter module

Objects for serialization of capella objects to workitems.

class capella2polarion.converters.element_converter.CapellaWorkItemSerializer(model: MelodyModel, capella_polarion_mapping: PolarionDataRepository, converter_session: dict[str, ConverterData], generate_attachments: bool)

Bases: JinjaRendererMixin

The general serializer class for CapellaWorkItems.

diagram_cache_path: Path
model: MelodyModel
serialize(uuid: str) → CapellaWorkItem | None

Return a CapellaWorkItem for the given diagram or element.

serialize_all() → list[CapellaWorkItem]

Serialize all items of the converter_session.

setup_env(env: Environment)

Add the link rendering filter.

capella2polarion.converters.element_converter.resolve_element_type(type_: str) → str

Return a valid Type ID for polarion for a given obj.

capella2polarion.converters.model_converter module

A module containing the overall model conversion class.

class capella2polarion.converters.model_converter.ModelConverter(model: MelodyModel, project_id: str)

Bases: object

Class to convert elements of a model and store related data.

Generate links for all work items and add custom fields for them.

generate_work_items(polarion_data_repo: PolarionDataRepository, generate_links: bool = False, generate_attachments: bool = False, generate_grouped_links_custom_fields: bool = False) → dict[str, CapellaWorkItem]

Return a work items mapping from model elements for Polarion.

The dictionary maps Capella UUIDs to CapellaWorkItem s. In addition, it is ensured that neither title nor type are None, Links are not created in this step by default.

Parameters:

  • polarion_data_repo – The PolarionDataRepository object storing current work item data.

  • generate_links – A boolean flag to control linked work item generation.

  • generate_attachments – A boolean flag to control attachments generation. For SVG attachments, PNGs are generated and attached automatically.

  • generate_grouped_links_custom_fields – A boolean flag to control grouped links custom fields generation.

read_model(config: ConverterConfig)

Read the model using a given config and diagram_idx.

capella2polarion.converters.polarion_html_helper module

Functions for polarion specific HTMl elements.

class capella2polarion.converters.polarion_html_helper.JinjaRendererMixin

Bases: object

A MixIn for converters which should render jinja frequently.

check_model_element(obj: object) → ModelElement | AbstractDiagram | None

Check if a model element was passed.

Return None if no element and raise a TypeError if a wrong typed element was passed. Returns the element if it matches expectations.

jinja_envs: dict[str, Environment]
setup_env(env: Environment)

Implement this method to adjust a newly created environment.

capella2polarion.converters.polarion_html_helper.camel_case_to_words(camel_case_str: str)

Split camel or dromedary case and return it as a space separated str.

capella2polarion.converters.polarion_html_helper.ensure_fragments(html_content: str | list[HtmlElement | str]) → list[HtmlElement | str]

Convert string to html elements.

capella2polarion.converters.polarion_html_helper.extract_headings(html_content: str | list[HtmlElement | str]) → list[str]

Return a list of work item IDs for all headings in the given content.

capella2polarion.converters.polarion_html_helper.extract_work_items(html_content: str | list[HtmlElement | str], tag_regex: Pattern | None = None) → list[str]

Return a list of work item IDs for work items in the given content.

capella2polarion.converters.polarion_html_helper.generate_image_html(title: str, attachment_id: str, max_width: int, cls: str) → str

Generate an image as HTMl with the given source.

capella2polarion.converters.polarion_html_helper.get_layout_index(default_layouter: str, rendering_layouts: list[RenderingLayout], work_item_type: str) → int

Return the index of the layout of the requested workitem.

If there is no rendering config yet, it will be created.

capella2polarion.converters.polarion_html_helper.remove_table_ids(html_content: str | list[HtmlElement | str]) → list[HtmlElement | str]

Remove the ID field from all tables.

This is necessary due to a bug in Polarion where Polarion does not ensure that the tables added in the UI have unique IDs. At the same time the REST-API does not allow posting or patching a document with multiple tables having the same ID.

capella2polarion.converters.polarion_html_helper.strike_through(string: str) → str

Return a striked-through html span from given string.

capella2polarion.converters.text_work_item_provider module

Provides a class to generate and inset text work items in documents.

class capella2polarion.converters.text_work_item_provider.TextWorkItemProvider(text_work_item_id_field: str = '__C2P__id', text_work_item_type: str = 'text', existing_text_work_items: list[WorkItem] | None = None)

Bases: object

Class providing text work items, their generation and insertion.

generate_text_work_items(content: list[HtmlElement] | str, work_item_id_filter: list[str] | None = None)

Generate text work items from the provided html.

insert_text_work_items(document: Document)

Insert text work items into the given document.