polarion_rest_api_client.document_rendering package

Public API for rendering Polarion documents with Jinja2.

class polarion_rest_api_client.document_rendering.DocumentData(document: data_models.Document, headings: list[data_models.WorkItem], text_work_item_provider: text_work_item_provider.TextWorkItemProvider)

Bases: object

A rendered Polarion document together with companion metadata.

document: data_models.Document
headings: list[data_models.WorkItem]
text_work_item_provider: text_work_item_provider.TextWorkItemProvider
class polarion_rest_api_client.document_rendering.DocumentRenderer(default_project_id: str | None = None, *, work_item_lookup: Callable[[object], tuple[str | None, WorkItem | None]] | None = None, work_item_repository: Mapping[tuple[str, str], WorkItem] | None = None, area_start_class: str = 'autoRenderAreaStart', area_end_class: str = 'autoRenderAreaEnd', extra_template_context: dict[str, Any] | None = None)

Bases: object

A generic renderer for Polarion documents.

The renderer can resolve explicit (project_id, WorkItem) pairs and (project_id, work_item_id) or work_item_id references through an internal lookup repository. For project-specific object models, subclass it and override resolve_work_item() and optionally get_template_context(). Alternatively, pass a work_item_lookup callback to the constructor.

get_template_context() → dict[str, Any]

Return default template context values for each render.

