Metadata-Version: 2.5
Name: ottertf
Version: 0.0.0
Summary: Extract HTML embedded in RTF (MS-OXRTFEX de-encapsulation).
Project-URL: Documentation, https://tschuelia.github.io/golden-retriever/
Project-URL: Issues, https://github.com/tschuelia/golden-retriever/issues
Project-URL: Repository, https://github.com/tschuelia/golden-retriever
Author: Julia Haag
License-Expression: MIT
License-File: LICENSE
Keywords: deencapsulation,email,html,ms-oxrtfex,msg,outlook,rtf
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Golden Retriever 🦮

[![CI](https://github.com/tschuelia/golden-retriever/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tschuelia/golden-retriever/actions/workflows/ci.yml)
[![Documentation](https://github.com/tschuelia/golden-retriever/actions/workflows/docs.yml/badge.svg?branch=main)](https://tschuelia.github.io/golden-retriever/)

Recover the original HTML from RTF-encapsulated HTML: the `\fromhtml1` form
that Microsoft Outlook and Exchange can store in a message's
`PidTagRtfCompressed` property.

golden-retriever implements de-encapsulation from
[MS-OXRTFEX](https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxrtfex/906fbb0f-2467-490e-8c3e-bdc31c5e9d35),
using the
[RTF 1.9.1 specification](<https://learn.microsoft.com/en-us/previous-versions/office/developer/office-2007/dd351035(v=office.12)>)
and Microsoft's
[code-page registry](https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers).
It has no runtime dependencies.

## Install

This `0.0.0` release is a functional bootstrap for the future `ottertf`
distribution name. Install it from PyPI with:

```console
python -m pip install ottertf==0.0.0
```

The import package remains `golden_retriever` in this bootstrap release.

Install the package from conda-forge:

```console
conda install -c conda-forge golden-retriever
```

With Pixi, add it to a workspace instead:

```console
pixi add golden-retriever
```

The package named `golden-retriever` on PyPI is unrelated to this repository;
do not install that package as a substitute.

## Use

Pass **uncompressed RTF bytes**, not an `.msg` file and not the compressed
`PidTagRtfCompressed` payload:

```python
import golden_retriever as gr

raw_rtf: bytes = ...

content_type = gr.detect_content_type(raw_rtf)
if content_type is gr.ContentType.NATIVE_RTF:
    raise ValueError("the message contains ordinary RTF")

result = gr.deencapsulate(raw_rtf)
print(result.content_type)  # ContentType.HTML or ContentType.TEXT
print(result.body)  # decoded str
print(result.diagnostics)
```

Extraction preserves the producer's HTML charset declaration even though the
result is already a Python `str`. If you serialize as UTF-8, make the declaration
agree first:

```python
html = gr.normalize_charset_declaration(result.body, "utf-8")
with open("mail.html", "w", encoding="utf-8") as output:
    output.write(html)
```

The default parser recovers usable content and reports damage in
`result.diagnostics`. `strict=True` raises structural problems instead. Native
RTF always raises `NotEncapsulatedRtfError` when passed to `deencapsulate`.

## Scope

The package performs one deliberately narrow step:

```text
.msg container -> RTF-compressed bytes -> uncompressed RTF -> HTML
       caller             caller          golden-retriever
```

It does not parse `.msg` compound files, decompress the RTF compression wrapper,
render native RTF, resolve `cid:` attachments, fetch resources, or sanitize HTML.
The returned markup is untrusted input and must be sanitized before browser use.

Read the [documentation](https://tschuelia.github.io/golden-retriever/) for the
format history, annotated examples, extraction algorithm, encoding rules,
diagnostic policy, conformance notes, and API reference.

## Development

The repository uses [Pixi](https://pixi.sh/):

```console
pixi install
pixi run postinstall
pixi run test
pixi run -e lint lint
pixi run -e docs docs-build
pixi run -e docs docs-serve
```

Slow performance checks are available with `pixi run test-slow`. See the
[development guide](https://tschuelia.github.io/golden-retriever/development/)
for the supported Python matrix and fixture rules.

## License

[MIT](LICENSE)
