Metadata-Version: 2.4
Name: scriptforge
Version: 0.1.1
Summary: Generate install.bat and start.bat for Python module projects.
Project-URL: Homepage, https://github.com/install-web/scriptforge
Project-URL: Issues, https://github.com/install-web/scriptforge/issues
Author: install-web
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
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 :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# scriptforge — 一键生成 Python 项目的安装与启动脚本

> 一个简单好用的命令行小工具，帮你瞬间生成 `install.bat`（安装脚本）和 `start.bat`（启动脚本），从此新建项目再也不用手写、复制、改配置。

---

## 一、项目简介与核心功能

### 1.1 这是什么？

`scriptforge` 是一个**命令行工具**（就是在黑色命令行窗口里敲命令用的程序）。你敲一行命令，它就能在当前文件夹里生成两个文件：

| 生成的文件 | 双击后的效果 |
|-----------|-------------|
| `install.bat` | 自动创建一个干净的 Python 虚拟环境，并把你的模块装进去；装完还能自动启动网站 |
| `start.bat`  | 自动激活虚拟环境，启动你的网站/服务，并自动打开浏览器 |

### 1.2 它解决了什么烦恼？

没有这个工具时，每新建一个 Python 项目，你都得：

1. 找以前项目的 `install.bat`、`start.bat` 复制过来；
2. 打开文件，找到顶部的 `CONFIG`（配置）段；
3. 手动改 `MODULE_DIR`（模块名）、`WEB_PORT`（端口）、`WEB_CMD`（启动命令）……
4. 改错一个字母，脚本就跑不起来。

有了 `scriptforge`，**一条命令搞定**，参数填对就行，不用再碰脚本内部。

### 1.3 适合谁用？

- 经常新建 Python 项目、想快速配上"双击即装 / 双击即启"脚本的同学；
- 想把项目分享给别人，让对方"双击就能跑起来"的同学；
- 不想每次都手写 `.bat` 脚本的同学。

---

## 二、环境依赖与系统要求

在开始之前，请确认你的电脑满足以下条件：

| 项目 | 要求 | 怎么检查 |
|------|------|----------|
| 操作系统 | Windows 10 / 11（生成的是 `.bat` 脚本，只在 Windows 上双击运行） | 看桌面右下角"开始"菜单图标 |
| Python | 3.10 或更高版本 | 命令行输入 `python --version` |
| 网络 | 安装工具时需要联网 | 打开浏览器能上网即可 |
| 命令行 | 系统自带的"命令提示符"或"PowerShell" | 按 `Win + R`，输入 `cmd` 回车 |

> 名词解释（给完全零基础的同学）：
> - **命令行 / 命令行窗口**：就是一个黑色（或白底）的文字窗口，你在里面输入命令、按回车，电脑就执行。打开方法：按键盘 `Win + R`，在弹出的小框里输入 `cmd`，按回车。
> - **虚拟环境（venv）**：可以理解成一个"专属小房间"，里面装的 Python 包不会影响电脑上其他项目，互不干扰。

---

## 三、详细的安装与配置步骤

### 第 1 步：确认 Python 已正确安装

打开命令行窗口（`Win + R` → 输入 `cmd` → 回车），输入：

```
python --version
```

如果看到类似下面的输出，说明 Python 已装好：

```
Python 3.11.7
```

