base-conversion 1.0.1__tar.gz

base_conversion-1.0.1/LICENSE

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

base_conversion-1.0.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: base-conversion
+Version: 1.0.1
+Summary: Exact arbitrary-base (2-62) number conversion: lossless big ints, Fraction-precise decimals, repeating-digit notation
+Author: xiaomaozjj666
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xiaomaozjj666/base-conversion
+Project-URL: Issues, https://github.com/xiaomaozjj666/base-conversion/issues
+Project-URL: Changelog, https://github.com/xiaomaozjj666/base-conversion/blob/main/CHANGELOG.md
+Keywords: base,radix,conversion,numbers,fractions,cli
+Classifier: Development Status :: 6 - Mature
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: setuptools>=69; extra == "dev"
+Dynamic: license-file
+
+# base-conversion
+
+> **⚠️ 本仓库已归档**：进制转换已迁入 [`programming-exercises`](https://github.com/xiaomaozjj666/programming-exercises)（`python|js|cpp/base_converter.*` 三语实现），算法基准并入其 `benchmark/`。本仓库仅保留库源码与基准的历史快照，不再演进——测试与 CI 持续可跑，但不再接受功能变更。
+
+<p align="center">
+  <a href="https://github.com/xiaomaozjj666/base-conversion/actions/workflows/ci.yml"><img src="https://github.com/xiaomaozjj666/base-conversion/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/ruff-linted-261230" alt="Ruff" />
+  <img src="https://img.shields.io/badge/tests-76%20passed-brightgreen" alt="Tests" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+</p>
+
+**任意进制（2-62）精确转换库** — 大整数无精度损失、小数用分数精确算术、循环小数用括号循环节表示并可无损往返。
+
+## 为什么用它
+
+| 能力 | 内置 `int(s, base)` | 本库 |
+|------|---------------------|------|
+| 进制范围 | 2-36 | **2-62**（`0-9A-Za-z`，37 起大小写敏感） |
+| 小数 | ✗ | ✓ **Fraction 精确**（二进制 `"0.1"` ≡ 1/2） |
+| 循环小数 | ✗ | ✓ `1/3` ↔ `"0.(3)"` 无损往返 |
+| 大整数 | ✓ | ✓（同一量级性能，见下） |
+| CLI | ✗ | ✓ `baseconv` 一条命令 |
+
+浮点实现的转换在 `0.1` 这类值上必然引入二进制近似误差；本库全程使用 `int` 与 `fractions.Fraction`，**任何输入的转换结果都是数学上精确的**。
+
+## 安装
+
+```bash
+git clone https://github.com/xiaomaozjj666/base-conversion.git
+cd base-conversion
+python -m pip install .
+```
+
+> 尚未发布到 PyPI；从源码安装（零运行时依赖，仅标准库）。
+
+## 快速开始
+
+```python
+>>> from fractions import Fraction
+>>> from base_conversion import to_base, to_decimal
+>>> to_base(255, 16)
+'FF'
+>>> to_decimal("ff", 16)          # 2-36 进制大小写不敏感
+255
+>>> to_decimal("0.1", 2)          # 精确：不是 0.5 的浮点近似
+Fraction(1, 2)
+>>> to_base(Fraction(1, 3), 10)   # 循环小数 → 括号循环节
+'0.(3)'
+>>> to_decimal("0.(3)", 10)       # 且可无损解析回来
+Fraction(1, 3)
+>>> to_base(10**100 + 7, 62)      # 大整数无损
+'QCyvrY2MJnQFGlUHTCA95Xz8AHOrLuoIO0fuPkHHCcyXy9ytM5N1lqsh'
+```
+
+命令行：
+
+```bash
+baseconv 255 10 16              # → FF
+baseconv -- -FF 16 10           # → -255（位置参数负数用 -- 分隔）
+baseconv -n -FF -f 16 -t 10     # → -255（-n 可直接接收负数值）
+baseconv -n 0.1 -f 2 -t 10      # → 0.5（二进制小数精确转十进制）
+```
+
+## API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `to_decimal` | `(s: str, base: int) → int \| Fraction` | 解析 `base` 进制字符串；支持 `±`、小数点、括号循环节 |
+| `to_base` | `(value: int \| Fraction \| float, base: int) → str` | 渲染为目标进制；非整数 float 拒绝（精度陷阱） |
+| `decimal_to_base` / `base_to_decimal` | 同上 | 旧 API 兼容别名 |
+| `decimal_to_binary` / `binary_to_decimal` | — | 二进制快捷方式 |
+| `decimal_to_hex` / `hex_to_decimal` | — | 十六进制快捷方式（输出大写） |
+
+常量：`BASE_MIN=2`、`BASE_MAX=62`、`DIGITS`（62 字符表）。
+
+### 文法（`to_decimal` 接受的输入）
+
+```
+[sign] digits [ "." digits ] [ "(" digits ")" ]
+```
+
+- 2-36 进制大小写不敏感；37-62 大小写敏感（`'A'`=10、`'a'`=36）；
+- `".5"`、`"5."` 合法，单独的 `"."` 非法；
+- 循环节括号必须收尾、非空、不嵌套：`"0.(3)"`、`"0.1(6)"` 合法，`"0.()"`、`"0.(3"` 非法。
+
+### 错误处理
+
+- 非法字符 / 文法错误 → `ValueError`（信息含具体字符与进制）；
+- 进制越界（非 2-62）→ `ValueError`；非 int 进制或 `bool` → `TypeError`；
+- `to_base` 收到非整数 `float` → `ValueError`（提示改用 `Fraction`；`to_base` 不接受数字字符串）。
+
+## 与内置的性能关系
+
+核心整数路径就是「除基取余 / 乘基累加」，与内置 `int(s, base)`、`format(n, 'x')` 同一数量级——测试含 500 例随机大整数交叉验证（对照内置 `int(s, base)`）与 300 例随机 Fraction 往返性质测试，10^60 量级毫秒级完成。本库的定位差异在**能力**（62 进制、精确小数、循环节）而非速度；极限吞吐场景请直接用内置函数。
+
+## 历史与归档
+
+本仓库早期是三语言（C++ / Python / JS）进制转换 + 查找排序基准的对比实现，2026-09 归档整理后：
+
+- Python 部分重写为本库（2-62 进制、Fraction 精确小数、CLI、76 个测试）；
+- 三语言基准脚本保留在 [`archive/`](archive/)（历史快照，不再维护）；
+- 查找/排序算法练习与多语言题解迁移至 [programming-exercises](https://github.com/xiaomaozjj666/programming-exercises)。
+
+历史 benchmark 实测数据（2026-08-21 本机，三语言算法对比）见 [`docs/images/benchmark.svg`](docs/images/benchmark.svg)。
+
+## 开发
+
+```bash
+python -m pip install -e ".[dev]"
+pytest                 # 76 个测试（含随机交叉验证与往返性质测试）
+ruff check src tests   # 代码检查
+mypy src               # 类型检查
+python -m build        # 构建分发包
+```
+
+CI 在 Python 3.9-3.13 矩阵上运行测试，并执行 lint、类型检查与构建验证。
+
+维护者发布流程见 [docs/RELEASING.md](docs/RELEASING.md)，版本变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## License
+
+[MIT](LICENSE)

base_conversion-1.0.1/README.md

@@ -0,0 +1,123 @@
+# base-conversion
+
+> **⚠️ 本仓库已归档**：进制转换已迁入 [`programming-exercises`](https://github.com/xiaomaozjj666/programming-exercises)（`python|js|cpp/base_converter.*` 三语实现），算法基准并入其 `benchmark/`。本仓库仅保留库源码与基准的历史快照，不再演进——测试与 CI 持续可跑，但不再接受功能变更。
+
+<p align="center">
+  <a href="https://github.com/xiaomaozjj666/base-conversion/actions/workflows/ci.yml"><img src="https://github.com/xiaomaozjj666/base-conversion/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/ruff-linted-261230" alt="Ruff" />
+  <img src="https://img.shields.io/badge/tests-76%20passed-brightgreen" alt="Tests" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+</p>
+
+**任意进制（2-62）精确转换库** — 大整数无精度损失、小数用分数精确算术、循环小数用括号循环节表示并可无损往返。
+
+## 为什么用它
+
+| 能力 | 内置 `int(s, base)` | 本库 |
+|------|---------------------|------|
+| 进制范围 | 2-36 | **2-62**（`0-9A-Za-z`，37 起大小写敏感） |
+| 小数 | ✗ | ✓ **Fraction 精确**（二进制 `"0.1"` ≡ 1/2） |
+| 循环小数 | ✗ | ✓ `1/3` ↔ `"0.(3)"` 无损往返 |
+| 大整数 | ✓ | ✓（同一量级性能，见下） |
+| CLI | ✗ | ✓ `baseconv` 一条命令 |
+
+浮点实现的转换在 `0.1` 这类值上必然引入二进制近似误差；本库全程使用 `int` 与 `fractions.Fraction`，**任何输入的转换结果都是数学上精确的**。
+
+## 安装
+
+```bash
+git clone https://github.com/xiaomaozjj666/base-conversion.git
+cd base-conversion
+python -m pip install .
+```
+
+> 尚未发布到 PyPI；从源码安装（零运行时依赖，仅标准库）。
+
+## 快速开始
+
+```python
+>>> from fractions import Fraction
+>>> from base_conversion import to_base, to_decimal
+>>> to_base(255, 16)
+'FF'
+>>> to_decimal("ff", 16)          # 2-36 进制大小写不敏感
+255
+>>> to_decimal("0.1", 2)          # 精确：不是 0.5 的浮点近似
+Fraction(1, 2)
+>>> to_base(Fraction(1, 3), 10)   # 循环小数 → 括号循环节
+'0.(3)'
+>>> to_decimal("0.(3)", 10)       # 且可无损解析回来
+Fraction(1, 3)
+>>> to_base(10**100 + 7, 62)      # 大整数无损
+'QCyvrY2MJnQFGlUHTCA95Xz8AHOrLuoIO0fuPkHHCcyXy9ytM5N1lqsh'
+```
+
+命令行：
+
+```bash
+baseconv 255 10 16              # → FF
+baseconv -- -FF 16 10           # → -255（位置参数负数用 -- 分隔）
+baseconv -n -FF -f 16 -t 10     # → -255（-n 可直接接收负数值）
+baseconv -n 0.1 -f 2 -t 10      # → 0.5（二进制小数精确转十进制）
+```
+
+## API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `to_decimal` | `(s: str, base: int) → int \| Fraction` | 解析 `base` 进制字符串；支持 `±`、小数点、括号循环节 |
+| `to_base` | `(value: int \| Fraction \| float, base: int) → str` | 渲染为目标进制；非整数 float 拒绝（精度陷阱） |
+| `decimal_to_base` / `base_to_decimal` | 同上 | 旧 API 兼容别名 |
+| `decimal_to_binary` / `binary_to_decimal` | — | 二进制快捷方式 |
+| `decimal_to_hex` / `hex_to_decimal` | — | 十六进制快捷方式（输出大写） |
+
+常量：`BASE_MIN=2`、`BASE_MAX=62`、`DIGITS`（62 字符表）。
+
+### 文法（`to_decimal` 接受的输入）
+
+```
+[sign] digits [ "." digits ] [ "(" digits ")" ]
+```
+
+- 2-36 进制大小写不敏感；37-62 大小写敏感（`'A'`=10、`'a'`=36）；
+- `".5"`、`"5."` 合法，单独的 `"."` 非法；
+- 循环节括号必须收尾、非空、不嵌套：`"0.(3)"`、`"0.1(6)"` 合法，`"0.()"`、`"0.(3"` 非法。
+
+### 错误处理
+
+- 非法字符 / 文法错误 → `ValueError`（信息含具体字符与进制）；
+- 进制越界（非 2-62）→ `ValueError`；非 int 进制或 `bool` → `TypeError`；
+- `to_base` 收到非整数 `float` → `ValueError`（提示改用 `Fraction`；`to_base` 不接受数字字符串）。
+
+## 与内置的性能关系
+
+核心整数路径就是「除基取余 / 乘基累加」，与内置 `int(s, base)`、`format(n, 'x')` 同一数量级——测试含 500 例随机大整数交叉验证（对照内置 `int(s, base)`）与 300 例随机 Fraction 往返性质测试，10^60 量级毫秒级完成。本库的定位差异在**能力**（62 进制、精确小数、循环节）而非速度；极限吞吐场景请直接用内置函数。
+
+## 历史与归档
+
+本仓库早期是三语言（C++ / Python / JS）进制转换 + 查找排序基准的对比实现，2026-09 归档整理后：
+
+- Python 部分重写为本库（2-62 进制、Fraction 精确小数、CLI、76 个测试）；
+- 三语言基准脚本保留在 [`archive/`](archive/)（历史快照，不再维护）；
+- 查找/排序算法练习与多语言题解迁移至 [programming-exercises](https://github.com/xiaomaozjj666/programming-exercises)。
+
+历史 benchmark 实测数据（2026-08-21 本机，三语言算法对比）见 [`docs/images/benchmark.svg`](docs/images/benchmark.svg)。
+
+## 开发
+
+```bash
+python -m pip install -e ".[dev]"
+pytest                 # 76 个测试（含随机交叉验证与往返性质测试）
+ruff check src tests   # 代码检查
+mypy src               # 类型检查
+python -m build        # 构建分发包
+```
+
+CI 在 Python 3.9-3.13 矩阵上运行测试，并执行 lint、类型检查与构建验证。
+
+维护者发布流程见 [docs/RELEASING.md](docs/RELEASING.md)，版本变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## License
+
+[MIT](LICENSE)

base_conversion-1.0.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "base-conversion"
+version = "1.0.1"
+description = "Exact arbitrary-base (2-62) number conversion: lossless big ints, Fraction-precise decimals, repeating-digit notation"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "xiaomaozjj666" }]
+requires-python = ">=3.9"
+keywords = ["base", "radix", "conversion", "numbers", "fractions", "cli"]
+classifiers = [
+    "Development Status :: 6 - Mature",
+    "Intended Audience :: Developers",
+
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/xiaomaozjj666/base-conversion"
+Issues = "https://github.com/xiaomaozjj666/base-conversion/issues"
+Changelog = "https://github.com/xiaomaozjj666/base-conversion/blob/main/CHANGELOG.md"
+
+[project.scripts]
+baseconv = "base_conversion.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.5", "mypy>=1.8", "build>=1.0", "setuptools>=69"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+base_conversion = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# 3.9 兼容的类型写法（from __future__ import annotations 已覆盖注解位置）
+"tests/*" = ["SIM115"]
+
+[tool.mypy]
+# python_version = "3.9" 已删除：mypy ≥2 不再支持 3.9 目标，该行被静默拒绝
+# （死配置）。代码仍保持 3.9 兼容（requires-python = ">=3.9" 不变），
+# 类型检查在 CI 的 3.12 解释器下执行。
+files = ["src"]
+warn_unused_ignores = true
+warn_redundant_casts = true

base_conversion-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

base_conversion-1.0.1/src/base_conversion/__init__.py

@@ -0,0 +1,49 @@
+"""base-conversion — 任意进制（2-62）精确转换库。
+
+核心能力：
+
+- 大整数无精度损失（Python 原生 ``int``）；
+- 小数用 ``Fraction`` 精确算术，循环小数用括号循环节表示并可无损往返
+  （``1/3`` ↔ ``"0.(3)"``）；
+- 2-36 进制大小写不敏感，37-62 大小写敏感（``0-9A-Za-z``）；
+- 提供 ``baseconv`` 命令行入口（``pip install`` 后可用）。
+
+快速上手::
+
+    >>> from base_conversion import to_base, to_decimal
+    >>> to_base(255, 16)
+    'FF'
+    >>> to_decimal("0.1", 2)
+    Fraction(1, 2)
+"""
+
+from base_conversion.converter import (
+    BASE_MAX,
+    BASE_MIN,
+    DIGITS,
+    base_to_decimal,
+    binary_to_decimal,
+    decimal_to_base,
+    decimal_to_binary,
+    decimal_to_hex,
+    hex_to_decimal,
+    to_base,
+    to_decimal,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BASE_MAX",
+    "BASE_MIN",
+    "DIGITS",
+    "__version__",
+    "base_to_decimal",
+    "binary_to_decimal",
+    "decimal_to_base",
+    "decimal_to_binary",
+    "decimal_to_hex",
+    "hex_to_decimal",
+    "to_base",
+    "to_decimal",
+]

base_conversion-1.0.1/src/base_conversion/cli.py

@@ -0,0 +1,129 @@
+"""``baseconv`` 命令行入口。
+
+用法::
+
+    baseconv NUMBER [FROM_BASE] [TO_BASE]     # 位置参数式（基数默认 10）
+    baseconv -n NUMBER -f FROM -t TO           # 选项式（负数输入推荐）
+    baseconv -- -123 10 2                     # ``--`` 分隔符式
+
+输出即目标进制表示：整数为数字串，精确小数为有限位或括号循环节
+（``0.(3)`` 表示 1/3 的十进制循环展开）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+from base_conversion import __version__
+from base_conversion.converter import to_base, to_decimal
+
+# 带符号输入可能以数字、字母、小数点或循环括号开头，如 -123、-FF、-.5。
+_SIGNED_NUMBER = re.compile(r"^[-+](?=[0-9A-Za-z.(])")
+_OPTION_FLAGS = frozenset(
+    {"-h", "--help", "-V", "--version", "-n", "--number", "-f", "--from-base", "-t", "--to-base"}
+)
+
+
+def _is_signed_number(value: str) -> bool:
+    """判断参数是否形如带符号数字，而非 CLI 自身的选项。"""
+    return value not in _OPTION_FLAGS and _SIGNED_NUMBER.match(value) is not None
+
+
+def _normalize_argv(argv: list[str]) -> list[str]:
+    """避免 argparse 将带符号数字误判为选项。
+
+    ``-n``/``--number`` 后的带符号值改写为 ``--number=VALUE``；首个位置参数
+    为带符号值时保留原有兼容行为，自动在其前插入 ``--``。
+    """
+    normalized: list[str] = []
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
+        if arg == "--":
+            normalized.extend(argv[index:])
+            break
+        if (
+            arg in ("-n", "--number")
+            and index + 1 < len(argv)
+            and _is_signed_number(argv[index + 1])
+        ):
+            normalized.append(f"--number={argv[index + 1]}")
+            index += 2
+            continue
+        normalized.append(arg)
+        index += 1
+
+    if normalized and _is_signed_number(normalized[0]):
+        return ["--", *normalized]
+    return normalized
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构建命令行解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="baseconv",
+        description=(
+            "任意进制（2-62）精确转换：大整数无损、小数用分数精确表示、循环小数输出括号循环节。"
+        ),
+        epilog=(
+            "示例:\n"
+            "  baseconv 255 10 16           # → FF\n"
+            "  baseconv -- -FF 16 10        # → -255（位置参数负数用 -- 分隔）\n"
+            "  baseconv -n -FF -f 16 -t 10  # → -255（-n 可直接接收负数值）\n"
+            "  baseconv -n 0.1 -f 2 -t 10   # → 0.5（二进制小数精确转十进制）"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"base-conversion {__version__}",
+        help="显示版本并退出",
+    )
+    parser.add_argument(
+        "number",
+        nargs="?",
+        help="待转换的数字（源进制字符串；负数可用 -- 分隔或用 -n 提供）",
+    )
+    parser.add_argument("from_base", nargs="?", type=int, default=10, help="源进制（默认 10）")
+    parser.add_argument("to_base_pos", nargs="?", type=int, default=10, help="目标进制（默认 10）")
+    parser.add_argument(
+        "-n", "--number", dest="number_opt", help="数字（可直接接收 -FF、-0.1 等负数值）"
+    )
+    parser.add_argument(
+        "-f", "--from-base", dest="from_base_opt", type=int, help="源进制（选项式，优先于位置）"
+    )
+    parser.add_argument(
+        "-t", "--to-base", dest="to_base_opt", type=int, help="目标进制（选项式，优先于位置）"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI 入口：返回 0 成功 / 1 转换错误 / 2 用法错误（argparse 自带）。"""
+    args_list = sys.argv[1:] if argv is None else list(argv)
+    args_list = _normalize_argv(args_list)
+    parser = build_parser()
+    ns = parser.parse_args(args_list)
+
+    number = ns.number_opt if ns.number_opt is not None else ns.number
+    from_base = ns.from_base_opt if ns.from_base_opt is not None else ns.from_base
+    target_base = ns.to_base_opt if ns.to_base_opt is not None else ns.to_base_pos
+
+    if number is None:
+        parser.error("必须提供待转换的数字（位置参数或 -n）")
+
+    try:
+        value = to_decimal(number, from_base)
+        print(to_base(value, target_base))
+    except (ValueError, TypeError) as exc:
+        print(f"baseconv: 错误: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())