docxspec 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on Keep a Changelog and is maintained automatically by Semantic Release.
6
+
7
+ ## [0.1.0] - 2026-03-16
8
+
9
+ ### Added
10
+
11
+ - Initial public release of `klword`
12
+ - `WordAPI` and `DocContainer` for template-based document generation
13
+ - Style helpers for text and table content
14
+ - CI, release, and PyPI publishing automation
docxspec-0.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Poggi-Tang
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,5 @@
1
+ include README.md
2
+ include README_CN.md
3
+ include LICENSE
4
+ include CHANGELOG.md
5
+ recursive-include src/docxspec/templates *
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.4
2
+ Name: docxspec
3
+ Version: 0.0.1
4
+ Summary: Lightweight Word report generation library based on python-docx
5
+ Author-email: poggio <2322806855@qq.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Poggi-Tang/docxspec
8
+ Project-URL: Repository, https://github.com/Poggi-Tang/docxspec
9
+ Project-URL: Issues, https://github.com/Poggi-Tang/docxspec/issues
10
+ Project-URL: Changelog, https://github.com/Poggi-Tang/docxspec/blob/master/CHANGELOG.md
11
+ Project-URL: Documentation, https://github.com/Poggi-Tang/docxspec/blob/master/README.md
12
+ Keywords: word,docx,report,automation,python-docx
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Topic :: Office/Business
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: python-docx>=1.1.0
25
+ Requires-Dist: Pillow>=10.0.0
26
+ Requires-Dist: docxtpl>=0.20.2
27
+ Requires-Dist: docxcompose>=1.4.1
28
+ Provides-Extra: dev
29
+ Requires-Dist: build>=1.2.2; extra == "dev"
30
+ Requires-Dist: pytest>=8.0; extra == "dev"
31
+ Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
32
+ Requires-Dist: ruff>=0.11.0; extra == "dev"
33
+ Requires-Dist: python-semantic-release>=9.15.0; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+ # docxspec
37
+ English | [简体中文](README.zh-CN.md)
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/docxspec?cacheSeconds=300)](https://pypi.org/project/docxspec/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/docxspec?cacheSeconds=300)](https://pypi.org/project/docxspec/)
41
+ [![License](https://img.shields.io/github/license/Poggi-Tang/docxspec)](https://github.com/Poggi-Tang/docxspec/blob/main/LICENSE)
42
+ [![CI](https://github.com/Poggi-Tang/docxspec/actions/workflows/ci.yml/badge.svg)](https://github.com/Poggi-Tang/docxspec/actions/workflows/ci.yml)
43
+ [![Publish](https://github.com/Poggi-Tang/docxspec/actions/workflows/publish.yml/badge.svg)](https://github.com/Poggi-Tang/docxspec/actions/workflows/publish.yml)
44
+
45
+ `docxspec` is a lightweight Word report generation library built on top of `python-docx`.
46
+
47
+ It provides a small, structured API for generating `.docx` reports from user-supplied templates
48
+ and containerized content blocks. It is suitable for automated test reports, simulation reports,
49
+ and other document-generation workflows.
50
+
51
+ ## Features
52
+
53
+ - Template-based Word report generation
54
+ - Structured content container API
55
+ - Text, image, and table insertion
56
+ - Rich text style helpers
57
+ - Automatic figure and table caption numbering
58
+ - PyPI-ready packaging and CI/CD workflows
59
+
60
+ ## Installation
61
+
62
+ Install from PyPI:
63
+
64
+ ```bash
65
+ pip install docxspec
66
+ ```
67
+
68
+ Or install from source:
69
+
70
+ ```bash
71
+ git clone https://github.com/Poggi-Tang/docxspec.git
72
+ cd docxspec
73
+ pip install -e .
74
+ ```
75
+
76
+ ## Quick Start
77
+
78
+ ```python
79
+ from docxspec import BODY_STYLE, WordAPI, make_rich_text
80
+
81
+ api = WordAPI("your_template.docx")
82
+
83
+ text = make_rich_text(
84
+ "This text is inserted into the template.",
85
+ BODY_STYLE,
86
+ )
87
+
88
+ image_container = api.new_container()
89
+ image_container.add_image(
90
+ "your_image.png",
91
+ width_cm=8.0,
92
+ align="center",
93
+ )
94
+
95
+ table_container = api.new_container()
96
+ table_container.add_table_by_config(
97
+ {
98
+ "data": [
99
+ ["Name", "Value"],
100
+ ["Example", "123"],
101
+ ]
102
+ }
103
+ )
104
+
105
+ api.render(
106
+ {
107
+ "text": text,
108
+ "image": image_container.subdoc,
109
+ "table": table_container.subdoc,
110
+ },
111
+ "report.docx",
112
+ )
113
+ ```
114
+
115
+ ## Demo Directory
116
+
117
+ The repository includes a runnable demo set in `Demo/`.
118
+
119
+ It uses one shared template file:
120
+
121
+ - `Demo/template.docx`
122
+
123
+ And provides these example scripts:
124
+
125
+ - `Demo/demo1_paragraph.py`
126
+ - `Demo/demo2_container_paragraph.py`
127
+ - `Demo/demo3_container_image_caption.py`
128
+ - `Demo/demo4_container_table_caption.py`
129
+ - `Demo/demo5_container_table_image_caption.py`
130
+ - `Demo/demo6_header_footer.py`
131
+ - `Demo/demo7_styles_in_container.py`
132
+ - `Demo/demo8_all_in_one.py`
133
+
134
+ Run them from the repository root, for example:
135
+
136
+ ```bash
137
+ python Demo/demo1_paragraph.py
138
+ python Demo/demo8_all_in_one.py
139
+ ```
140
+
141
+ Generated files are written to `Demo/output/`.
142
+
143
+ Note: template and demo assets are repository examples. They are not packaged into the published wheel.
144
+
145
+ ## Project Structure
146
+
147
+ ```text
148
+ docxspec
149
+ ├── .github/
150
+ │ └── workflows/
151
+ ├── Demo/
152
+ ├── src/
153
+ │ └── docxspec/
154
+ │ ├── __init__.py
155
+ │ ├── word_api.py
156
+ │ └── word_styles.py
157
+ ├── tests/
158
+ ├── CHANGELOG.md
159
+ ├── CONTRIBUTING.md
160
+ ├── LICENSE
161
+ ├── README.md
162
+ ├── README.zh-CN.md
163
+ └── pyproject.toml
164
+ ```
165
+
166
+ ## Release Automation
167
+
168
+ This repository is prepared for a professional Python package workflow:
169
+
170
+ - **CI** runs lint and tests on push and pull request.
171
+ - **Semantic Release** updates the version, changelog, tag, and GitHub Release.
172
+ - **Trusted Publishing** publishes to PyPI from GitHub Actions without a PyPI API token.
173
+ - **Build artifacts** include both source distribution and wheel.
174
+
175
+ ## Development
176
+
177
+ ```bash
178
+ pip install -e .[dev]
179
+ pytest
180
+ ruff check .
181
+ ```
182
+
183
+ When developing locally, prepare your own `.docx` template files in the repository or project workspace and pass their paths explicitly to `WordAPI`.
184
+
185
+ ## License
186
+
187
+ MIT License. See [LICENSE](https://github.com/Poggi-Tang/docxspec/blob/main/LICENSE).
@@ -0,0 +1,152 @@
1
+ # docxspec
2
+ English | [简体中文](README.zh-CN.md)
3
+
4
+ [![PyPI](https://img.shields.io/pypi/v/docxspec?cacheSeconds=300)](https://pypi.org/project/docxspec/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/docxspec?cacheSeconds=300)](https://pypi.org/project/docxspec/)
6
+ [![License](https://img.shields.io/github/license/Poggi-Tang/docxspec)](https://github.com/Poggi-Tang/docxspec/blob/main/LICENSE)
7
+ [![CI](https://github.com/Poggi-Tang/docxspec/actions/workflows/ci.yml/badge.svg)](https://github.com/Poggi-Tang/docxspec/actions/workflows/ci.yml)
8
+ [![Publish](https://github.com/Poggi-Tang/docxspec/actions/workflows/publish.yml/badge.svg)](https://github.com/Poggi-Tang/docxspec/actions/workflows/publish.yml)
9
+
10
+ `docxspec` is a lightweight Word report generation library built on top of `python-docx`.
11
+
12
+ It provides a small, structured API for generating `.docx` reports from user-supplied templates
13
+ and containerized content blocks. It is suitable for automated test reports, simulation reports,
14
+ and other document-generation workflows.
15
+
16
+ ## Features
17
+
18
+ - Template-based Word report generation
19
+ - Structured content container API
20
+ - Text, image, and table insertion
21
+ - Rich text style helpers
22
+ - Automatic figure and table caption numbering
23
+ - PyPI-ready packaging and CI/CD workflows
24
+
25
+ ## Installation
26
+
27
+ Install from PyPI:
28
+
29
+ ```bash
30
+ pip install docxspec
31
+ ```
32
+
33
+ Or install from source:
34
+
35
+ ```bash
36
+ git clone https://github.com/Poggi-Tang/docxspec.git
37
+ cd docxspec
38
+ pip install -e .
39
+ ```
40
+
41
+ ## Quick Start
42
+
43
+ ```python
44
+ from docxspec import BODY_STYLE, WordAPI, make_rich_text
45
+
46
+ api = WordAPI("your_template.docx")
47
+
48
+ text = make_rich_text(
49
+ "This text is inserted into the template.",
50
+ BODY_STYLE,
51
+ )
52
+
53
+ image_container = api.new_container()
54
+ image_container.add_image(
55
+ "your_image.png",
56
+ width_cm=8.0,
57
+ align="center",
58
+ )
59
+
60
+ table_container = api.new_container()
61
+ table_container.add_table_by_config(
62
+ {
63
+ "data": [
64
+ ["Name", "Value"],
65
+ ["Example", "123"],
66
+ ]
67
+ }
68
+ )
69
+
70
+ api.render(
71
+ {
72
+ "text": text,
73
+ "image": image_container.subdoc,
74
+ "table": table_container.subdoc,
75
+ },
76
+ "report.docx",
77
+ )
78
+ ```
79
+
80
+ ## Demo Directory
81
+
82
+ The repository includes a runnable demo set in `Demo/`.
83
+
84
+ It uses one shared template file:
85
+
86
+ - `Demo/template.docx`
87
+
88
+ And provides these example scripts:
89
+
90
+ - `Demo/demo1_paragraph.py`
91
+ - `Demo/demo2_container_paragraph.py`
92
+ - `Demo/demo3_container_image_caption.py`
93
+ - `Demo/demo4_container_table_caption.py`
94
+ - `Demo/demo5_container_table_image_caption.py`
95
+ - `Demo/demo6_header_footer.py`
96
+ - `Demo/demo7_styles_in_container.py`
97
+ - `Demo/demo8_all_in_one.py`
98
+
99
+ Run them from the repository root, for example:
100
+
101
+ ```bash
102
+ python Demo/demo1_paragraph.py
103
+ python Demo/demo8_all_in_one.py
104
+ ```
105
+
106
+ Generated files are written to `Demo/output/`.
107
+
108
+ Note: template and demo assets are repository examples. They are not packaged into the published wheel.
109
+
110
+ ## Project Structure
111
+
112
+ ```text
113
+ docxspec
114
+ ├── .github/
115
+ │ └── workflows/
116
+ ├── Demo/
117
+ ├── src/
118
+ │ └── docxspec/
119
+ │ ├── __init__.py
120
+ │ ├── word_api.py
121
+ │ └── word_styles.py
122
+ ├── tests/
123
+ ├── CHANGELOG.md
124
+ ├── CONTRIBUTING.md
125
+ ├── LICENSE
126
+ ├── README.md
127
+ ├── README.zh-CN.md
128
+ └── pyproject.toml
129
+ ```
130
+
131
+ ## Release Automation
132
+
133
+ This repository is prepared for a professional Python package workflow:
134
+
135
+ - **CI** runs lint and tests on push and pull request.
136
+ - **Semantic Release** updates the version, changelog, tag, and GitHub Release.
137
+ - **Trusted Publishing** publishes to PyPI from GitHub Actions without a PyPI API token.
138
+ - **Build artifacts** include both source distribution and wheel.
139
+
140
+ ## Development
141
+
142
+ ```bash
143
+ pip install -e .[dev]
144
+ pytest
145
+ ruff check .
146
+ ```
147
+
148
+ When developing locally, prepare your own `.docx` template files in the repository or project workspace and pass their paths explicitly to `WordAPI`.
149
+
150
+ ## License
151
+
152
+ MIT License. See [LICENSE](https://github.com/Poggi-Tang/docxspec/blob/main/LICENSE).
@@ -0,0 +1,102 @@
1
+ [build-system]
2
+ requires = ["setuptools>=80", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "docxspec"
7
+ version = "0.0.1"
8
+ description = "Lightweight Word report generation library based on python-docx"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ authors = [
13
+ { name = "poggio", email = "2322806855@qq.com" }
14
+ ]
15
+ keywords = ["word", "docx", "report", "automation", "python-docx"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Operating System :: OS Independent",
23
+ "Topic :: Office/Business",
24
+ "Topic :: Software Development :: Libraries :: Python Modules"
25
+ ]
26
+ dependencies = [
27
+ "python-docx>=1.1.0",
28
+ "Pillow>=10.0.0",
29
+ "docxtpl>=0.20.2",
30
+ "docxcompose>=1.4.1",
31
+ ]
32
+
33
+ [project.optional-dependencies]
34
+ dev = [
35
+ "build>=1.2.2",
36
+ "pytest>=8.0",
37
+ "pytest-cov>=5.0.0",
38
+ "ruff>=0.11.0",
39
+ "python-semantic-release>=9.15.0"
40
+ ]
41
+
42
+ [project.urls]
43
+ Homepage = "https://github.com/Poggi-Tang/docxspec"
44
+ Repository = "https://github.com/Poggi-Tang/docxspec"
45
+ Issues = "https://github.com/Poggi-Tang/docxspec/issues"
46
+ Changelog = "https://github.com/Poggi-Tang/docxspec/blob/master/CHANGELOG.md"
47
+ Documentation = "https://github.com/Poggi-Tang/docxspec/blob/master/README.md"
48
+
49
+ [tool.setuptools]
50
+ package-dir = {"" = "src"}
51
+ include-package-data = true
52
+
53
+ [tool.setuptools.packages.find]
54
+ where = ["src"]
55
+ namespaces = false
56
+
57
+ [tool.setuptools.package-data]
58
+ docxspec = [
59
+ "py.typed"
60
+ ]
61
+
62
+ [tool.pytest.ini_options]
63
+ minversion = "8.0"
64
+ addopts = "-ra --strict-markers --strict-config"
65
+ testpaths = ["tests"]
66
+
67
+ [tool.ruff]
68
+ line-length = 100
69
+ target-version = "py311"
70
+
71
+ [tool.ruff.lint]
72
+ select = ["E", "F", "I", "B", "UP"]
73
+ ignore = []
74
+
75
+ [tool.coverage.run]
76
+ source = ["src/docxspec"]
77
+ branch = true
78
+
79
+ [tool.coverage.report]
80
+ show_missing = true
81
+ skip_covered = false
82
+
83
+ [tool.semantic_release]
84
+ branch = "master"
85
+ version_toml = ["pyproject.toml:project.version"]
86
+ version_variables = ["src/docxspec/__init__.py:__version__"]
87
+ changelog_file = "CHANGELOG.md"
88
+ build_command = "python -m build"
89
+ dist_path = "dist/"
90
+ upload_to_pypi = false
91
+ upload_to_release = true
92
+ commit_message = "chore(release): {version} [skip ci]"
93
+ tag_format = "v{version}"
94
+ commit_parser = "conventional"
95
+ major_on_zero = false
96
+ allow_zero_version = true
97
+
98
+ [tool.semantic_release.remote]
99
+ name = "origin"
100
+
101
+ [tool.semantic_release.publish]
102
+ dist_glob_patterns = ["dist/*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,34 @@
1
+ # -*- coding: utf-8 -*-
2
+ """Public exports for docxspec."""
3
+
4
+ from .word_api import DocContainer, WordAPI
5
+ from .word_styles import (
6
+ BODY_STYLE,
7
+ CAPTION_STYLE,
8
+ MAIN_STYLE,
9
+ TABLE_BODY_STYLE,
10
+ TABLE_HEADER_STYLE,
11
+ CellStyle,
12
+ TableStyle,
13
+ TextStyle,
14
+ make_rich_text,
15
+ make_table_style,
16
+ )
17
+
18
+ __version__ = "0.0.1"
19
+
20
+ __all__ = [
21
+ "WordAPI",
22
+ "DocContainer",
23
+ "TextStyle",
24
+ "CellStyle",
25
+ "TableStyle",
26
+ "BODY_STYLE",
27
+ "CAPTION_STYLE",
28
+ "MAIN_STYLE",
29
+ "TABLE_BODY_STYLE",
30
+ "TABLE_HEADER_STYLE",
31
+ "make_rich_text",
32
+ "make_table_style",
33
+ "__version__",
34
+ ]