Metadata-Version: 2.4
Name: klword
Version: 1.0.2
Summary: Lightweight Word report generation library based on python-docx
Author-email: poggio <2322806855@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/poggiotzx/klword
Project-URL: Repository, https://github.com/poggiotzx/klword
Project-URL: Issues, https://github.com/poggiotzx/klword/issues
Project-URL: Changelog, https://github.com/poggiotzx/klword/blob/master/CHANGELOG.md
Project-URL: Documentation, https://github.com/poggiotzx/klword/blob/master/README.md
Keywords: word,docx,report,automation,python-docx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-docx>=1.1.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: docxtpl>=0.20.2
Requires-Dist: docxcompose>=1.4.1
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Requires-Dist: python-semantic-release>=9.15.0; extra == "dev"
Dynamic: license-file

# klword

English | [简体中文](README_CN.md)

[![PyPI](https://img.shields.io/pypi/v/klword)](https://pypi.org/project/klword/)
[![Python](https://img.shields.io/pypi/pyversions/klword)](https://pypi.org/project/klword/)
[![License](https://img.shields.io/github/license/poggiotzx/klword)](LICENSE)
[![CI](https://github.com/poggiotzx/klword/actions/workflows/ci.yml/badge.svg)](https://github.com/poggiotzx/klword/actions/workflows/ci.yml)
[![Publish](https://github.com/poggiotzx/klword/actions/workflows/publish.yml/badge.svg)](https://github.com/poggiotzx/klword/actions/workflows/publish.yml)

`klword` is a lightweight Word report generation library built on top of `python-docx`.

It provides a small, structured API for generating `.docx` reports from templates and
containerized content blocks. It is suitable for automated test reports, simulation reports,
and other document-generation workflows.

## Features

- Template-based Word report generation
- Structured content container API
- Text, image, and table insertion
- Rich text style helpers
- Automatic figure and table caption numbering
- PyPI-ready packaging and CI/CD workflows

## Installation

Install from PyPI:

```bash
pip install klword
```

Or install from source:

```bash
git clone https://github.com/poggiotzx/klword.git
cd klword
pip install -e .
```

## Quick Start

```python
from klword import WordAPI
from klword import BODY_STYLE, make_rich_text

api = WordAPI("templates/test.docx")

text = make_rich_text(
    "This text is inserted into the template.",
    BODY_STYLE,
)

image_container = api.new_container()
image_container.add_image(
    "templates/test_image.png",
    width_cm=8.0,
    align="center",
)

table_container = api.new_container()
table_container.add_table_by_config(
    {
        "data": [
            ["Name", "Value"],
            ["Example", "123"],
        ]
    }
)

api.render(
    {
        "text": text,
        "image": image_container.subdoc,
        "table": table_container.subdoc,
    },
    "report.docx",
)
```

## Project Structure

```text
klword
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── publish.yml
│       └── release.yml
├── examples/
├── src/
│   └── klword/
│       ├── __init__.py
│       ├── word_api.py
│       ├── word_styles.py
│       └── templates/
├── tests/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README_CN.md
└── pyproject.toml
```

## Release Automation

This repository is prepared for a professional Python package workflow:

- **CI** runs lint and tests on push and pull request.
- **Semantic Release** updates the version, changelog, tag, and GitHub Release.
- **Trusted Publishing** publishes to PyPI from GitHub Actions without a PyPI API token.
- **Build artifacts** include both source distribution and wheel.

## Development

```bash
pip install -e .[dev]
pytest
ruff check .
```

## License

MIT License. See [LICENSE](LICENSE).
