Metadata-Version: 2.5
Name: create-promptex-py
Version: 1.1.0
Summary: Scaffold a promptex Python project, plugin or adapter.
Project-URL: Homepage, https://github.com/promptex-ai/promptex
Project-URL: Repository, https://github.com/promptex-ai/promptex
Project-URL: Issues, https://github.com/promptex-ai/promptex/issues
Project-URL: Changelog, https://github.com/promptex-ai/promptex/blob/main/CHANGELOG.md
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# create-promptex-py

Start a [promptex](https://github.com/promptex-ai/promptex) Python project,
plugin or adapter from the starter templates bundled with this package, or add
promptex to a project you already have.

```console
uvx create-promptex-py my-prompts   # new project in ./my-prompts
uvx create-promptex-py .            # add promptex to the current directory
```

`uvx` runs the latest release without installing it first.

After that, declare and install the SDK, then build:

```console
uv add promptex-py
uv run promptex build --install
```

## 建立模式與初始化模式

create 依目標目錄自動選模式，輸出的第一行說明選了哪一種：

- 目標不存在，或第一層只有下表的項目時，走建立模式，開一個新專案。
- 其他情況走初始化模式，在原資料夾加入 promptex。初始化模式只支援 `project` 範本，
  `plugin` 與 `adapter` 遇到這種資料夾會以結束碼 2 拒絕。

| 分組 | 不影響模式判斷的項目 |
| :--- | :--- |
| macOS（不分大小寫） | `.DS_Store`、`._*`、`.localized`、`.Spotlight-V100`、`.Trashes`、`.fseventsd`、`.TemporaryItems` |
| Windows（不分大小寫） | `Thumbs.db`、`desktop.ini`、`ehthumbs.db`、`$RECYCLE.BIN`、`System Volume Information` |
| Linux | `.directory`、`.Trash-*`、`.fuse_hidden*`、`.nfs*`、`lost+found` |
| 版本控制與倉庫 | `.git`、`.gitignore`、`.gitattributes`、`.gitkeep`、`.hg`、`.hgignore`、`.svn`、`LICENSE`、`README.md`、`.github` |
| 編輯器與 AI 工具 | `.vscode`、`.idea`、`*.iml`、`.zed`、`.cursor`、`.claude` |

兩種模式寫入時都逐檔判斷，既有檔一律不覆寫：

| 情況 | 處理 |
| :--- | :--- |
| 已有 `promptex.config.ts`、`.py` 或 `.rs` | 判定已初始化，什麼都不寫，結束碼 0 |
| 已有 `pyproject.toml` | 內容不動，`promptex-py` 依賴由你用 `uv add promptex-py` 加 |
| 其他同名的範本檔 | 跳過並列出。`prompts/` 已存在時整個跳過 |
| `.gitignore` | 不存在就建立。存在就在尾端追加 promptex 區塊，已有區塊的標記行就跳過 |
| `README.md` | 只在建立模式寫出，已存在仍跳過 |
| git | 目標在任何 git 工作樹內（含上層資料夾）就不 `git init`。兩種模式都不自動 commit |
| 寫到一半失敗 | 只移除這次新建的檔案與資料夾，既有檔不動 |

目標本身是符號連結或檔案時，以結束碼 2 拒絕。目標裡的符號連結不跟隨，連到外部的
檔案不會被寫到。

## 旗標

每個問題都有對應的旗標，可以不互動執行：

```console
uvx create-promptex-py my-prompts --template project --name my-prompts --no-git --yes
```

| Flag | Meaning |
| :--- | :--- |
| `--template <t>` | `project`（消費專案）、`plugin`、`adapter`。初始化模式只收 `project` |
| `--name <n>` | kebab-case 名稱；預設取目標目錄名正規化 |
| `--source <p>` | 改讀本地模板目錄（含各 `*-starter` 的那一層），開發模板時用 |
| `--git` / `--no-git` | 是否 `git init`；預設是。在既有 git 工作樹內一律略過。給 `--git` 但沒裝 git 時報錯，沒給時靜默略過 |
| `--install` | 鷹架後直接 `uv sync`；預設只印下一步 |
| `--force` | 覆寫與範本同名的既有檔。不清空資料夾，也不動 `pyproject.toml`、`.gitignore` 與設定檔 |
| `--dry-run` | 列出會建立、覆寫、追加、跳過的檔，不寫入 |
| `--json` | 搭配 `--dry-run`，在 stdout 輸出一份 JSON |
| `--yes` | 跳過互動，全部取預設值；不代表同意覆寫 |
| `--locale <l>` | 訊息與範例資源的語系：`en`（預設）或 `zh-Hant` |

沒有終端機、帶 `--yes`，或環境變數 `CI` 為真時不提問，全部取預設值。

## 機器可讀的試跑結果

`--dry-run --json` 在 stdout 輸出一行 JSON，欄位與另兩個 create 套件
（create-promptex-js、create-promptex-rs）相同，只有 `package` 與 `language` 不同：

```json
{"formatVersion":"1.1","package":{"name":"create-promptex-py","version":"1.0.1"},"language":"python",
 "mode":"init","alreadyInitialized":false,"existingConfig":null,"target":"/work/app",
 "template":"project","name":"app",
 "files":{"create":["promptex.config.py","prompts/example.py","prompts/example_skill.py"],
          "overwrite":[],"append":[".gitignore"],
          "skip":[{"path":"README.md","reason":"init-mode"},{"path":"pyproject.toml","reason":"manifest-kept"}]},
 "git":{"init":false,"reason":"inside-worktree"}}
```

| 欄位 | 內容 |
| :--- | :--- |
| `mode` | `create` 或 `init` |
| `alreadyInitialized`、`existingConfig` | 已有 promptex 設定檔時為 `true` 與那個檔名，`files` 四個清單都是空的 |
| `files.create`、`files.overwrite`、`files.append` | 會建立、覆寫（只在 `--force` 時出現）、追加的相對路徑 |
| `files.skip` | 跳過的路徑與原因：`exists`、`manifest-kept`、`example-dir-exists`、`init-mode`、`marker-present`、`symlink`、`blocked` |
| `git` | `init` 是否會執行 `git init`；不執行時 `reason` 是 `inside-worktree`、`disabled`、`unavailable` 或 `already-initialized` |

失敗時 stdout 是一份錯誤 JSON，stderr 另寫一行同文的訊息：

```json
{"formatVersion":"1.1","error":{"code":"USAGE_TEMPLATE_NEEDS_EMPTY_DIR","message":"…","details":{"template":"plugin","path":"/work/app","entries":["src"]}}}
```

結束碼是 0 成功（含已初始化）、1 執行失敗、2 用法錯誤。程式只比對 `error.code`：
`USAGE_` 開頭是呼叫本身不對，`RUN_` 開頭是執行失敗。

## 語系與模板

語系未以 `--locale` 指定時，依序讀 `PROMPTEX_LOCALE`、`LANGUAGE`、`LC_ALL`、
`LC_MESSAGES`、`LANG`，都沒有就用英文；`LC_ALL=C` 意為關掉在地化。`zh-TW`、
`zh-HK`、`zh-MO` 與 `zh-Hant-*` 都對到 `zh-Hant`。它同時決定鋪出來的範例資源
用哪個語系寫（[ADR-030](https://github.com/promptex-ai/ssot)）：那份內容從產出
當下起就歸你，框架不再改寫它。plugin 與 adapter 骨架裡教你怎麼填的註解維持英文。

模板隨本套件一起發布，鷹架時不需要網路，每個版本具現化的都是它發布時的模板。
`{{promptexVersion}}` 於鷹架當下以本套件版本填入，三套件與 SDK 同版發布。

`promptex init` 已棄用，2.0 移除。它能做的事改由本工具的初始化模式處理。
