pixcraft 0.1.0__tar.gz

pixcraft-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include requirements.txt
+recursive-include docs *.md

pixcraft-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: pixcraft
+Version: 0.1.0
+Summary: 本地批量图片处理 CLI 工具——压缩、转格式、改尺寸、去信息，一行命令搞定
+Home-page: https://github.com/your-org/pixcraft
+Author: PixCraft
+Project-URL: Bug Tracker, https://github.com/your-org/pixcraft/issues
+Project-URL: Source Code, https://github.com/your-org/pixcraft
+Keywords: image,compress,convert,resize,cli,batch,webp,avif,exif
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0.0
+Requires-Dist: Pillow>=10.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# PixCraft
+
+**批量处理图片的命令行工具。压缩、转格式、改尺寸、清除元数据，一条命令的事。**
+
+写这个工具的原因很简单——每次要批量压缩图片就得打开 TinyPNG 网页，或者翻出 Photoshop 脚本，太烦了。PixCraft 把这些操作全部搬到了终端里。
+
+---
+
+## 安装
+
+Python 3.10 以上，依赖 Click 和 Pillow，pip 会自动装好。
+
+```bash
+pip install pixcraft
+```
+
+也可以从源码装：
+
+```bash
+git clone https://github.com/your-org/pixcraft.git
+cd pixcraft
+pip install .
+```
+
+---
+
+## 快速开始
+
+五个命令，覆盖最常见的图片处理需求：
+
+```bash
+# 批量压缩到 500KB 以内
+pixcraft compress ./images/ -s 500k
+
+# 整个目录转 WebP
+pixcraft convert ./images/ -t webp
+
+# 等比缩放到 1200 宽
+pixcraft resize hero.jpg -w 1200
+
+# 清除 EXIF/GPS/相机信息
+pixcraft strip ./photos/
+
+# 查看图片详情
+pixcraft info photo.jpg
+```
+
+---
+
+## 命令详解
+
+### pixcraft compress
+
+压缩图片。可以指定质量，也可以指定目标文件大小让工具自己找最佳参数。
+
+```bash
+pixcraft compress <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-q, --quality` | int | `85` | 压缩质量 1-100，越大质量越好，文件也越大 |
+| `-s, --max-size` | str | — | 目标文件大小上限，比如 `500k`、`5mb`。指定后自动二分搜索找最佳质量值 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+| `-f, --format` | str | — | 输出格式（`jpg`/`png`/`webp`/`avif`），不指定就用原格式 |
+| `--no-resize` | flag | `false` | 禁止自动缩小尺寸，只靠降低质量来压缩 |
+
+几个默认行为值得注意：
+
+- `PATH` 可以是单个文件或目录，目录会递归处理
+- 默认把图片最长边缩到 2000px，防止超大尺寸撑爆文件体积
+- 指定 `--max-size` 时用二分搜索找质量值，比你自己试快得多
+- 质量降到最低还是超的话，会自动逐级缩小尺寸（2000px → 1000px → 500px）
+
+### pixcraft convert
+
+JPG、PNG、WebP、AVIF 四种格式互转。
+
+```bash
+pixcraft convert <PATH> -t <TARGET_FORMAT> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-t, --to` | str | **必填** | 目标格式（`jpg`/`png`/`webp`/`avif`） |
+| `-q, --quality` | int | `85` | 输出质量，只对 jpg/webp/avif 生效 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+| `--lossless` | flag | `false` | 无损模式，目前只支持 PNG → WebP |
+
+转换时会做一些自动处理，防止出问题：
+
+- PNG → JPG 会自动填白色背景（透明区域没法往 JPG 里塞）
+- JPG → PNG 直接拒绝，JPG 已经有损了，转 PNG 只是浪费空间
+- PNG → WebP 加 `--lossless` 能保留透明通道
+- 其他方向正常转
+
+### pixcraft resize
+
+四种缩放模式，比 ImageMagick 的参数好记多了。
+
+```bash
+pixcraft resize <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-w, --width` | int | — | 目标宽度，高度自动按比例算 |
+| `-h, --height` | int | — | 目标高度，宽度自动按比例算 |
+| `--fit` | str | — | 适配尺寸如 `1200x630`，图片完整显示，空白处填白 |
+| `--fill` | str | — | 填充尺寸如 `1200x630`，铺满区域，超出居中裁剪 |
+| `--scale` | float | — | 缩放倍数，`0.5` 就是缩小一半 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+
+四种模式：
+
+- `-w` / `-h`：等比缩放。只给一个边就自动算另一边，两个都给就按固定尺寸来
+- `--fit`：把图片塞进指定区域，保持比例，留白不裁剪
+- `--fill`：填满指定区域，保持比例，多出来的裁掉
+- `--scale`：直接按倍数缩放，最简单直接
+
+### pixcraft strip
+
+清除元数据，保护隐私。去掉 EXIF、GPS 坐标、相机型号、拍摄时间。
+
+```bash
+pixcraft strip <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-o, --output` | path | — | 输出目录，不指定就覆盖原文件 |
+
+在社交媒体发照片之前跑一下这个命令，就不用担心别人从 EXIF 里读到你家的 GPS 坐标了。
+
+### pixcraft info
+
+查看图片的详细信息。
+
+```bash
+pixcraft info <PATH>
+```
+
+> 只接受单个文件，不支持目录。
+
+会输出这些内容：文件名、格式、尺寸、文件大小、颜色模式，还有 EXIF 里藏的各种信息（相机型号、拍摄时间、GPS 等）。
+
+---
+
+## 输出示例
+
+批量处理时会逐文件显示状态和体积变化：
+
+```text
+  ✓ hero.jpg (4.2MB -> 0.3MB)
+  ✓ photo.png (2.1MB -> 0.5MB)
+  ✓ banner.webp (1.8MB -> 0.4MB)
+  ✗ broken.jpg (无法读取，已跳过)
+
+  处理完成：3/4 个文件，节省 6.9MB
+```
+
+成功打勾，失败打叉并附原因，最后汇总成功数和节省的总体积。
+
+---
+
+## 测试
+
+```text
+89 passed in 4.24s
+```
+
+---
+
+## 开源协议
+
+MIT License
+
+---
+
+PixCraft —— 给开发者用的命令行版 TinyPNG。