render_document(template_folder: str | Path, template_name: str, polarion_folder: str, polarion_name: str, polarion_type: str | None = None, 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.

resolve_work_item(obj: object) → tuple[str | None, WorkItem | None]
resolve_work_item(project_id: str, work_item_id: str) → tuple[str | None, WorkItem | None]

Resolve a custom object into a Polarion work item.

The default implementation supports lookups by (project_id, work_item_id) and by work_item_id with default_project_id. For non-string objects, the default implementation delegates to the optional callback supplied at construction time.

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 polarion_rest_api_client.document_rendering.RenderingSession(document_project_id: str | None, headings: list[WorkItem] = <factory>, heading_ids: list[str] = <factory>, rendering_layouts: list[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 | None
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]
class polarion_rest_api_client.document_rendering.TextWorkItemProvider(text_work_item_id_field: str = '__AUTO_RENDER__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.

__init__(text_work_item_id_field: str = '__AUTO_RENDER__id', text_work_item_type: str = 'text', existing_text_work_items: list[WorkItem] | None = None) → None

Initialize the text work item provider.

Parameters:

  • text_work_item_id_field – The field name for custom IDs on text work items.

  • text_work_item_type – The type name for text work items.

  • existing_text_work_items – Existing text work items to reuse.

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.

Parameters:

  • content – HTML content to extract work items from.

  • work_item_id_filter – Only generate work items with these IDs.

insert_text_work_items(document: Document) → None

Insert text work items into the given document.

Parameters:

document – The document to insert work items into.

polarion_rest_api_client.document_rendering.camel_case_to_words(camel_case_str: str) → str

Split camel or dromedary case and return a spaced string.

polarion_rest_api_client.document_rendering.ensure_fragments(html_content: str | Sequence[HtmlFragment]) → list[HtmlFragment]

Convert string to html elements.

polarion_rest_api_client.document_rendering.extract_headings(html_content: str | Sequence[HtmlFragment]) → list[str]

Return work item IDs for headings.

polarion_rest_api_client.document_rendering.extract_work_items(html_content: str | Sequence[HtmlFragment], tag_regex: Pattern[str] | None = None) → list[str]

Return work item IDs from content.

polarion_rest_api_client.document_rendering.generate_image_html(title: str, attachment_id: str, max_width: int, css_class: str, caption: tuple[str, str] | None = None) → str

Generate Polarion HTML for an attached image.

polarion_rest_api_client.document_rendering.get_layout_index(default_layouter: str, rendering_layouts: list[RenderingLayout], work_item_type: str) → int

Return the index of layout for work item.

polarion_rest_api_client.document_rendering.remove_table_ids(html_content: str | Sequence[HtmlFragment]) → list[HtmlFragment]

Remove the ID field from all tables.

This works around a Polarion limitation where duplicate table IDs in document HTML are rejected by the REST API.

polarion_rest_api_client.document_rendering.strike_through(string: str) → str

Return a striked-through HTML span from the given string.

Submodules

polarion_rest_api_client.document_rendering.document_renderer module

A generic Jinja renderer for Polarion documents.

polarion_rest_api_client.document_rendering.document_renderer.DEFAULT_AREA_END_CLS = 'autoRenderAreaEnd'

Default marker class for the wiki macro that ends a rendering area.

polarion_rest_api_client.document_rendering.document_renderer.DEFAULT_AREA_START_CLS = 'autoRenderAreaStart'

Default marker class for the wiki macro that starts a rendering area.

class polarion_rest_api_client.document_rendering.document_renderer.DocumentRenderer(default_project_id: str | None = None, *, work_item_lookup: Callable[[object], tuple[str | None, WorkItem | None]] | None = None, work_item_repository: Mapping[tuple[str, str], WorkItem] | None = None, area_start_class: str = 'autoRenderAreaStart', area_end_class: str = 'autoRenderAreaEnd', extra_template_context: dict[str, Any] | None = None)

Bases: object

A generic renderer for Polarion documents.

The renderer can resolve explicit (project_id, WorkItem) pairs and (project_id, work_item_id) or work_item_id references through an internal lookup repository. For project-specific object models, subclass it and override resolve_work_item() and optionally get_template_context(). Alternatively, pass a work_item_lookup callback to the constructor.

get_template_context() → dict[str, Any]

Return default template context values for each render.

jinja_envs: dict[str, Environment]
render_document(template_folder: str | Path, template_name: str, polarion_folder: str, polarion_name: str, polarion_type: str | None = None, 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.

resolve_work_item(obj: object) → tuple[str | None, WorkItem | None]
resolve_work_item(project_id: str, work_item_id: str) → tuple[str | None, WorkItem | None]

Resolve a custom object into a Polarion work item.

The default implementation supports lookups by (project_id, work_item_id) and by work_item_id with default_project_id. For non-string objects, the default implementation delegates to the optional callback supplied at construction time.

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.

polarion_rest_api_client.document_rendering.html_utils module

Functions for generic Polarion-specific HTML elements.

type polarion_rest_api_client.document_rendering.html_utils.HtmlFragment = HtmlElement | str
polarion_rest_api_client.document_rendering.html_utils.camel_case_to_words(camel_case_str: str) → str

Split camel or dromedary case and return a spaced string.

polarion_rest_api_client.document_rendering.html_utils.ensure_fragments(html_content: str | Sequence[HtmlFragment]) → list[HtmlFragment]

Convert string to html elements.

polarion_rest_api_client.document_rendering.html_utils.extract_headings(html_content: str | Sequence[HtmlFragment]) → list[str]

Return work item IDs for headings.

polarion_rest_api_client.document_rendering.html_utils.extract_work_items(html_content: str | Sequence[HtmlFragment], tag_regex: Pattern[str] | None = None) → list[str]

Return work item IDs from content.

polarion_rest_api_client.document_rendering.html_utils.generate_image_html(title: str, attachment_id: str, max_width: int, css_class: str, caption: tuple[str, str] | None = None) → str

Generate Polarion HTML for an attached image.

polarion_rest_api_client.document_rendering.html_utils.get_layout_index(default_layouter: str, rendering_layouts: list[RenderingLayout], work_item_type: str) → int

Return the index of layout for work item.

polarion_rest_api_client.document_rendering.html_utils.remove_table_ids(html_content: str | Sequence[HtmlFragment]) → list[HtmlFragment]

Remove the ID field from all tables.

This works around a Polarion limitation where duplicate table IDs in document HTML are rejected by the REST API.

polarion_rest_api_client.document_rendering.html_utils.strike_through(string: str) → str

Return a striked-through HTML span from the given string.

polarion_rest_api_client.document_rendering.rendering_session module

Shared data structures for document rendering.

class polarion_rest_api_client.document_rendering.rendering_session.DocumentData(document: data_models.Document, headings: list[data_models.WorkItem], text_work_item_provider: text_work_item_provider.TextWorkItemProvider)

Bases: object

A rendered Polarion document together with companion metadata.

document: data_models.Document
headings: list[data_models.WorkItem]
text_work_item_provider: text_work_item_provider.TextWorkItemProvider
class polarion_rest_api_client.document_rendering.rendering_session.RenderingSession(document_project_id: str | None, headings: list[WorkItem] = <factory>, heading_ids: list[str] = <factory>, rendering_layouts: list[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 | None
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]

polarion_rest_api_client.document_rendering.text_work_item_provider module

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

class polarion_rest_api_client.document_rendering.text_work_item_provider.TextWorkItemProvider(text_work_item_id_field: str = '__AUTO_RENDER__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.

__init__(text_work_item_id_field: str = '__AUTO_RENDER__id', text_work_item_type: str = 'text', existing_text_work_items: list[WorkItem] | None = None) → None

Initialize the text work item provider.

Parameters:

  • text_work_item_id_field – The field name for custom IDs on text work items.

  • text_work_item_type – The type name for text work items.

  • existing_text_work_items – Existing text work items to reuse.

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.

Parameters:

  • content – HTML content to extract work items from.

  • work_item_id_filter – Only generate work items with these IDs.

insert_text_work_items(document: Document) → None

Insert text work items into the given document.

Parameters:

document – The document to insert work items into.