pythonalize 0.0.1__py3-none-any.whl

pythonalize/__init__.py

@@ -0,0 +1,5 @@
+"""Pythonalize: Python 的本地化表示层（简体中文）。"""
+
+__version__ = "0.0.1"
+
+__all__ = ["__version__"]

pythonalize/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m pythonalize`` 入口，委托给 :func:`pythonalize.cli.main`。"""
+
+from .cli import main
+
+raise SystemExit(main())

pythonalize/cli.py

@@ -0,0 +1,168 @@
+"""Pythonalize 的命令行入口。
+
+本模块只负责参数解析与文件调度：把用户请求映射到
+:mod:`pythonalize.normalize`、:mod:`pythonalize.represent` 与
+:mod:`pythonalize.runner` 的既有功能，不复制任何转换核心逻辑。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import tokenize
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+
+from .normalize import normalize
+from .represent import represent
+from .runner import compile_file, normalized_source, read_source, run_file
+
+__all__ = ["main"]
+
+
+def _file_error(path: str, want_ext: Optional[str]) -> Optional[str]:
+    """校验 ``path`` 是否存在、是否为文件、扩展名是否匹配，返回错误消息。"""
+    p = Path(path)
+    if not p.exists():
+        return f"{path} does not exist."
+    if not p.is_file():
+        return f"{path} is not a file."
+    if want_ext is not None and p.suffix != want_ext:
+        return f"{path} must be a {want_ext} file."
+    return None
+
+
+def _read_python_source(path: str) -> str:
+    """按 Python 源码编码 (PEP 263) 读取 ``path``。"""
+    with tokenize.open(path) as f:
+        return f.read()
+
+
+def _write_conversion(
+    path: str,
+    dest_ext: str,
+    source_reader: Callable[[str], str],
+    encoder: Callable[[str], str],
+    yes: bool,
+) -> int:
+    """把 ``path`` 经 ``encoder`` 转换后写到 ``dest_ext`` 目标文件。
+
+    目标用 ``with_suffix`` 派生；已存在时报告错误并返回非零，``yes``
+    也不覆盖。未给 ``-y`` 时交互式询问，仅 ``y``/``Y`` 才以 ``x`` 独占
+    模式创建，拒绝则返回 0。
+    """
+    target = Path(path).with_suffix(dest_ext)
+    if target.exists():
+        print(f"Error: {target} already exists.", file=sys.stderr)
+        return 1
+
+    # 先完成读取与编码，再询问是否创建，避免在用户确认后才做转换准备。
+    content = encoder(source_reader(path))
+
+    if not yes:
+        answer = input(f"Create {target}? [y/N]: ")
+        if answer.lower() != "y":
+            return 0
+
+    try:
+        with target.open("x", encoding="utf-8") as f:
+            f.write(content)
+    except FileExistsError:
+        print(f"Error: {target} already exists.", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    """执行 ``.pthz`` 文件。程序自身异常不被吞掉，直接向外传播。"""
+    err = _file_error(args.file, ".pthz")
+    if err is not None:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    run_file(args.file)
+    return 0
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    """在 stdout 输出 ``.pthz`` 规范化后的源码。"""
+    err = _file_error(args.file, ".pthz")
+    if err is not None:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    print(normalized_source(args.file), end="")
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    """编译 ``.pthz`` 文件；成功打印 ``OK: FILE``。"""
+    err = _file_error(args.file, ".pthz")
+    if err is not None:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    compile_file(args.file)
+    print(f"OK: {args.file}")
+    return 0
+
+
+def _cmd_represent(args: argparse.Namespace) -> int:
+    """把 ``.py`` 转换为 ``.pthz`` (``represent``)。"""
+    err = _file_error(args.file, ".py")
+    if err is not None:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    return _write_conversion(args.file, ".pthz", _read_python_source, represent, args.yes)
+
+
+def _cmd_normalize(args: argparse.Namespace) -> int:
+    """把 ``.pthz`` 转换为 ``.py`` (``normalize``)。"""
+    err = _file_error(args.file, ".pthz")
+    if err is not None:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    return _write_conversion(args.file, ".py", read_source, normalize, args.yes)
+
+
+def _add_run_subparser(subparsers: argparse._SubParsersAction, name: str) -> None:
+    p = subparsers.add_parser(name, help="run a .pthz file")
+    p.add_argument("file", help="path to the .pthz file")
+    p.set_defaults(handler=_cmd_run)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pthz", description="Run or convert Pythonalize sources.")
+    parser.add_argument("--version", action="version", version="%(prog)s 0.0.1")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    _add_run_subparser(subparsers, "run")
+
+    show = subparsers.add_parser("show", help="print normalized source of a .pthz file")
+    show.add_argument("file", help="path to the .pthz file")
+    show.set_defaults(handler=_cmd_show)
+
+    check = subparsers.add_parser("check", help="compile a .pthz file")
+    check.add_argument("file", help="path to the .pthz file")
+    check.set_defaults(handler=_cmd_check)
+
+    represent_parser = subparsers.add_parser("represent", help="convert .py to .pthz")
+    represent_parser.add_argument("file", help="path to the .py file")
+    represent_parser.add_argument("-y", "--yes", action="store_true", help="create without prompting")
+    represent_parser.set_defaults(handler=_cmd_represent)
+
+    normalize_parser = subparsers.add_parser("normalize", help="convert .pthz to .py")
+    normalize_parser.add_argument("file", help="path to the .pthz file")
+    normalize_parser.add_argument("-y", "--yes", action="store_true", help="create without prompting")
+    normalize_parser.set_defaults(handler=_cmd_normalize)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """CLI 入口，返回进程退出码。"""
+    words = list(sys.argv[1:] if argv is None else argv)
+    # 裸首个文件参数 (如 ``pthz FILE``) 视为 ``run FILE``。
+    commands = ("run", "show", "check", "represent", "normalize")
+    if words and words[0] not in commands and not words[0].startswith("-"):
+        words.insert(0, "run")
+    args = _build_parser().parse_args(words)
+    return args.handler(args)

pythonalize/normalize.py

@@ -0,0 +1,46 @@
+"""把简体中文 Pythonalize 表示源码规范化为 canonical Python 源码。
+
+仅对词法层面的 :data:`tokenize.NAME` 令牌做映射：字符串字面量、注释、
+数字以及映射表中不存在的 (未知) 标识符一律保持不变，因此天然支持
+中英混写。
+"""
+
+from __future__ import annotations
+
+import io
+import tokenize
+from typing import Optional
+
+from .scheme import Scheme, load_scheme
+
+__all__ = ["normalize"]
+
+#: 惰性加载一次已校验的 scheme，供 :func:`normalize` 使用。
+_SCHEME: Optional[Scheme] = None
+
+
+def _scheme() -> Scheme:
+    """返回缓存的 :class:`Scheme`，首次调用时通过 :func:`load_scheme` 加载。"""
+    global _SCHEME
+    if _SCHEME is None:
+        _SCHEME = load_scheme()
+    return _SCHEME
+
+
+def normalize(source: str) -> str:
+    """把 ``source`` 中的 Pythonalize 词替换为对应的 Python 词。
+
+    仅替换 :data:`tokenize.NAME` 且命中 ``load_scheme().e2p`` 的令牌；
+    字符串、注释、数字、未知标识符保持不变。
+    """
+    e2p = _scheme().e2p
+
+    result = []
+    for ttype, string, (srow, scol), (erow, ecol), line in tokenize.generate_tokens(
+        io.StringIO(source).readline
+    ):
+        if ttype == tokenize.NAME and string in e2p:
+            string = e2p[string]
+        result.append((ttype, string, (srow, scol), (erow, ecol), line))
+
+    return tokenize.untokenize(result)

pythonalize/represent.py

@@ -0,0 +1,51 @@
+"""把 canonical Python 源码转换回简体中文 Pythonalize 表示源码。
+
+仅对词法层面的 :data:`tokenize.NAME` 令牌做映射：字符串字面量、注释、
+数字以及映射表中不存在的 (未知) 标识符一律保持不变，因此天然支持
+中英混写。
+
+注意：本函数纯按词法替换，内置名称（如 ``print``、``len``）只要命中
+``load_scheme().p2e`` 就会替换成对应的 Pythonalize 词，无法识别变量遮蔽
+（shadowing）等语义层面信息。
+"""
+
+from __future__ import annotations
+
+import io
+import tokenize
+from typing import Optional
+
+from .scheme import Scheme, load_scheme
+
+__all__ = ["represent"]
+
+#: 惰性加载一次已校验的 scheme，供 :func:`represent` 使用。
+_SCHEME: Optional[Scheme] = None
+
+
+def _scheme() -> Scheme:
+    """返回缓存的 :class:`Scheme`，首次调用时通过 :func:`load_scheme` 加载。"""
+    global _SCHEME
+    if _SCHEME is None:
+        _SCHEME = load_scheme()
+    return _SCHEME
+
+
+def represent(source: str) -> str:
+    """把 ``source`` 中的 Python 词替换为对应的 Pythonalize 词。
+
+    仅替换 :data:`tokenize.NAME` 且命中 ``load_scheme().p2e`` 的令牌；
+    字符串、注释、数字、未知标识符保持不变。内置名称按词法替换，
+    无法识别遮蔽。
+    """
+    p2e = _scheme().p2e
+
+    result = []
+    for ttype, string, (srow, scol), (erow, ecol), line in tokenize.generate_tokens(
+        io.StringIO(source).readline
+    ):
+        if ttype == tokenize.NAME and string in p2e:
+            string = p2e[string]
+        result.append((ttype, string, (srow, scol), (erow, ecol), line))
+
+    return tokenize.untokenize(result)

pythonalize/runner.py

@@ -0,0 +1,52 @@
+"""执行 Pythonalize 源码：读取、规范化、编译并运行。
+
+模块只关心从 ``.pthz`` 文件到可执行代码的完整流程：读取 UTF-8 源码、
+用 :mod:`pythonalize.normalize` 转为 canonical Python、编译并在一个独立的全局
+命名空间中执行，不生成任何临时文件。
+"""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Any, Dict
+
+from .normalize import normalize
+
+__all__ = ["read_source", "normalized_source", "compile_file", "run_file"]
+
+
+def read_source(path: str) -> str:
+    """读取 ``path`` 指向的文件（UTF-8），返回其文本内容。"""
+    return pathlib.Path(path).read_text(encoding="utf-8")
+
+
+def normalized_source(path: str) -> str:
+    """读取 ``path`` 的源码并返回 :func:`normalize` 后的 canonical Python。"""
+    return normalize(read_source(path))
+
+
+def compile_file(path: str) -> Any:
+    """把 ``path`` 的规范化源码编译为 code 对象。
+
+    ``filename`` 使用传入的原始 ``path``，以便 traceback / 调试信息指向
+    原始的 ``.pthz`` 文件。
+    """
+    return compile(normalized_source(path), str(path), "exec")
+
+
+def run_file(path: str) -> Dict[str, Any]:
+    """执行 ``path`` 指向的 ``.pthz`` 文件，返回其全局命名空间。
+
+    不生成临时文件：直接 :func:`exec` 编译得到的 code 对象。全局命名空间
+    至少包含 ``__name__ == "__main__"``、``__file__ == str(path)``、
+    ``__package__ is None`` 与 ``__cached__ is None``。
+    """
+    code = compile_file(path)
+    namespace: Dict[str, Any] = {
+        "__name__": "__main__",
+        "__file__": str(path),
+        "__package__": None,
+        "__cached__": None,
+    }
+    exec(code, namespace)
+    return namespace

pythonalize/scheme.py

@@ -0,0 +1,130 @@
+"""Pythonalize 翻译方案（scheme）的加载与校验。
+
+通过 :mod:`importlib.resources` 从已安装包（``pythonalize.schemes``）中读取
+JSON 资源，校验其结构（meta 与 keywords/constants/builtins 均为非空的
+``str -> str`` 映射），并构造统一的 Pythonalize -> Python 合并映射及严格反向
+映射。
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Dict, Mapping
+
+__all__ = ["Scheme", "load_scheme", "default_language"]
+
+#: 默认加载的 scheme 语言标识。
+default_language = "zh-CN"
+
+
+class Scheme:
+    """一个校验通过的 Pythonalize 翻译方案。
+
+    Attributes
+    ----------
+    meta_name / meta_locale / meta_version:
+        scheme 的元数据。
+    keywords / constants / builtins:
+        各分组原始 ``str -> str`` 映射。
+    e2p:
+        合并后的 Pythonalize 词 -> Python 词映射。
+    p2e:
+        严格的反向映射（Python -> Pythonalize），唯一的。
+    """
+
+    def __init__(
+        self,
+        meta_name: str,
+        meta_locale: str,
+        meta_version: str,
+        keywords: Mapping[str, str],
+        constants: Mapping[str, str],
+        builtins: Mapping[str, str],
+    ) -> None:
+        self.meta_name = meta_name
+        self.meta_locale = meta_locale
+        self.meta_version = meta_version
+        self.keywords: Dict[str, str] = dict(keywords)
+        self.constants: Dict[str, str] = dict(constants)
+        self.builtins: Dict[str, str] = dict(builtins)
+        self.e2p: Dict[str, str] = {}
+        self.p2e: Dict[str, str] = {}
+        self._build()
+
+    def _build(self) -> None:
+        """构建合并映射与严格反向映射，Python 值重复时抛出 :class:`ValueError`。"""
+        e2p: Dict[str, str] = {}
+        p2e: Dict[str, str] = {}
+        for group in (self.keywords, self.constants, self.builtins):
+            for e, p in group.items():
+                if p in p2e and p2e[p] != e:
+                    raise ValueError(
+                        f"Python 值 {p!r} 被多个 Pythonalize 词重复映射: "
+                        f"{p2e[p]!r} 与 {e!r}"
+                    )
+                e2p[e] = p
+                p2e[p] = e
+        self.e2p = e2p
+        self.p2e = p2e
+
+    def __repr__(self) -> str:
+        return (
+            f"Scheme(locale={self.meta_locale!r}, version={self.meta_version!r}, "
+            f"words={len(self.e2p)})"
+        )
+
+
+def _validate_mapping(name: str, value: object) -> Dict[str, str]:
+    """校验 ``value`` 是非空的 ``str -> str`` 映射，并返回其副本。"""
+    if not isinstance(value, dict):
+        raise ValueError(f"{name} 必须是一个 str->str 映射（对象）")
+    result: Dict[str, str] = {}
+    for key, item in value.items():
+        if not isinstance(key, str) or not key:
+            raise ValueError(f"{name} 的键必须是非空字符串")
+        if not isinstance(item, str) or not item:
+            raise ValueError(f"{name}[{key!r}] 的值必须是非空字符串")
+        result[key] = item
+    if not result:
+        raise ValueError(f"{name} 不能为空")
+    return result
+
+
+def load_scheme(entry: str = default_language) -> Scheme:
+    """从已安装包加载名为 ``entry`` 的 scheme 并校验。
+
+    ``entry`` 对应资源 ``pythonalize.schemes/<entry>.json``。返回的
+    :class:`Scheme` 已完成 schema 校验，并计算好 ``e2p`` / ``p2e``。
+    """
+    resource = files("pythonalize.schemes").joinpath(f"{entry}.json")
+    raw = json.loads(resource.read_text(encoding="utf-8"))
+
+    if not isinstance(raw, dict):
+        raise ValueError("scheme 顶层必须是一个对象")
+
+    meta = raw.get("meta")
+    if not isinstance(meta, dict):
+        raise ValueError("scheme 缺少 meta 对象（meta 必须是一个对象）")
+    for key in ("name", "locale", "version"):
+        value = meta.get(key)
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"meta.{key} 必须是非空字符串")
+
+    keywords = _validate_mapping("keywords", raw.get("keywords"))
+    constants = _validate_mapping("constants", raw.get("constants"))
+    builtins = _validate_mapping("builtins", raw.get("builtins"))
+
+    if meta["locale"] != entry:
+        raise ValueError(
+            f"meta.locale {meta['locale']!r} 与请求的 entry {entry!r} 不匹配"
+        )
+
+    return Scheme(
+        meta_name=meta["name"],
+        meta_locale=meta["locale"],
+        meta_version=meta["version"],
+        keywords=keywords,
+        constants=constants,
+        builtins=builtins,
+    )

pythonalize/schemes/__init__.py

@@ -0,0 +1,4 @@
+"""翻译方案（scheme）资源包。
+
+每个 ``.json`` 文件描述一种语言的 Pythonalize -> Python 词表。
+"""

pythonalize/schemes/zh-CN.json

@@ -0,0 +1,62 @@
+{
+  "meta": {
+    "name": "Pythonalize 简体中文 Scheme",
+    "locale": "zh-CN",
+    "version": "0.0.1"
+  },
+  "keywords": {
+    "定义": "def",
+    "若": "if",
+    "否则若": "elif",
+    "否则": "else",
+    "返回": "return",
+    "遍历": "for",
+    "只要": "while",
+    "停止": "break",
+    "继续": "continue",
+    "在": "in",
+    "是": "is",
+    "非": "not",
+    "且": "and",
+    "或": "or",
+    "尝试": "try",
+    "如果察觉": "except",
+    "保底": "finally",
+    "报错": "raise",
+    "导入": "import",
+    "从": "from",
+    "作为": "as",
+    "经由": "with",
+    "类": "class",
+    "略过": "pass"
+  },
+  "constants": {
+    "真": "True",
+    "假": "False",
+    "空": "None"
+  },
+  "builtins": {
+    "打印": "print",
+    "长度": "len",
+    "范围": "range",
+    "枚举": "enumerate",
+    "配对": "zip",
+    "总和": "sum",
+    "最小": "min",
+    "最大": "max",
+    "排序": "sorted",
+    "列表": "list",
+    "字典": "dict",
+    "集合": "set",
+    "组": "tuple",
+    "字符串": "str",
+    "整数": "int",
+    "小数": "float",
+    "是或非": "bool",
+    "输入": "input",
+    "打开": "open",
+    "类型": "type",
+    "全部": "all",
+    "任一": "any"
+  }
+}

pythonalize-0.0.1.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: pythonalize
+Version: 0.0.1
+Summary: Pythonalize: a localized representation layer for Python (Simplified Chinese).
+License: MIT License
+        
+        Copyright (c) 2026 Pythonalize contributors
+        
+        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.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Pythonalize
+
+**Pythonalize** 是 Python 的本地化表示层：让你用简体中文写 Python。
+
+它不是新语言，也不是翻译器之外的东西。它只做一件事——把中文写法的
+Python 源码，换成等价的英文 Python 源码，再交给 Python 执行。
+
+- 面向：想用中文阅读/编写 Python 的人，以及用 AI 快速出代码的 **vibe coder**。
+- 它**降低源码的阅读门槛**，但**不会替代 Python 概念学习**——你要理解
+  什么是函数、循环、类，仍是学 Python 本身。
+
+---
+
+## Pythonalize 是什么 / 不是什么
+
+**是：**
+
+- Python 的一个 **本地化表示层**——中文只是 Python 关键字/内置名的另一种写法。
+- 一个用 `tokenize` 做**词法映射**的小工具：把中文 token 换成英文 token。
+
+**不是：**
+
+- ❌ 一门**新语言**。
+- ❌ 一个新的 **runtime / 解释器**。
+- ❌ 一个新的 **VM**。
+- ❌ 一个 **compiler**（它只是把源码换成等价源码，不生成机器码）。
+- ❌ 一个**独立的 package ecosystem**（你不用装另一套包管理器）。
+- ❌ 一个**自然语言编程**系统（它是词法映射，不是理解你的程序意图）。
+
+**黄金规则：** Python 的 **grammar（语法）和 semantics（语义）是唯一标准**。
+Pythonalize 只改变字面写法，完全不改变 Python 的语法与运行语义。
+
+> **Pythonalize does not define program semantics. Python does.**
+
+---
+
+## 中英混写与标识符
+
+- 可以**中英混写**：中文词换英文词，其余一律原样保留。
+- **字符串、注释、数字** 绝不会被替换。
+- **项目自定义的中文 Unicode 标识符**（如函数名、变量名、类名）**不被猜译**，
+  原样保留。Pythonalize 只替换它内置映射表里的那几十个词。
+
+---
+
+## 版本
+
+- `v0.0.1` 目前**仅支持 `zh-CN`**（简体中文）一个语言。
+- 其他语言 / 更多词表将在后续版本加入。
+
+---
+
+## 安装
+
+安装发布版：
+
+```bash
+pip install pythonalize
+```
+
+从 PyPI 安装 `pythonalize` 发布版，执行需要 Python 3.9 及以上。
+
+从源码开发安装（在项目根目录执行）：
+
+```bash
+pip install .
+```
+
+这会从当前源码安装，是开发时用到的方式；执行同样需要 Python 3.9 及以上。
+
+安装后，`pthz` 命令进入 PATH（由 `pyproject.toml` 的 `[project.scripts]` 提供）。
+
+---
+
+## Hello 示例
+
+`examples/hello.pthz`：
+
+```python
+定义 主():
+    打印("你好，世界")
+
+若 __name__ == "__main__":
+    主()
+```
+
+它等价于 `examples/hello.py`：
+
+```python
+def main():
+    print("你好，世界")
+
+if __name__ == "__main__":
+    main()
+```
+
+两个文件**语义等价**，运行都输出：
+
+```text
+你好，世界
+```
+
+---
+
+## 命令
+
+所有命令都是 `pthz` 的子命令。
+
+### 运行（默认）
+
+```bash
+pthz examples/hello.pthz        # 裸文件 = run
+pthz run examples/hello.pthz    # 等价
+```
+
+### 查看规范化结果（推荐先看再跑）
+
+```bash
+pthz show examples/hello.pthz
+```
+
+把 `.pthz` 规范化后的等价 Python 打印到屏幕，方便你**审阅**。
+
+### 语法检查
+
+```bash
+pthz check examples/hello.pthz
+```
+
+只编译、不执行。成功打印 `OK: examples/hello.pthz`。
+
+### 双向转换
+
+**注意：** 目标文件默认是源文件同名的另一后缀（`hello.pthz` ↔ `hello.py`）。
+如果目标**已存在**，命令会拒绝（`-y` 也不会覆盖）。仓库自带的
+`examples/hello.py` 与 `examples/hello.pthz` **同时存在**，因此不要把其中
+一个当另一个的转换目标——先复制到一个**目标初始不存在**的新目录。
+
+下面的示例分成两个相互独立的目录，每个方向只执行一条命令，可整段照抄。
+
+**`.pthz` → `.py`（中文写 → 英文写），用 `from-pthz/`：**
+
+```bash
+mkdir -p from-pthz && cp examples/hello.pthz from-pthz/
+pthz normalize -y from-pthz/hello.pthz      # 创建 from-pthz/hello.py
+```
+
+**`.py` → `.pthz`（英文写 → 中文写），用 `from-py/`：**
+
+```bash
+mkdir -p from-py && cp examples/hello.py from-py/
+pthz represent -y from-py/hello.py        # 创建 from-py/hello.pthz
+```
+
+> 上面用 `-y` 跳过确认、直接创建。去掉 `-y` 会先显示
+> `Create <TARGET>? [y/N]: ` 提示，等你在输入 `y` 或 `Y` 之后才创建。
+
+转换行为：
+
+- 目标文件默认是源文件同名的另一后缀（`hello.pthz` ↔ `hello.py`）。
+- 目标**已存在时拒绝**，只报 `Error: <TARGET> already exists.` 并返回非零。
+- **`-y` 也不会覆盖已有文件**，它只是跳过“是否创建？”的询问。
+- 没有 `-y` 时会询问 `Create <TARGET>? [y/N]: `，只有输入 `y` 或 `Y`
+  才创建；回答其他内容则正常退出（返回 0）。
+
+### 帮助与版本
+
+```bash
+pthz --help
+pthz --version
+```
+
+`pthz --help` 列出全部子命令与参数；`pthz --version` 打印当前版本
+（`pthz 0.0.1`）。
+
+---
+
+## 一个需要知道的坑：内置名遮蔽也会被替换
+
+Pythonalize 是**纯词法映射**，不追踪变量绑定。
+
+也就是说：即使你在代码里把一个内置名（如 `print`、`len`、`range`）
+当普通变量重新赋值了，它的那个名字**依然会被替换**成对应的中文词。
+它**无法识别 shadowing（遮蔽）**。
+
+如果你要遮蔽内置名，请注意：被替换的仍然是那个词法 token。
+
+```python
+# .py 里：把 print 重新赋值，再调用
+print = my_logger        # 这个 print 会被替换成 打印
+print("hi")              # 这个也会被替换成 打印
+```
+
+---
+
+## ⚠️ 安全提示：不是沙箱
+
+**执行 `.pthz` 与执行等价 `.py` 一样不安全。**
+
+- Pythonalize **不是沙箱**，没有隔离能力。
+- 被运行的代码拥有与你完全相同的权限：能读写文件、访问网络、调用系统命令。
+- **运行前**请务必先用 `pthz show` 查看规范化结果、再用 `pthz check`，
+  并**审阅**代码内容，尤其是你从 AI 或其他渠道获得的代码。
+
+---
+
+## 给 AI 生成代码的建议
+
+如果你用 AI 帮你写 Pythonalize 代码：
+
+- 直接告诉它：“用 Pythonalize 写，输出 **`.pthz`**，语法就是 Python，只是把
+  `def/if/for/print` 等词换成了中文对应词。”
+- 让它**先写 `.pthz`**，你再 `pthz show` 检查；或让它**同时给 `.py`**，
+  你用 `pthz represent` 转成 `.pthz` 再运行。
+- ⚠️ 交代它：**不要编造 Pythonalize 不存在的语法**；Pythonalize 只用标准 Python
+  语法，只是关键字/内置名是中文。
+- 让 AI 遵守 `zh-CN` 当前词表（`定义/若/否则若/否则/返回/遍历/只要/停止/
+  继续/在/是/非/且/或/从/作为/类/略过/打印/长度/范围/枚举/总和/最小/最大...
+  等），避免它发明新词。
+- 提醒它：**项目自定义的中文标识符、字符串、注释不会被翻译**，别假设会被猜译。
+- **别让 AI 在没有审阅的情况下直接运行**外部代码——先 `show`/`check` 再看。
+
+---
+
+## License
+
+MIT —— 详见 [`LICENSE`](LICENSE)。

pythonalize-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+pythonalize/__init__.py,sha256=7XMdW4NRg9AJ5XdiLlKuqR5_OlPkewx9RvhNgV2xV9U,119
+pythonalize/__main__.py,sha256=m6bmOhrPyXIihKIKXOH87zTQmtZ8zDbh5Z3LzXcCIPY,132
+pythonalize/cli.py,sha256=3EbIq6UAwYcq1zuLbSGlvNRDD4mJ_9957KrWEMBfRGo,5994
+pythonalize/normalize.py,sha256=ExC8hk_clQSF1C15z3fLHbOryPrqcn4SzcoD3AsOIJs,1413
+pythonalize/represent.py,sha256=_TXuY8qCwvRX0Ys8R165MVw7C3YhnFTWc3IpM8E90VQ,1690
+pythonalize/runner.py,sha256=6RTzjisc7V79HsQDnZvRu--v2LndRxjPfOt7lYYNqMA,1756
+pythonalize/scheme.py,sha256=dm1uAfStMesyIeDeNwT-_x-PvYRGWZoKHQqaV_mO78A,4598
+pythonalize/schemes/__init__.py,sha256=Cd0I3n0NSfqjVzS-kR8exEquFSfQzGblcK9YhUGzy5Y,122
+pythonalize/schemes/zh-CN.json,sha256=_QAm7WYVpksrQXYbadW7axMf1WYX4k5BVjZZVqHaWE8,1236
+pythonalize-0.0.1.dist-info/licenses/LICENSE,sha256=kv85h4RPRAABEGCfsS-XAv8PgmVHaVWBK9aZrseAtw4,1081
+pythonalize-0.0.1.dist-info/METADATA,sha256=kl6wvl1xFMhiLHYPjHksF-kfVy7RutqnAA-lbG6xDQo,8577
+pythonalize-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pythonalize-0.0.1.dist-info/entry_points.txt,sha256=z31X4E5B1I_Vt5N8c-MXu9rVg-2DCbZOqna7Jfub5TM,46
+pythonalize-0.0.1.dist-info/top_level.txt,sha256=7m04orXMDgeOz-2FY5LYkdE9_0iA13FQt2oMj-kgx30,12
+pythonalize-0.0.1.dist-info/RECORD,,

pythonalize-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pythonalize-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pthz = pythonalize.cli:main

pythonalize-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pythonalize contributors
+
+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.

pythonalize-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pythonalize