pixcraft-0.1.0/README.md

@@ -0,0 +1,180 @@
+# PixCraft
+
+**批量处理图片的命令行工具。压缩、转格式、改尺寸、清除元数据，一条命令的事。**
+
+写这个工具的原因很简单——每次要批量压缩图片就得打开 TinyPNG 网页，或者翻出 Photoshop 脚本，太烦了。PixCraft 把这些操作全部搬到了终端里。
+
+---
+
+## 安装
+
+Python 3.10 以上，依赖 Click 和 Pillow，pip 会自动装好。
+
+```bash
+pip install pixcraft
+```
+
+也可以从源码装：
+
+```bash
+git clone https://github.com/your-org/pixcraft.git
+cd pixcraft
+pip install .
+```
+
+---
+
+## 快速开始
+
+五个命令，覆盖最常见的图片处理需求：
+
+```bash
+# 批量压缩到 500KB 以内
+pixcraft compress ./images/ -s 500k
+
+# 整个目录转 WebP
+pixcraft convert ./images/ -t webp
+
+# 等比缩放到 1200 宽
+pixcraft resize hero.jpg -w 1200
+
+# 清除 EXIF/GPS/相机信息
+pixcraft strip ./photos/
+
+# 查看图片详情
+pixcraft info photo.jpg
+```
+
+---
+
+## 命令详解
+
+### pixcraft compress
+
+压缩图片。可以指定质量，也可以指定目标文件大小让工具自己找最佳参数。
+
+```bash
+pixcraft compress <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-q, --quality` | int | `85` | 压缩质量 1-100，越大质量越好，文件也越大 |
+| `-s, --max-size` | str | — | 目标文件大小上限，比如 `500k`、`5mb`。指定后自动二分搜索找最佳质量值 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+| `-f, --format` | str | — | 输出格式（`jpg`/`png`/`webp`/`avif`），不指定就用原格式 |
+| `--no-resize` | flag | `false` | 禁止自动缩小尺寸，只靠降低质量来压缩 |
+
+几个默认行为值得注意：
+
+- `PATH` 可以是单个文件或目录，目录会递归处理
+- 默认把图片最长边缩到 2000px，防止超大尺寸撑爆文件体积
+- 指定 `--max-size` 时用二分搜索找质量值，比你自己试快得多
+- 质量降到最低还是超的话，会自动逐级缩小尺寸（2000px → 1000px → 500px）
+
+### pixcraft convert
+
+JPG、PNG、WebP、AVIF 四种格式互转。
+
+```bash
+pixcraft convert <PATH> -t <TARGET_FORMAT> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-t, --to` | str | **必填** | 目标格式（`jpg`/`png`/`webp`/`avif`） |
+| `-q, --quality` | int | `85` | 输出质量，只对 jpg/webp/avif 生效 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+| `--lossless` | flag | `false` | 无损模式，目前只支持 PNG → WebP |
+
+转换时会做一些自动处理，防止出问题：
+
+- PNG → JPG 会自动填白色背景（透明区域没法往 JPG 里塞）
+- JPG → PNG 直接拒绝，JPG 已经有损了，转 PNG 只是浪费空间
+- PNG → WebP 加 `--lossless` 能保留透明通道
+- 其他方向正常转
+
+### pixcraft resize
+
+四种缩放模式，比 ImageMagick 的参数好记多了。
+
+```bash
+pixcraft resize <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-w, --width` | int | — | 目标宽度，高度自动按比例算 |
+| `-h, --height` | int | — | 目标高度，宽度自动按比例算 |
+| `--fit` | str | — | 适配尺寸如 `1200x630`，图片完整显示，空白处填白 |
+| `--fill` | str | — | 填充尺寸如 `1200x630`，铺满区域，超出居中裁剪 |
+| `--scale` | float | — | 缩放倍数，`0.5` 就是缩小一半 |
+| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
+
+四种模式：
+
+- `-w` / `-h`：等比缩放。只给一个边就自动算另一边，两个都给就按固定尺寸来
+- `--fit`：把图片塞进指定区域，保持比例，留白不裁剪
+- `--fill`：填满指定区域，保持比例，多出来的裁掉
+- `--scale`：直接按倍数缩放，最简单直接
+
+### pixcraft strip
+
+清除元数据，保护隐私。去掉 EXIF、GPS 坐标、相机型号、拍摄时间。
+
+```bash
+pixcraft strip <PATH> [OPTIONS]
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-o, --output` | path | — | 输出目录，不指定就覆盖原文件 |
+
+在社交媒体发照片之前跑一下这个命令，就不用担心别人从 EXIF 里读到你家的 GPS 坐标了。
+
+### pixcraft info
+
+查看图片的详细信息。
+
+```bash
+pixcraft info <PATH>
+```
+
+> 只接受单个文件，不支持目录。
+
+会输出这些内容：文件名、格式、尺寸、文件大小、颜色模式，还有 EXIF 里藏的各种信息（相机型号、拍摄时间、GPS 等）。
+
+---
+
+## 输出示例
+
+批量处理时会逐文件显示状态和体积变化：
+
+```text
+  ✓ hero.jpg (4.2MB -> 0.3MB)
+  ✓ photo.png (2.1MB -> 0.5MB)
+  ✓ banner.webp (1.8MB -> 0.4MB)
+  ✗ broken.jpg (无法读取，已跳过)
+
+  处理完成：3/4 个文件，节省 6.9MB
+```
+
+成功打勾，失败打叉并附原因，最后汇总成功数和节省的总体积。
+
+---
+
+## 测试
+
+```text
+89 passed in 4.24s
+```
+
+---
+
+## 开源协议
+
+MIT License
+
+---
+
+PixCraft —— 给开发者用的命令行版 TinyPNG。

pixcraft-0.1.0/docs//344/273/273/345/212/241/346/270/205/345/215/225.md

@@ -0,0 +1,83 @@
+# PixCraft MVP 任务清单
+
+> 基于需求文档 v1.0，按可并行启动维度组织
+
+---
+
+## 第一梯队（可同时启动）
+
+项目骨架搭好后，以下 7 个任务互不依赖，可并行开发：
+
+| # | 任务 | 产出文件 | 说明 |
+|---|------|----------|------|
+| 1 | **项目骨架搭建** | 目录结构、`setup.py`、`requirements.txt`、`__init__.py` | 所有模块的前置依赖 |
+| 2 | **CLI 主入口** | `pixcraft/cli.py` | Click 命令组、参数解析、帮助信息 |
+| 3 | **公共工具模块** | `pixcraft/utils.py` | 文件遍历、图片识别、进度显示、二分搜索算法 |
+| 4 | **压缩模块** | `pixcraft/compress.py` | `compress` 命令，质量压缩 + 目标大小二分搜索 + 自适应缩小尺寸 |
+| 5 | **格式转换模块** | `pixcraft/convert.py` | `convert` 命令，JPG/PNG/WebP/AVIF 互转 + 透明通道处理 |
+| 6 | **尺寸调整模块** | `pixcraft/resize.py` | `resize` 命令，等比/适配(fit)/填充(fill)/倍数缩放 |
+| 7 | **信息清除模块** | `pixcraft/strip.py` | `strip` 命令，EXIF/GPS/相机型号清除 |
+| 8 | **信息查看模块** | `pixcraft/info.py` | `info` 命令，尺寸/大小/格式/EXIF/颜色模式显示 |
+
+---
+
+## 第二梯队（模块就绪后并行启动）
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 9 | **压缩模块测试** | 单文件压缩、批量压缩、max-size 二分搜索正确性 |
+| 10 | **格式转换模块测试** | 各方向转换正确性、透明通道保留、JPG→PNG 报错验证 |
+| 11 | **尺寸调整模块测试** | 等比缩放、fit/fill/scale 参数正确性 |
+| 12 | **信息清除模块测试** | EXIF 清除完整性、非图片文件跳过 |
+| 13 | **信息查看模块测试** | 各格式图片信息读取正确性 |
+| 14 | **边界情况测试** | 损坏图片、超大文件、50 张批量不崩溃、空目录 |
+| 15 | **README 文档** | 使用说明 + Demo GIF + 安装指南 |
+
+---
+
+## 第三梯队（测试通过后启动）
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 16 | **PyInstaller 打包** | 单文件 .exe，目标：不含 Python 环境可运行 |
+| 17 | **PyPI 发布准备** | `setup.py` 完善、版本号、`pip install pixcraft` |
+| 18 | **GitHub 开源发布** | 仓库准备、开源协议(MIT)、推广文章 |
+
+---
+
+## 并行度总览
+
+```
+第一梯队（8 个任务）
+  ├── #1 项目骨架 ──→ 阻塞 #2~#8
+  └── #2~#8 ──────────→ 全部可同时启动（#2/#3 先完成以支撑 #4~#8）
+                           
+第二梯队（7 个任务）  
+  └── #9~#15 ──────────→ 全部可同时启动
+
+第三梯队（3 个任务）
+  └── #16~#18 ──────────→ 顺序执行
+```
+
+## 进度记录
+
+| 任务 | 状态 | 完成日期 |
+|------|------|----------|
+| #1 项目骨架搭建 | ✅ 已完成 | 2026-06-10 |
+| #2 CLI 主入口 | ✅ 已完成 | 2026-06-10 |
+| #3 公共工具模块 | ✅ 已完成 | 2026-06-10 |
+| #4 压缩模块 | ✅ 已完成 | 2026-06-10 |
+| #5 格式转换模块 | ✅ 已完成 | 2026-06-10 |
+| #6 尺寸调整模块 | ✅ 已完成 | 2026-06-10 |
+| #7 信息清除模块 | ✅ 已完成 | 2026-06-10 |
+| #8 信息查看模块 | ✅ 已完成 | 2026-06-10 |
+| #9 压缩模块测试 | ✅ 已完成 | 2026-06-10 |
+| #10 格式转换模块测试 | ✅ 已完成 | 2026-06-10 |
+| #11 尺寸调整模块测试 | ✅ 已完成 | 2026-06-10 |
+| #12 信息清除模块测试 | ✅ 已完成 | 2026-06-10 |
+| #13 信息查看模块测试 | ✅ 已完成 | 2026-06-10 |
+| #14 边界情况测试 | ✅ 已完成 | 2026-06-10 |
+| #15 README 文档 | ✅ 已完成 | 2026-06-10 |
+| #16 PyInstaller 打包 | ✅ 已完成 | 2026-06-11 |
+| #17 PyPI 发布准备 | ⬜ 待开始 | - |
+| #18 GitHub 开源发布 | ⬜ 待开始 | - |