capella2polarion.documents package¶

A package containing document generation related modules.

Submodules¶

capella2polarion.documents.document_config module¶

Module with classes and a loader for document rendering configs.

class capella2polarion.documents.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.documents.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.documents.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.documents.document_config.DocumentConfigs(*, full_authority: list[~capella2polarion.documents.document_config.FullAuthorityDocumentRenderingConfig] = <factory>, mixed_authority: list[~capella2polarion.documents.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.documents.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.documents.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.documents.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.documents.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.documents.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.documents.document_config.WorkItemLayout] = <factory>, instances: ~collections.abc.Sequence[~capella2polarion.documents.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.documents.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.documents.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.documents.document_config.generate_work_item_layouts(configs: dict[str, WorkItemLayout]) → list[RenderingLayout]¶: Create polarion_api.RenderingLayouts for a given configuration.

capella2polarion.documents.document_config.read_config_file(config: TextIO, model: MelodyModel | None = None) → DocumentConfigs¶: Read a yaml containing a list of DocumentRenderingConfigs.

capella2polarion.documents.document_renderer module¶

A jinja renderer for Polarion documents.

capella2polarion.documents.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.documents.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.documents.document_renderer.DocumentRenderer(polarion_repository: PolarionDataRepository, model: MelodyModel, model_work_item_project_id: str)¶

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.

setup_env(env: Environment) → None¶: 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.documents.document_renderer.RenderingSession(document_project_id: str, 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[tuple[str, str]] = <factory>, text_work_items: dict[str, ~polarion_rest_api_client.data_models.WorkItem] = <factory>)¶

Bases: object

A data class for parameters handled during a rendering session.

document_project_id: str¶

heading_ids: list[str]¶

headings: list[WorkItem]¶

inserted_work_item_ids: list[tuple[str, str]]¶

rendering_layouts: list[RenderingLayout]¶

text_work_items: dict[str, WorkItem]¶

capella2polarion.documents.mass_document_renderer module¶

Provides functionalities to render multiple documents config based.

class capella2polarion.documents.mass_document_renderer.MassDocumentRenderer(polarion_repository: PolarionDataRepository, model: MelodyModel, model_work_item_project_id: str, overwrite_heading_numbering: bool = False, overwrite_layouts: bool = False)¶

Bases: object

A class to render multiple documents based on configs.

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 dict mapping project ID to new and updated documents.
Return type:: documents

class capella2polarion.documents.mass_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]¶

capella2polarion.documents.text_work_item_provider module¶

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

class capella2polarion.documents.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) → None¶: Generate text work items from the provided html.

insert_text_work_items(document: Document) → None¶: Insert text work items into the given document.