json-resume 1.1.0__tar.gz

json_resume-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

json_resume-1.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+prune tests
+global-exclude __pycache__ *.py[cod]

json_resume-1.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: json-resume
+Version: 1.1.0
+Summary: Strict JSON-to-DOCX resume generator with locale-aware Word layout
+Author: Eric Zhou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Eric-Zhou-0302/JSON-Resume
+Project-URL: Repository, https://github.com/Eric-Zhou-0302/JSON-Resume.git
+Project-URL: Issues, https://github.com/Eric-Zhou-0302/JSON-Resume/issues
+Project-URL: Changelog, https://github.com/Eric-Zhou-0302/JSON-Resume/blob/main/CHANGELOG.md
+Keywords: resume,json,docx,word,cv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-docx==1.2.0
+Requires-Dist: docx2pdf==0.1.8
+Requires-Dist: pypdf==6.10.0
+Dynamic: license-file
+
+<h1 align="center">📄 JSON-Resume</h1>
+
+<p align="center"><strong>Prepare JSON. Generate your resume.</strong></p>
+
+<p align="center">
+  <sub>✦</sub>
+  <strong>Works with</strong>
+  <a href="SKILL.md"><kbd>🤖 AI Agent</kbd></a>
+  <sub>·</sub>
+  <code>Codex</code>
+  <code>OpenClaw</code>
+  <code>WorkBuddy</code>
+  <sub>✦</sub>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white" alt="Python 3.11" />
+  <img src="https://img.shields.io/badge/output-DOCX%20%2B%20PDF-2B579A" alt="DOCX and PDF output" />
+  <a href="SKILL.md"><img src="https://img.shields.io/badge/AI%20Agent-Skill-6E56CF" alt="AI Agent Skill" /></a>
+  <a href="https://github.com/Eric-Zhou-0302/Offer-Rain" title="Open Offer-Rain"><img src="https://img.shields.io/badge/Workflow-JSON--Resume%20%C3%97%20Offer--Rain-6E56CF" alt="JSON-Resume × Offer-Rain workflow" /></a>
+</p>
+
+<p align="center">
+  <a href="#resume-style">Resume style</a> ·
+  <a href="#how-to-use">How to use</a> ·
+  <a href="#project-structure">Project structure</a> ·
+  <a href="#workflow">Workflow</a> ·
+  <a href="#license">License</a> ·
+  <a href="#pair-with-offer-rain">Pair with Offer-Rain</a>
+</p>
+
+<p align="center"><a href="README.md">中文</a> | English</p>
+
+<div align="center">
+  <img src="assets/json-resume-hero.png" width="480" alt="An abstract illustration of structured JSON becoming a professional resume" />
+</div>
+
+---
+
+Writing a resume should not mean hand-tuning Word, copying formatting, or worrying about breaking the last good file. JSON-Resume stores resume content in strict JSON while the generator handles Word styles, bullets, links, and a two-column layout—then produces a composed, restrained DOCX resume.
+
+# Resume style
+
+- Minimal decoration, content first
+- Monochrome and restrained
+- High information density with a clear hierarchy
+- Well suited to finance, academic research, technical roles, and similar applications
+- See the [full style specification](docs/ARCHITECTURE.md#完整样式规范)
+
+<div align="center">
+  <p>Generated resume preview</p>
+  <a href="assets/example/example_resume_en.pdf">
+    <img src="assets/example/example_resume_en.png" width="960" alt="English resume PDF preview; click to open the PDF" />
+  </a>
+  <p>
+    <a href="assets/example/example_resume_en.docx">View the DOCX</a> ·
+    <a href="assets/example/example_resume_en.json">View the JSON</a>
+  </p>
+</div>
+
+# How to use
+
+JSON-Resume offers three ways to work: have an Agent create a resume, generate one from the command line, or call it from a Python script.
+
+## Agent-assisted resume workflow
+
+The project includes `SKILL.md`, which Codex, OpenClaw, WorkBuddy, and other compatible Agents can use to create or render resumes.
+
+- Give an existing JSON file to an Agent and have it render the resume.
+- Give resume materials to an Agent and have it create the resume.
+
+### Install the Skill
+
+Send this directly to your Agent:
+
+```text
+Install this Skill to help me create my resume:
+https://github.com/Eric-Zhou-0302/JSON-Resume
+```
+
+### A better workflow
+
+Do not repeatedly edit the previous resume. And do not cram every experience into one universal resume.
+
+#### Career source
+
+Maintain a complete personal Career Source in Markdown or plain text: education, employment, projects, and other career facts. It is the source material for each resume.
+
+#### Role tailoring
+
+For each application, give the target job description to the Agent. It will use only the facts in the Career Source, foregrounding your most relevant strengths to create the best-fitting resume for that role.
+
+### Agent delivery standard
+
+The Skill does more than put text into Word. It owns the complete delivery path from factual material to the final resume and follows these standards:
+
+- **One-page resume standard:** In professional authoring mode, the Agent selects and refines content for the target role, producing a naturally dense resume of exactly one page. If content is excessive, it removes weaker or repetitive information first; if content is thin, it only adds facts from authorized source materials.
+- **Full acceptance:** The Agent must generate the DOCX and PDF through the CLI, check the actual PDF page count, and inspect every page for clipping, overlap, table alignment, line breaks, characters, and whitespace. Creating files alone is not completion.
+- **Factual boundary:** The Agent uses only materials you provide or explicitly authorize: Career Sources, prior resumes, and project records. It does not invent experience, dates, titles, grades, metrics, skills, or contact details. A job description may guide selection and wording, but is never evidence of personal facts.
+- **File protection:** Without explicit authorization, the Agent does not overwrite existing JSON, DOCX, or PDF files.
+- **When you provide JSON directly:** The Agent only renders it, preserving its content and order without rewriting or removing anything.
+
+## Command line and Python
+
+### Write the JSON
+
+Create a JSON file and fill in your resume content according to the JSON contract. See the [example JSON file](assets/example/example_resume_en.json).
+
+<details>
+<summary><strong>Expand to view the JSON contract</strong></summary>
+
+<br />
+
+| Field | Rule |
+| --- | --- |
+| `locale` | Required: `zh-CN`, `en-US`, `en-GB`, or `en-EU`. It selects paper size only: `en-US` is Letter; the rest are A4. It does not translate content. |
+| `basics` | Must contain exactly `name` and `contacts`. |
+| `contacts` | At least one item. `label` is visible text and `href` is an optional link target; provide complete `mailto:` / `tel:` values yourself. |
+| `sections` | Contains at least one section and renders in JSON order. Each section may contain only `title` and `entries`; `title` must be nonblank and `entries` needs at least one item. |
+| `entries` | Each entry needs at least one nonblank `title`, `position`, `location`, `start_date` / `end_date`, or `bullets`. |
+| `bullets` | Optional; when present, a flat `list[str]` with at least one nonblank string. Nested lists, objects, and hierarchy inferred from prefixes are not supported. |
+
+Dates must be valid `YYYY-MM` values. `end_date` may also use status text such as `Present`; calendar date ranges render as `YYYY.MM - YYYY.MM`.
+
+</details>
+
+### Render the resume
+
+You can generate a DOCX or PDF from a resume JSON in three ways.
+
+#### Run the installed package from the command line
+
+```bash
+pip install json-resume
+json-resume resume.json
+```
+
+#### Render in a Python script
+
+After installing the package, import `render_json_file_to_docx()` to render a resume in a Python script.
+
+```python
+from resume_generator import render_json_file_to_docx
+
+docx_path = render_json_file_to_docx(
+    "resume.json",
+    "resume.docx",
+)
+
+print(docx_path)
+```
+
+#### `main.py` entry point
+
+```bash
+pip install -r requirements.txt
+python main.py resume.json
+```
+
+#### Command-line options
+
+Both `json-resume` and `python main.py` support:
+
+```bash
+-o OUTPUT, --output OUTPUT  # Set the output path and filename
+--pdf                        # Generate a PDF
+--force                      # Replace existing output files
+```
+
+The Python API accepts the corresponding `output_path`, `pdf=True`, and `force=True` arguments.
+
+# Project structure
+
+```text
+JSON-Resume/
+├── README.md                          # Chinese user documentation
+├── README_EN.md                       # English user documentation
+├── CHANGELOG.md                       # Release notes
+├── SKILL.md                           # Built-in Skill for Agents
+├── LICENSE                            # MIT License
+├── MANIFEST.in                        # Source-distribution content boundary
+├── main.py                            # Traditional CLI entry point
+├── pyproject.toml                     # Package metadata, dependencies, and installed command
+├── requirements.txt                   # Python dependencies
+├── assets/
+│   ├── example/                       # Example JSON, DOCX, PDF, and preview images
+│   ├── buy-me-a-coffee.jpg
+│   └── json-resume-hero.png
+├── docs/
+│   └── ARCHITECTURE.md                # Developer architecture documentation
+├── resume_generator/
+│   ├── cli.py                         # Command-line arguments and main flow
+│   ├── validator.py                   # JSON validation and model parsing
+│   ├── renderer.py                    # DOCX content rendering
+│   ├── styles.py                      # Page, style, and table specifications
+│   ├── layout.py                      # Two-column entry layout
+│   ├── helpers.py                     # OOXML, link, and font helpers
+│   ├── config.py                      # Locale and paper configuration
+│   ├── models.py                      # Pure data models
+│   ├── output.py                      # Output-target checks and atomic writes
+│   ├── service.py                     # In-memory and file-level public service APIs
+│   └── pdf.py                         # PDF export and page-count check
+└── tests/                             # Tests
+```
+
+# Workflow
+
+```mermaid
+flowchart TD
+    A[Prepare JSON yourself] --> B[Generate directly with the CLI]
+    B --> C[DOCX]
+    C --> D[Optional PDF]
+
+    E[Career Source + optional JD] --> F[Agent professional authoring]
+    F --> G[Generate JSON]
+    G --> H[CLI generates DOCX and PDF]
+    H --> I[Page-count check + PDF visual review]
+    I --> J[One-page tailored resume]
+
+    K[User provides JSON] --> L[Agent faithful rendering]
+    L --> M[Preserve content and order]
+    M --> H
+```
+
+# Pair with Offer-Rain
+
+JSON-Resume focuses on creating resumes, not sending applications. If you need to apply by email, use [Offer-Rain](https://github.com/Eric-Zhou-0302/Offer-Rain).
+
+# License
+
+[MIT](./LICENSE) @ 2026 Eric Zhou
+
+---
+
+# Buy the author a coffee
+
+<div align="center">
+  <p>
+    If this project helped you finish your first, fifth, or fiftieth resume,
+    <br />
+    consider buying the author a coffee.
+  </p>
+  <p>
+    May your next resume tell your real experience clearly and look great,
+    <br />
+    while my cup gets a small refill of hot Americano.
+  </p>
+  <img src="assets/buy-me-a-coffee.jpg" alt="Buy the author a coffee" width="320" />
+  <p>
+    <sub>Entirely optional. It does not affect features or your ability to keep generating resumes.</sub>
+  </p>
+</div>
+
+---

json_resume-1.1.0/README.md

@@ -0,0 +1,255 @@
+<h1 align="center">📄 JSON-Resume</h1>
+
+<p align="center"><strong>准备 JSON，生成你的简历。</strong></p>
+
+<p align="center">
+  <sub>✦</sub>
+  <strong>支持接入</strong>
+  <a href="SKILL.md"><kbd>🤖 AI Agent</kbd></a>
+  <sub>·</sub>
+  <code>Codex</code>
+  <code>OpenClaw</code>
+  <code>WorkBuddy</code>
+  <sub>✦</sub>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white" alt="Python 3.11" />
+  <img src="https://img.shields.io/badge/output-DOCX%20%2B%20PDF-2B579A" alt="DOCX and PDF output" />
+  <a href="SKILL.md"><img src="https://img.shields.io/badge/AI%20Agent-Skill-6E56CF" alt="AI Agent Skill" /></a>
+  <a href="https://github.com/Eric-Zhou-0302/Offer-Rain" title="打开 Offer-Rain"><img src="https://img.shields.io/badge/Workflow-JSON--Resume%20%C3%97%20Offer--Rain-6E56CF" alt="JSON-Resume × Offer-Rain 工作流" /></a>
+</p>
+
+
+<p align="center">
+  <a href="#简历风格">简历风格</a> ·
+  <a href="#如何使用">如何使用</a> ·
+  <a href="#项目结构">项目结构</a> ·
+  <a href="#工作流">工作流</a> ·
+  <a href="#协议">协议</a> ·
+  <a href="#搭配-offer-rain">搭配 Offer-Rain</a>
+</p>
+
+<p align="center">中文 | <a href="README_EN.md">English</a></p>
+
+<div align="center">
+  <img src="assets/json-resume-hero.png" width="480" alt="结构化 JSON 生成职业简历的抽象插画" />
+</div>
+
+---
+
+写简历的麻烦不该是手调 Word、复制格式和担心改坏旧文件。JSON-Resume 把简历内容写成一份严格的 JSON，生成器负责 Word 的样式、项目符号、链接和双栏排版，最后生成沉稳克制风格的 DOCX 简历。
+
+# 简历风格
+
+- 低装饰、重内容
+- 黑白、克制
+- 高密度、强层级
+- 适用：金融机构、学术研究、技术岗位等
+- 简历所用样式详见 [完整样式规范](docs/ARCHITECTURE.md#完整样式规范)
+
+<div align="center">
+  <p>生成简历预览</p>
+  <a href="assets/example/example_resume_zh.pdf">
+    <img src="assets/example/example_resume_zh.png" width="960" alt="中文简历 PDF 预览，点击打开 PDF" />
+  </a>
+  <p>
+    <a href="assets/example/example_resume_zh.docx">查看对应 DOCX</a> ·
+    <a href="assets/example/example_resume_zh.json">查看对应 JSON</a>
+  </p>
+</div>
+
+# 如何使用
+
+JSON-Resume 提供三种使用方式：让 Agent 制作、通过命令行生成，或在 Python 脚本中调用。
+
+## 面向 Agent 的简历工作流
+
+项目内置 `SKILL.md`，可供 Codex、OpenClaw、WorkBuddy 等 Agent 使用，用于制作或渲染简历。
+
+- 提供已写好的 JSON，交给 Agent 渲染简历
+- 提供简历内容，交给 Agent 制作简历
+
+### 安装 Skill
+
+直接把下面这段话发给 Agent：
+
+```text
+安装这个 Skill，用于帮我制作简历：
+https://github.com/Eric-Zhou-0302/JSON-Resume
+```
+
+### 最佳工作流
+
+不要反复在上一份简历上删改，更不要把所有经历塞进同一份“万能简历”。
+
+#### 个人档案
+
+先维护一份完整的 Markdown 或 txt 格式的个人档案，记录教育、工作、项目等个人信息，作为简历内容的来源。
+
+#### 岗位匹配
+
+每次投递时，再把目标岗位的 JD 交给 Agent，Agent 将严格按照档案的内容，最大化突出个人的优势，为这个岗位定制最贴合的一版简历。
+
+### Agent 的交付标准
+
+项目的 Skill 不只是把文字塞进 Word；它负责从事实材料到最终简历的完整交付，并遵守以下标准：
+
+- **一页简历标准**：在专业创作模式下，Agent 会根据目标岗位筛选和精简内容，最终输出恰好一页、信息密度自然的简历；内容过多时优先删除较弱或重复的信息，内容不足时只从已授权的档案补充事实。
+- **完整验收**：Agent 必须通过项目 CLI 生成 DOCX 和 PDF，先检查 PDF 实际页数，再逐页检查裁切、重叠、表格对齐、换行、字符和留白，不能只生成文件就宣称完成。
+- **事实边界**：Agent 只使用你提供或明确授权读取的档案、旧简历和项目材料；不会捏造经历、日期、职位、成绩、指标、技能或联系方式。JD 只能帮助选择和表达，不能成为个人事实的来源。
+- **文件保护**：未经明确授权，Agent 不会覆盖既有 JSON、DOCX 或 PDF。
+- **直接提供 JSON 时**：Agent 只负责渲染，会保留内容和顺序，不会改写或删减。
+
+## 命令行与 Python
+
+### 填写 JSON
+
+创建一份 JSON 文件，根据 JSON 契约填写简历内容，具体可参考 [示例 JSON 文件](assets/example/example_resume_zh.json)。
+
+<details>
+<summary><strong>展开查看 JSON 契约</strong></summary>
+
+<br />
+
+| 字段 | 规则                                                                                                                       |
+| --- |----------------------------------------------------------------------------------------------------------------------------|
+| `locale` | 必填：`zh-CN`、`en-US`、`en-GB`、`en-EU`。仅决定纸张：`en-US` 为 Letter，其余为 A4；不会翻译内容。                         |
+| `basics` | 必须且只能包含 `name` 与 `contacts`。                                                                                      |
+| `contacts` | 至少一项。`label` 是显示文字，`href` 是可选链接目标；邮箱/电话需要自行写完整 `mailto:` / `tel:`。                          |
+| `sections` | 至少包含一个 section，按 JSON 顺序输出。每个 section 只能有 `title` 和 `entries`；`title` 必须非空白，`entries` 至少一项。 |
+| `entries` | 每个条目至少包含一项非空的`title`、`position`、`location`、`start_date` / `end_date` 或 `bullets`。                         |
+| `bullets` | 可省略；提供时必须是至少包含一条非空字符串的扁平 `list[str]`。不支持嵌套列表、对象或从前缀推断层级。                       |
+
+日期必须是有效的 `YYYY-MM`。`end_date` 也可使用 `Present`、`至今` 等状态文本；真实日期范围会显示成 `YYYY.MM - YYYY.MM`。
+
+</details>
+
+### 渲染简历
+
+简历 JSON 可以通过以下三种方式生成 DOCX 或 PDF。
+
+#### 通过已安装的包在命令行生成
+
+```bash
+pip install json-resume
+json-resume resume.json
+```
+
+#### 脚本内渲染
+
+安装 pip 包后，也可通过导入 `render_json_file_to_docx()` 在 Python 脚本中渲染简历。
+
+```python
+from resume_generator import render_json_file_to_docx
+
+docx_path = render_json_file_to_docx(
+    "resume.json",
+    "resume.docx",
+)
+
+print(docx_path)
+```
+
+#### `main.py` 入口
+
+```bash
+pip install -r requirements.txt
+python main.py resume.json
+```
+
+#### 命令行参数
+
+`json-resume` 与 `python main.py` 都支持以下参数：
+
+```bash
+-o OUTPUT, --output OUTPUT  # 指定输出位置与文件名
+--pdf              # 生成 PDF
+--force            # 覆盖已有文件
+```
+
+Python 接口使用 `output_path`、`pdf=True` 和 `force=True` 传入对应设置。
+
+# 项目结构
+
+```text
+JSON-Resume/
+├── README.md                          # 中文用户文档
+├── README_EN.md                       # English documentation
+├── CHANGELOG.md                       # 版本更新记录
+├── SKILL.md                           # 内置 SKILL，面向 Agent 使用
+├── LICENSE                            # MIT 协议
+├── MANIFEST.in                        # 源码发行包内容边界
+├── main.py                            # CLI 入口
+├── pyproject.toml                     # 包元数据、依赖与安装命令入口
+├── requirements.txt                   # Python 依赖
+├── assets/
+│   ├── example/                       # 示例 JSON、DOCX、PDF 与预览图
+│   ├── buy-me-a-coffee.jpg
+│   └── json-resume-hero.png
+├── docs/
+│   └── ARCHITECTURE.md                # 开发者架构文档
+├── resume_generator/
+│   ├── cli.py                         # 命令行参数与主流程
+│   ├── validator.py                   # JSON 校验与模型解析
+│   ├── renderer.py                    # DOCX 内容渲染
+│   ├── styles.py                      # 页面、样式和表格规范
+│   ├── layout.py                      # 条目双栏版式
+│   ├── helpers.py                     # OOXML、链接和字体工具
+│   ├── config.py                      # locale 与纸张配置
+│   ├── models.py                      # 纯数据模型
+│   ├── output.py                      # 输出目标检查与原子写入
+│   ├── service.py                     # 内存与文件级公共服务接口
+│   └── pdf.py                         # PDF 导出与页数检测
+└── tests/                             # 测试
+```
+
+# 工作流
+
+```mermaid
+flowchart TD
+    A[自行准备 JSON] --> B[CLI 直接生成]
+    B --> C[DOCX]
+    C --> D[可选 PDF]
+
+    E[个人档案 + 可选 JD] --> F[Agent 专业创作]
+    F --> G[生成 JSON]
+    G --> H[CLI 生成 DOCX 和 PDF]
+    H --> I[页数检测 + PDF 视觉验收]
+    I --> J[一页定制简历]
+
+    K[用户提供 JSON] --> L[Agent 忠实渲染]
+    L --> M[保持原文与顺序]
+    M --> H
+```
+
+# 搭配 Offer-Rain
+
+JSON-Resume 专注于制作简历，不负责投递。若你需要以邮箱方式投递你的简历，可使用 [Offer-Rain](https://github.com/Eric-Zhou-0302/Offer-Rain)。
+
+# 协议
+
+[MIT](./LICENSE) @ 2026 Eric Zhou
+
+---
+
+# 请作者喝杯咖啡
+
+<div align="center">
+  <p>
+    如果这个项目帮你完成了第一份、第五份，或者第五十份简历，
+    <br />
+    欢迎请作者喝杯咖啡。
+  </p>
+  <p>
+    愿你的下一份简历，把真实经历讲得清楚、排得漂亮，
+    <br />
+    而我的杯子里也能顺便续上一点热美式。
+  </p>
+  <img src="assets/buy-me-a-coffee.jpg" alt="请作者喝杯咖啡" width="320" />
+  <p>
+    <sub>自愿支持，不影响功能使用，也不影响你继续生成简历。</sub>
+  </p>
+</div>
+
+---