> 如果提示"不是内部或外部命令"，说明还没装 Python。请去 [python.org](https://www.python.org/downloads/) 下载安装，安装时**务必勾选 "Add Python to PATH"**（把 Python 加入环境变量），这一步很重要！

### 第 2 步：安装 scriptforge

在命令行里输入下面这条命令并回车：

```
pip install scriptforge
```

稍等几秒，看到 `Successfully installed ...` 就表示装好了。

> 如果你的网络较慢、一直卡住，可以加一个国内镜像加速：
> ```
> pip install scriptforge -i https://pypi.tuna.tsinghua.edu.cn/simple
> ```

<details>
<summary>📦 没有发布到 PyPI 时，从源码安装（点我展开）</summary>

如果 `pip install scriptforge` 提示找不到这个包（说明还没发布到 PyPI），你可以直接从源码安装：

```
cd scriptforge
pip install .
```

或者用"可编辑模式"安装（改了代码立刻生效，适合开发调试）：

```
cd scriptforge
pip install -e .
```

</details>

### 第 3 步：验证安装成功

输入：

```
scriptforge --help
```

看到一段帮助说明（列出所有可用参数），就说明安装成功、可以用了。

```
 Usage: scriptforge [OPTIONS]

 Options:
 --module-dir TEXT          模块目录名（含 pyproject.toml）  [required]
 --host TEXT                Web 监听地址  [default: 127.0.0.1]
 --port INTEGER             Web 端口  [default: 6060]
 --web-cmd TEXT             启动命令，留空则自动推导
 --venv-dir TEXT            虚拟环境目录名  [default: venv]
 --start-web/--no-start-web install 完成后是否启动 Web  [default: start-web]
 --open-browser/--no-open-browser  start 是否自动打开浏览器  [default: open-browser]
 --output-dir PATH          脚本输出目录  [default: .]
 --only TEXT                只生成某一个: install | start
 --help                     Show this message and exit.
```

---

## 四、基础使用方法与示例

### 4.0 先了解：你的项目应该长什么样

`scriptforge` 生成的脚本默认假设你的项目目录是这样的：

```
我的项目/                  ← 项目根目录（脚本生成在这里）
|-- cold_msg/              ← 模块文件夹（里面要有 pyproject.toml）
|   |-- pyproject.toml
|   |-- cold_msg/
|   `-- ...
|-- install.bat            ← scriptforge 生成
`-- start.bat              ← scriptforge 生成
```

关键点：**模块文件夹里必须有一个 `pyproject.toml` 文件**（这是 Python 项目的"说明书"）。

### 4.1 示例 1：最简单的用法（生成两个脚本）

打开命令行，用 `cd` 命令进入你的项目根目录，然后执行：

```
scriptforge --module-dir cold_msg
```

- `--module-dir cold_msg`：告诉它你的模块文件夹叫 `cold_msg`。

运行后你会看到类似下面的输出：

```
generated: install.bat
generated: start.bat
```

这时当前目录下就多了 `install.bat` 和 `start.bat` 两个文件。**默认配置**是：地址 `127.0.0.1`、端口 `6060`、自动打开浏览器、安装完自动启动。

### 4.2 示例 2：换个端口

想让网站跑在 `7000` 端口？加个 `--port`：

```
scriptforge --module-dir cold_msg --port 7000
```

生成的脚本里 `WEB_PORT` 就会变成 `7000`。

### 4.3 示例 3：自己指定启动命令

如果你的启动命令不是默认的 `模块名 web --host ... --port ...`，可以用 `--web-cmd` 完全自定义：

```
scriptforge --module-dir cold_msg --web-cmd "cold-msg web --reload"
```

> 注意：命令里有空格，所以要用双引号 `"` 把整条命令包起来。

### 4.4 示例 4：安装完不要自动启动

有时候你只想先装好，等会儿再手动启动。加 `--no-start-web`：

```
scriptforge --module-dir cold_msg --no-start-web
```

这样 `install.bat` 装完就结束，不会自动启动网站。

### 4.5 示例 5：只生成一个脚本

只想生成 `start.bat`，不要 `install.bat`：

```
scriptforge --module-dir cold_msg --only start
```

同理，`--only install` 只生成安装脚本。

### 4.6 示例 6：生成到别的文件夹

想把脚本生成到别处（比如桌面某个文件夹）：

```
scriptforge --module-dir cold_msg --output-dir D:\我的项目
```

### 4.7 生成之后怎么用？

**双击 `install.bat`**（第一次使用时）：
1. 它会检查 Python 是否可用；
2. 创建一个名叫 `venv` 的虚拟环境（已存在则跳过）；
3. 升级 pip，然后 `pip install .` 把你的模块装进去；
4. 默认装完自动启动网站并打开浏览器。

> 下面的代码块模拟你在命令行双击 `install.bat` 后看到的效果：
> ```
> ============================================================
>   Python Module Install Script
>   project root : D:\我的项目
>   module dir   : D:\我的项目\cold_msg
>   venv dir     : D:\我的项目\venv
>   start web    : 1
> ============================================================
>
> [1/4] check python version ...
> Python 3.11.7
> [2/4] create venv at D:\我的项目\venv ...
> [3/4] upgrade pip ...
> [3/4] install module: pip install "D:\我的项目\cold_msg"
> [4/4] start web server and open browser ...
> ```

**双击 `start.bat`**（已经装过、以后每次启动时）：
1. 激活虚拟环境；
2. 启动你的网站/服务；
3. 默认自动打开浏览器访问 `http://127.0.0.1:6060`。

> 想停止网站：在运行它的命令行窗口里按 `Ctrl + C`。

### 4.8 全部参数一览表

| 参数 | 默认值 | 作用 | 举例 |
|------|--------|------|------|
| `--module-dir` | **必填** | 模块文件夹名（里面要有 pyproject.toml） | `--module-dir cold_msg` |
| `--host` | `127.0.0.1` | 网站监听地址 | `--host 0.0.0.0` |
| `--port` | `6060` | 网站端口号 | `--port 7000` |
| `--web-cmd` | 自动推导 | 启动网站的完整命令 | `--web-cmd "cold-msg web --reload"` |
| `--venv-dir` | `venv` | 虚拟环境文件夹名 | `--venv-dir .venv` |
| `--start-web` / `--no-start-web` | 开启 | install 装完后是否自动启动网站 | `--no-start-web` |
| `--open-browser` / `--no-open-browser` | 开启 | start 启动时是否自动打开浏览器 | `--no-open-browser` |
| `--output-dir` | 当前目录 | 脚本生成到哪个文件夹 | `--output-dir D:\proj` |
| `--only` | 两个都生成 | 只生成其中一个 | `--only start` |

> 小提示：`--start-web` 和 `--open-browser` 这类开关，写它就是"开"，加个 `no-` 前缀就是"关"。例如 `--open-browser`（开浏览器）vs `--no-open-browser`（不开浏览器）。

---

## 五、常见问题解答（FAQ）与故障排除

### 安装类

**Q1：运行 `pip install scriptforge` 报错 "找不到这个包"？**
说明它还没发布到 PyPI。请改用源码安装（见"第三步"里展开的"从源码安装"小节）。

**Q2：`pip install` 一直卡住不动？**
多半是网络慢。换国内镜像：
```
pip install scriptforge -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**Q3：提示 "pip 不是内部或外部命令"？**
说明 Python 没加入环境变量。重新运行 Python 安装包，勾选 **"Add Python to PATH"**，或手动把 Python 的 `Scripts` 目录加到系统环境变量 `PATH` 里。

**Q4：提示 "python 不是内部或外部命令"？**
同 Q3，Python 没装或没加入 PATH。去 [python.org](https://www.python.org/downloads/) 下载安装，勾选 "Add Python to PATH"。

### 使用类

**Q5：运行 `scriptforge --help` 提示"不是内部或外部命令"？**
工具没装好，或没装到当前 Python 里。重新执行 `pip install scriptforge`，确认看到 `Successfully installed`。

**Q6：忘了写 `--module-dir`，报错退出？**
这个参数是**必填**的，不写就会报错。请务必带上，例如 `scriptforge --module-dir cold_msg`。

**Q7：`--only` 后面乱填了一个值，报错？**
`--only` 只接受 `install` 或 `start` 两个值，其他都会报错退出。例如 `--only start`。

**Q8：生成的脚本里 `WEB_CMD` 是怎么来的？**
如果你没写 `--web-cmd`，它会自动拼成：`模块名 web --host 地址 --port 端口`。例如模块叫 `cold_msg`、端口 `6060`，就是 `cold_msg web --host 127.0.0.1 --port 6060`。想完全自定义就用 `--web-cmd`。

### 生成的脚本运行类

**Q9：双击 `install.bat` 提示 "pyproject.toml not found"？**
说明 `--module-dir` 指的文件夹里没有 `pyproject.toml`。请检查：① 文件夹名是否拼对；② 该文件夹里确实有 `pyproject.toml` 这个文件。

**Q10：双击 `install.bat` 提示 "python not found in PATH"？**
电脑上没装 Python，或没加入环境变量。先装 Python 3.10+ 并勾选 "Add Python to PATH"，再重新双击。

**Q11：双击 `start.bat` 提示 "venv not found"？**
说明还没运行过 `install.bat`（虚拟环境还没创建）。请先双击 `install.bat` 完成安装，再双击 `start.bat`。

**Q12：启动网站时报错"端口被占用"？**
说明 `6060`（或你设的端口）已经有别的程序在用。换一个端口重新生成脚本即可：
```
scriptforge --module-dir cold_msg --port 8080
```

**Q13：浏览器没自动打开？**
检查生成时是否用了 `--no-open-browser`。如果没加却没打开，可能是系统默认浏览器设置异常，手动在浏览器地址栏输入 `http://127.0.0.1:6060`（端口换成你设的）即可。

**Q14：想停止正在运行的网站？**
在运行 `install.bat` 或 `start.bat` 的那个命令行窗口里，按 `Ctrl + C` 即可停止。

**Q15：改了参数想重新生成，会覆盖旧脚本吗？**
会。`scriptforge` 默认覆盖已存在的 `install.bat` / `start.bat`，并打印 `generated: ...` 提示。原来的脚本会被替换成新内容。

---

## 六、一句话总结

```
scriptforge --module-dir 你的模块名
```

就这一条，`install.bat` 和 `start.bat` 立刻生成，双击即用。祝使用愉快！🎉
