Metadata-Version: 2.4
Name: docxlite
Version: 0.0.1
Author-email: Nathan Cooper <nathanacooper@proton.me>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/docxlite
Project-URL: Documentation, https://AnswerDotAI.github.io/docxlite/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: python-docx
Dynamic: license-file

# docxlite


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

`docxlite` is a small layer on top of
[`python-docx`](https://python-docx.readthedocs.io/) for reading,
previewing, searching, and editing Word documents from Python. It gives
`.docx` files a notebook-friendly markdown preview, adds simple markdown
insertion, and supports tracked insertions and deletions with author
attribution.

It is designed for document automation workflows where an agent or
notebook needs to make precise edits to Word files without losing the
structure that matters: paragraphs, tables, runs, formatting, and
revision metadata.

## Installation

Install latest from [pypi](https://pypi.org/project/docxlite/)

``` sh
$ pip install docxlite
```

## How to use

``` python
from docxlite import *
```

Create or open a Word document using `DocxDocument`. In a notebook or
solveit dialog, the document renders as markdown so you can inspect its
contents without downloading and opening Word.

``` python
doc = DocxDocument()
p = doc.add_paragraph('Hello from docxlite')
doc
```

<div class="prose">

Hello from docxlite

</div>

`add_md` parses a small markdown subset and adds formatted runs to an
existing paragraph. It supports bold, italic, bold-italic, and
underline.

``` python
p = doc.add_paragraph()
p.add_md('This has **bold**, *italic*, and <u>underline</u>.')
```

<div class="prose">

This has **bold**, *italic*, and <u>underline</u>.

</div>

Tables render as markdown tables, and `add_row` accepts cell values
directly. Cell contents can use the same inline markdown formatting as
paragraphs.

``` python
tbl = doc.add_table(rows=0, cols=3)
tbl.add_row('Name', 'Value', 'Notes')
tbl.add_row('Apples', '42', '**crisp**')
tbl
```

<div class="prose">

| Name   | Value | Notes     |
|--------|-------|-----------|
| Apples | 42    | **crisp** |

</div>

Documents are iterable in body order. That matters because `python-docx`
exposes `doc.paragraphs` and `doc.tables` separately, which loses the
interleaving of paragraphs and tables in the original file.

``` python
for block in doc:
    print(type(block).__name__, block._text[:40] if hasattr(block, '_text') else '')
```

    Paragraph Hello from docxlite
    Paragraph This has bold, italic, and underline.
    Table Name  Value   Notes
    Apples  42  crisp

`search` returns the matching document blocks themselves, not detached
search results. You can search for text, then edit the returned
paragraph or table directly.

``` python
hits = doc.search('bold')
hits[0]
```

<div class="prose">

This has **bold**, *italic*, and <u>underline</u>.

</div>

## Tracked changes

Call `set_tracking(author)` to make insertions and deletions appear as
Word tracked changes. Use `set_tracking(None)` when you want edits to be
applied directly.

``` python
set_tracking('AI Editor')
hits[0].insert_after('Inserted with tracking enabled.')
doc
```

<div class="prose">

Hello from docxlite

This has **bold**, *italic*, and <u>underline</u>.

<span class="insertion">Inserted with tracking enabled.</span>

| Name   | Value | Notes     |
|--------|-------|-----------|
| Apples | 42    | **crisp** |

</div>

Deleting with tracking enabled marks content as deleted instead of
removing it. Deleted text appears in the markdown preview using revision
spans, and Word will show it as a tracked deletion.

``` python
doc.search('Hello')[0].delete()
doc
```

<div class="prose">

<span class="deletion">Hello from docxlite</span>

This has **bold**, *italic*, and <u>underline</u>.

<span class="insertion">Inserted with tracking enabled.</span>

| Name   | Value | Notes     |
|--------|-------|-----------|
| Apples | 42    | **crisp** |

</div>

## LLM Integration

`docxlite` ships with a `pyskills` integration for LLM agents. Importing
`docxlite.skill` exposes the document classes and editing methods to the
tool system, and enables tracked changes with
`set_tracking('AI Editor')` by default so agent edits are reviewable in
Word.

``` python
from docxlite.skill import *
```

The skill uses the same API as regular `docxlite`; the difference is
that the relevant classes and methods are registered for safe tool
access. That lets an LLM search, preview, insert, delete, and save
`.docx` files while preserving revision metadata.

``` python
skill_doc = DocxDocument()
skill_doc.add_paragraph('Inserted through the docxlite pyskill')
skill_doc
```

## Saving

Save the edited document with the normal `python-docx` API.

``` python
doc.save('example.docx')
```
