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¶

links: list[LinkConfig]¶

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: str¶: The Attribute name on the capellambse model object.

include: dict[str, str]¶

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.

link_field: str = ''¶

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

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_model.work_items.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 | ~pathlib.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, ~capella2polarion.converters.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.converters.document_config.DocumentRenderingInstance])¶

Bases: BaseModel

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

heading_numbering: bool¶

instances: Sequence[DocumentRenderingInstance]¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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[~capella2polarion.converters.document_config.FullAuthorityDocumentRenderingConfig] = <factory>, mixed_authority: list[~capella2polarion.converters.document_config.MixedAuthorityDocumentRenderingConfig] = <factory>)¶

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_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class capella2polarion.converters.document_config.DocumentRenderingInstance(*, polarion_space: str, polarion_name: str, polarion_title: str | None = None, params: dict[str, ~typing.Any] = <factory>)¶

Bases: BaseModel

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

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

params: dict[str, Any]¶

polarion_name: str¶

polarion_space: str¶

polarion_title: str | None¶

class capella2polarion.converters.document_config.FullAuthorityDocumentRenderingConfig(*, template_directory: str | ~pathlib.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, ~capella2polarion.converters.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.converters.document_config.DocumentRenderingInstance], template: str)¶

Bases: BaseDocumentRenderingConfig

Full authority document config with one template per document.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

template: str¶

class capella2polarion.converters.document_config.MixedAuthorityDocumentRenderingConfig(*, template_directory: str | ~pathlib.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, ~capella2polarion.converters.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.converters.document_config.SectionBasedDocumentRenderingInstance], sections: dict[str, str])¶

Bases: BaseDocumentRenderingConfig

Mixed authority document with multiple auto generated sections.

instances: Sequence[SectionBasedDocumentRenderingInstance]¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sections: dict[str, str]¶

class capella2polarion.converters.document_config.SectionBasedDocumentRenderingInstance(*, polarion_space: str, polarion_name: str, polarion_title: str | None = None, params: dict[str, ~typing.Any] = <factory>, section_params: dict[str, dict[str, ~typing.Any]] = <factory>)¶

Bases: DocumentRenderingInstance

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

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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] = <factory>, fields_at_end: list[str] = <factory>)¶

Bases: BaseModel

Configuration for rendering layouts of work items.

fields_at_end: list[str]¶

fields_at_start: list[str]¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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_model.document_data.DocumentData] = <factory>, updated_docs: list[~capella2polarion.data_model.document_data.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_item_ids: list[str] = <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_item_ids: list[str]¶

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, generate_figure_captions: bool = False)¶

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.link_converter module¶

Objects for synchronization of Capella model objects to Polarion.

class capella2polarion.converters.link_converter.LinkSerializer(capella_polarion_mapping: PolarionDataRepository, converter_session: dict[str, ConverterData], project_id: str, model: MelodyModel)¶

Bases: object

A converter for capella element links and description references.

create_grouped_back_link_fields(work_item: CapellaWorkItem, links: dict[str, list[WorkItemLink]])¶

Create fields for the given WorkItem using a list of backlinks.

Parameters:

work_item – The ConverterData that stores the WorkItem to create the fields for.
links – Dict of field names and links referencing work_item as secondary.

create_grouped_link_fields(data: ConverterData, back_links: dict[str, dict[str, list[WorkItemLink]]] | None = None)¶

Create the grouped link fields from the primary work item.

Parameters:

data – The ConverterData that stores the WorkItem to create the fields for.
back_links – A dictionary of secondary WorkItem IDs to links to create backlinks later.

create_links_for_work_item(uuid: str) → list[WorkItemLink]¶: Create work item links for a given Capella object.

capella2polarion.converters.link_converter.find_link_config(data: ConverterData, role: str) → LinkConfig | None¶: Search for LinkConfig with matching polarion_role in data.

capella2polarion.converters.link_converter.make_link_logging_message(message: str, capella_attr: str) → list[str]¶: Return a list of strings for a link logging message.

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_work_item_links(polarion_data_repo: PolarionDataRepository, generate_grouped_links_custom_fields: bool)¶: 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, generate_figure_captions: 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.
generate_figure_captions – A boolean flag to enable the generation of figure captions

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, caption: tuple[str, str] | None = None) → 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.