dfk1352/LibreOffice-skills / skills/libreoffice-writer
libreoffice-writer
VerifiedUse when creating, editing, formatting, exporting, or extracting LibreOffice Writer (.odt) documents via UNO, including session-based edits, structured text targets, tables, images, lists, patch workflows, and snapshots.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| references/troubleshooting.md | markdown | 3.9 KB |
| scripts/colors.py | script | 4.6 KB |
| scripts/constants.py | script | 180 B |
| scripts/exceptions.py | script | 748 B |
| scripts/patch_base.py | script | 12.1 KB |
| scripts/session.py | script | 2.6 KB |
| scripts/uno_bridge.py | script | 9.1 KB |
| scripts/writer/__init__.py | script | 554 B |
| scripts/writer/core.py | script | 3.4 KB |
| scripts/writer/exceptions.py | script | 2.5 KB |
| scripts/writer/patch.py | script | 9.4 KB |
| scripts/writer/session.py | script | 18.8 KB |
| scripts/writer/snapshot.py | script | 5.6 KB |
| scripts/writer/targets.py | script | 14.7 KB |
scripts/writer/session.py
View on GitHub"""Session-based editing API for Writer documents."""
from pathlib import Path
from typing import Any
from colors import resolve_color
from constants import ALIGNMENT_MAP
from session import BaseSession
from uno_bridge import uno_context
from writer.core import EXPORT_FILTERS
from writer.exceptions import (
DocumentNotFoundError,
ImageNotFoundError,
InvalidMetadataError,
WriterSessionError,
WriterSkillError,
)
from writer.patch import PatchApplyMode
from writer.targets import (
ListItem,
TextFormatting,
WriterTarget,
resolve_image_target,
resolve_insertion_point,
resolve_list_target,
resolve_table_target,
resolve_text_range,
validate_formatting,
validate_image_update,
validate_list_items,
validate_table_data,
)
_PARAGRAPH_BREAK = 0
_BOLD_WEIGHT = 150
_NORMAL_WEIGHT = 100
_ITALIC_POSTURE = 2
_NORMAL_POSTURE = 0
_SINGLE_UNDERLINE = 1
_NO_UNDERLINE = 0
_ALIGNMENT_MAP = ALIGNMENT_MAP
_ORDERED_LIST_STYLE = "Numbering 123"
_UNORDERED_LIST_STYLE = "List 1"
class WriterSession(BaseSession):
"""Long-lived Writer editing session bound to one document."""
def __init__(self, path: str) -> None:
super().__init__(closed_error_type=WriterSessionError)
self._path = Path(path)
if not self._path.exists():
raise DocumentNotFoundError(f"Document not found: {path}")
self._open_document()
@property
def doc(self) -> Any:
self._require_open()
return self._doc
def read_text(self, target: WriterTarget | None = None) -> str:
self._require_open()
if target is None:
return self._doc.Text.getString()
return resolve_text_range(target, self._doc).getString()
def insert_text(self, text: str, target: WriterTarget | None = None) -> None:
self._require_open()
cursor = resolve_insertion_point(target, self._doc)
_insert_string(self._doc.Text, cursor, text)
def replace_text(self, target: WriterTarget, new_text: str) -> None:
self._require_open()
match = resolve_text_range(target, self._doc)
match.setString(new_text)
def delete_text(self, target: WriterTarget) -> None:
self._require_open()
match = resolve_text_range(target, self._doc)
match.setString("")
def format_text(self, target: WriterTarget, formatting: TextFormatting) -> None:
self._require_open()
validate_formatting(formatting)
text_range = resolve_text_range(target, self._doc)
_apply_formatting(text_range, formatting)
def insert_table(
self,
rows: int,
cols: int,
data: list[list[Any]] | None = None,
name: str | None = None,
target: WriterTarget | None = None,
) -> None:
self._require_open()
validate_table_data(rows, cols, data)
table = self._doc.createInstance("com.sun.star.text.TextTable")
table.initialize(rows, cols)
cursor = resolve_insertion_point(target, self._doc)
self._doc.Text.insertTextContent(cursor, table, False)
if name is not None:
_assign_content_name(table, name)
if data is not None:
_write_table_data(table, data)
def update_table(self, target: WriterTarget, data: list[list[Any]]) -> None:
self._require_open()
table = resolve_table_target(target, self._doc)
rows = table.Rows.Count
cols = table.Columns.Count
validate_table_data(rows, cols, data)
_write_table_data(table, data)
def delete_table(self, target: WriterTarget) -> None:
self._require_open()
table = resolve_table_target(target, self._doc)
try:
self._doc.Text.removeTextContent(table)
except Exception:
table.dispose()
def insert_image(
self,
image_path: str,
width: int | None = None,
height: int | None = None,
name: str | None = None,
target: WriterTarget | None = None,
) -> None:
self._require_open()
image_file = Path(image_path)
if not image_file.exists():
raise ImageNotFoundError(f"Image not found: {image_path}")
graphic = self._doc.createInstance("com.sun.star.text.GraphicObject")
graphic.GraphicURL = image_file.resolve().as_uri()
if width is not None or height is not None:
_set_graphic_size(graphic, width, height)
cursor = resolve_insertion_point(target, self._doc)
self._doc.Text.insertTextContent(cursor, graphic, False)
if name is not None:
_assign_content_name(graphic, name)
def update_image(
self,
target: WriterTarget,
image_path: str | None = None,
width: int | None = None,
height: int | None = None,
) -> None:
self._require_open()
validate_image_update(image_path, width, height)
graphic = resolve_image_target(target, self._doc)
if image_path is not None:
image_file = Path(image_path)
if not image_file.exists():
raise ImageNotFoundError(f"Image not found: {image_path}")
graphic.GraphicURL = image_file.resolve().as_uri()
if width is not None or height is not None:
_set_graphic_size(graphic, width, height)
def delete_image(self, target: WriterTarget) -> None:
self._require_open()
graphic = resolve_image_target(target, self._doc)
try:
self._doc.Text.removeTextContent(graphic)
except Exception:
graphic.dispose()
def insert_list(
self,
items: list[ListItem],
ordered: bool,
target: WriterTarget | None = None,
) -> None:
self._require_open()
validate_list_items(items)
cursor = resolve_insertion_point(target, self._doc)
if target is not None and target.after is not None and target.before is None:
cursor, following_list = _advance_cursor_past_following_list(cursor)
if following_list:
_apply_list_style_to_paragraphs(following_list, ordered)
_insert_list_at_cursor(self._doc.Text, cursor, items, ordered)
def replace_list(
self,
target: WriterTarget,
items: list[ListItem],
ordered: bool | None = None,
) -> None:
self._require_open()
validate_list_items(items)
paragraphs = resolve_list_target(target, self._doc)
ordered_value = ordered
if ordered_value is None:
ordered_value = _paragraphs_are_ordered(paragraphs)
anchor = _delete_paragraph_block(self._doc, paragraphs)
_insert_list_at_cursor(self._doc.Text, anchor, items, ordered_value)
def delete_list(self, target: WriterTarget) -> None:
self._require_open()
paragraphs = resolve_list_target(target, self._doc)
_delete_paragraph_block(self._doc, paragraphs)
def set_metadata(self, values: dict[str, str]) -> None:
"""Set metadata properties on the open document.
Args:
values: Dictionary of metadata key-value pairs.
Supported keys: title, author, subject, keywords, description.
Raises:
InvalidMetadataError: If any key is empty.
"""
self._require_open()
if any(not key for key in values):
raise InvalidMetadataError("Metadata keys must be non-empty")
doc_info = self._doc.getDocumentProperties()
if "title" in values:
doc_info.Title = values["title"]
if "author" in values:
doc_info.Author = values["author"]
if "subject" in values:
doc_info.Subject = values["subject"]
if "keywords" in values:
keywords = values["keywords"]
if isinstance(keywords, str):
keyword_list = [k.strip() for k in keywords.split(",")]
doc_info.Keywords = tuple(keyword_list)
else:
doc_info.Keywords = tuple(keywords)
if "description" in values:
doc_info.Description = values["description"]
def get_metadata(self) -> dict[str, str]:
"""Read metadata properties from the open document.
Returns:
Dictionary with keys: title, author, subject, keywords,
description.
"""
self._require_open()
doc_info = self._doc.getDocumentProperties()
return {
"title": doc_info.Title or "",
"author": doc_info.Author or "",
"subject": doc_info.Subject or "",
"keywords": ", ".join(doc_info.Keywords) or "",
"description": doc_info.Description or "",
}
def patch(self, patch_text: str, mode: PatchApplyMode = "atomic"):
self._require_open()
from writer.patch import apply_operations
return apply_operations(self, patch_text, mode)
def export(self, output_path: str, export_format: str) -> None:
"""Export the current document state to another Writer-supported format."""
self._require_open()
if export_format not in EXPORT_FILTERS:
raise WriterSkillError(f"Unsupported export format: {export_format}")
output = Path(output_path)
output.parent.mkdir(parents=True, exist_ok=True)
import uno # type: ignore[import-not-found]
filter_prop = uno.createUnoStruct("com.sun.star.beans.PropertyValue")
filter_prop.Name = "FilterName"
filter_prop.Value = EXPORT_FILTERS[export_format]
self._doc.storeToURL(output.resolve().as_uri(), (filter_prop,))
def _open_document(self) -> None:
self._uno_manager = uno_context()
self._desktop = self._uno_manager.__enter__()
assert self._path is not None
try:
self._doc = self._desktop.loadComponentFromURL(
self._path.resolve().as_uri(),
"_blank",
0,
(),
)
if self._doc is None:
raise DocumentNotFoundError(
f"Failed to open Writer document: {self._path}"
)
except Exception as exc:
self._uno_manager.__exit__(type(exc), exc, exc.__traceback__)
self._uno_manager = None
self._desktop = None
if isinstance(exc, DocumentNotFoundError):
raise
raise WriterSkillError(
f"Failed to open Writer document: {self._path}"
) from exc
self._closed = False
def _insert_string(text_obj: Any, cursor: Any, text: str) -> None:
if not _cursor_is_at_paragraph_boundary(cursor) and _cursor_has_text_before(cursor):
text_obj.insertControlCharacter(cursor, _PARAGRAPH_BREAK, False)
parts = text.split("\n")
for index, part in enumerate(parts):
if index > 0:
text_obj.insertControlCharacter(cursor, _PARAGRAPH_BREAK, False)
if part:
text_obj.insertString(cursor, part, False)
def _apply_formatting(text_range: Any, formatting: TextFormatting) -> None:
paragraph_cursor = _paragraph_cursor_for_range(text_range)
if formatting.bold is not None:
text_range.CharWeight = _BOLD_WEIGHT if formatting.bold else _NORMAL_WEIGHT
if formatting.italic is not None:
text_range.CharPosture = (
_ITALIC_POSTURE if formatting.italic else _NORMAL_POSTURE
)
if formatting.underline is not None:
text_range.CharUnderline = (
_SINGLE_UNDERLINE if formatting.underline else _NO_UNDERLINE
)
if formatting.font_name is not None:
text_range.CharFontName = formatting.font_name
if formatting.font_size is not None:
text_range.CharHeight = formatting.font_size
if formatting.color is not None:
text_range.CharColor = resolve_color(formatting.color)
if formatting.align is not None:
paragraph_cursor.ParaAdjust = _ALIGNMENT_MAP[
str(formatting.align).strip().lower()
]
if formatting.line_spacing is not None:
import uno # type: ignore[import-not-found]
line_spacing = uno.createUnoStruct("com.sun.star.style.LineSpacing")
line_spacing.Mode = 0
line_spacing.Height = int(formatting.line_spacing * 100)
paragraph_cursor.ParaLineSpacing = line_spacing
if formatting.spacing_before is not None:
paragraph_cursor.ParaTopMargin = formatting.spacing_before
if formatting.spacing_after is not None:
paragraph_cursor.ParaBottomMargin = formatting.spacing_after
def _paragraph_cursor_for_range(text_range: Any) -> Any:
text_obj = text_range.getText()
paragraph_cursor = text_obj.createTextCursorByRange(text_range.Start)
paragraph_cursor.gotoStartOfParagraph(False)
paragraph_end = text_obj.createTextCursorByRange(text_range.End)
paragraph_end.gotoEndOfParagraph(False)
paragraph_cursor.gotoRange(paragraph_end.getEnd(), True)
return paragraph_cursor
def _write_table_data(table: Any, data: list[list[Any]]) -> None:
for row_index, row_data in enumerate(data):
for col_index, cell_value in enumerate(row_data):
table.getCellByName(_get_cell_name(row_index, col_index)).setString(
str(cell_value)
)
def _insert_list_at_cursor(
text_obj: Any,
cursor: Any,
items: list[ListItem],
ordered: bool,
) -> None:
style_name = _ORDERED_LIST_STYLE if ordered else _UNORDERED_LIST_STYLE
if not _cursor_is_at_paragraph_boundary(cursor) and _cursor_has_text_before(cursor):
text_obj.insertControlCharacter(cursor, _PARAGRAPH_BREAK, False)
for index, item in enumerate(items):
start = cursor.getStart()
text_obj.insertString(cursor, item.text, False)
paragraph_cursor = text_obj.createTextCursorByRange(start)
paragraph_cursor.gotoRange(cursor.getEnd(), True)
paragraph_cursor.NumberingStyleName = style_name
paragraph_cursor.NumberingLevel = item.level
if index < len(items) - 1:
text_obj.insertControlCharacter(cursor, _PARAGRAPH_BREAK, False)
def _advance_cursor_past_following_list(cursor: Any) -> tuple[Any, list[Any]]:
text_obj = cursor.getText()
enumeration = text_obj.createEnumeration()
trailing_list: list[Any] = []
cursor_start = _range_start(cursor)
while enumeration.hasMoreElements():
paragraph = enumeration.nextElement()
if not _range_is_after(text_obj, _range_start(paragraph), cursor_start):
continue
if not paragraph.getString() and not getattr(
paragraph, "NumberingStyleName", ""
):
continue
if getattr(paragraph, "NumberingStyleName", ""):
trailing_list.append(paragraph)
continue
break
if not trailing_list:
return cursor, []
return text_obj.createTextCursorByRange(
_range_end(trailing_list[-1])
), trailing_list
def _cursor_has_text_before(cursor: Any) -> bool:
probe = cursor.getText().createTextCursorByRange(cursor.getStart())
probe.gotoStart(True)
return bool(probe.getString())
def _cursor_is_at_paragraph_boundary(cursor: Any) -> bool:
probe = cursor.getText().createTextCursorByRange(cursor.getStart())
try:
return probe.isStartOfParagraph()
except Exception:
return False
def _range_is_after(text_obj: Any, first: Any, second: Any) -> bool:
return text_obj.compareRegionStarts(first, second) < 0
def _range_start(text_range: Any) -> Any:
anchored = _anchored_range(text_range)
if anchored is not text_range:
return _range_start(anchored)
try:
return text_range.getStart()
except AttributeError:
return text_range.Start
def _range_end(text_range: Any) -> Any:
anchored = _anchored_range(text_range)
if anchored is not text_range:
return _range_end(anchored)
try:
return text_range.getEnd()
except AttributeError:
return text_range.End
def _anchored_range(text_range: Any) -> Any:
try:
anchor = text_range.getAnchor()
except Exception:
anchor = getattr(text_range, "Anchor", None)
return anchor if anchor is not None else text_range
def _delete_paragraph_block(doc: Any, paragraphs: list[Any]) -> Any:
text_obj = doc.Text
cursor = text_obj.createTextCursorByRange(paragraphs[0].getStart())
if len(paragraphs) == 1:
paragraph = paragraphs[0]
paragraph.setString("")
paragraph.NumberingStyleName = ""
paragraph.NumberingLevel = 0
return cursor
for paragraph in reversed(paragraphs):
try:
paragraph.dispose()
except Exception:
paragraph.setString("")
paragraph.NumberingStyleName = ""
paragraph.NumberingLevel = 0
try:
cursor.collapseToStart()
except Exception:
pass
return cursor
def _paragraphs_are_ordered(paragraphs: list[Any]) -> bool:
if not paragraphs:
return False
numbering_type = _paragraph_numbering_type(paragraphs[0])
return numbering_type == 4
def _apply_list_style_to_paragraphs(paragraphs: list[Any], ordered: bool) -> None:
style_name = _ORDERED_LIST_STYLE if ordered else _UNORDERED_LIST_STYLE
for paragraph in paragraphs:
paragraph.NumberingStyleName = style_name
def _paragraph_numbering_type(paragraph: Any) -> int | None:
rules = getattr(paragraph, "NumberingRules", None)
if rules is None:
return None
level = int(getattr(paragraph, "NumberingLevel", 0))
try:
properties = rules.getByIndex(level)
except Exception:
properties = rules.getByIndex(0)
for property_value in properties:
if getattr(property_value, "Name", None) == "NumberingType":
try:
return int(property_value.Value)
except Exception:
return None
return None
def _get_cell_name(row: int, col: int) -> str:
col_name = ""
col_num = col + 1
while col_num > 0:
col_num -= 1
col_name = chr(65 + (col_num % 26)) + col_name
col_num //= 26
return f"{col_name}{row + 1}"
def _set_graphic_size(graphic: Any, width: int | None, height: int | None) -> None:
import uno # type: ignore[import-not-found]
current = graphic.Size
size = uno.createUnoStruct("com.sun.star.awt.Size")
size.Width = current.Width if width is None else width
size.Height = current.Height if height is None else height
graphic.setSize(size)
def _assign_content_name(content: Any, name: str) -> None:
candidates = [name]
normalized = "_".join(name.split())
if normalized != name:
candidates.append(normalized)
for candidate in candidates:
if hasattr(content, "setName"):
try:
content.setName(candidate)
return
except Exception:
pass
try:
content.Name = candidate
return
except Exception:
pass
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |