tools-alias-cli 0.1.0__tar.gz

tools_alias_cli-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.3
+Name: tools-alias-cli
+Version: 0.1.0
+Summary: Add your description here
+Author: riag
+Author-email: riag <riag@163.com>
+License: Apache License 2.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Dist: mypy>=1.10.0 ; extra == 'dev'
+Requires-Python: >=3.10
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Tools Alias CLI
+
+一个用于管理和运行自定义工具别名的命令行工具，支持环境变量配置。
+
+## 特性
+
+- 📋 **工具管理**：定义自定义工具，包含名称、命令和帮助信息
+- 🌍 **环境变量**：从配置文件加载环境变量，并支持用户路径展开
+- 📝 **字符串模板**：在工具命令中使用 `${VARIABLE}` 语法引用环境变量
+- 🎯 **动态子命令**：工具可作为直接子命令使用
+- 📖 **帮助系统**：内置 help 命令，支持工具特定的帮助信息
+- 📦 **易于安装**：通过 pip 或 uv 安装
+- 📂 **配置目录定制**：通过 TOOLS_ALIAS_DIR 环境变量自定义配置目录位置
+
+## 安装
+
+### 使用 uv
+
+```bash
+uv pip install tools-alias-cli
+```
+
+### 使用 pip
+
+```bash
+pip install tools-alias-cli
+```
+
+## 配置
+
+### 配置文件
+
+默认情况下，工具会在 `~/.tools-alias/config.toml` 查找配置文件。
+
+### 配置目录定制
+
+你可以通过环境变量 `TOOLS_ALIAS_DIR` 来指定配置文件所在的目录：
+
+```bash
+# Linux/Mac
+TOOLS_ALIAS_DIR="~/my-tools-alias" tools-alias-cli list
+
+# Windows
+set TOOLS_ALIAS_DIR="C:\\my-tools-alias" && tools-alias-cli list
+```
+
+如果未设置该环境变量，工具会自动将 `TOOLS_ALIAS_DIR` 设置为默认目录 `~/.tools-alias` 的绝对路径。
+
+### 配置格式
+
+配置文件使用 TOML 格式，结构如下：
+
+```toml
+# 环境变量（可选）
+[ENV]
+HOME_PATH = "~/my-tools"
+CONFIG_PATH = "~/.config/tools-alias"
+USER = "myuser"
+
+# 工具定义（必填）
+[[tool]]
+name = "show-home"
+command = "echo ${HOME_PATH}"
+short_help = "显示用户主目录"
+help = "显示展开后的主目录路径"
+
+[[tool]]
+name = "list-files"
+command = "ls -la"
+short_help = "列出当前目录文件"
+
+[[tool]]
+name = "grep-pattern"
+command = "grep $args *.py"
+short_help = "在 Python 文件中搜索模式"
+```
+
+### 配置选项
+
+#### 环境变量 (`[ENV]`)
+
+- 定义可用于所有工具命令的环境变量
+- 值可以包含用户路径展开（`~` 会被替换为用户主目录）
+- 配置文件中的环境变量会覆盖系统环境变量
+
+#### 工具定义 (`[[tool]]`)
+
+- **name**：工具的唯一标识符（必填）
+- **command**：要执行的命令（必填）
+- **short_help**：帮助输出中显示的简短描述（可选）
+- **help**：详细帮助文本（可选）
+- **help_command**：使用 `help` 命令时执行的帮助命令（可选）
+
+## 使用方法
+
+### 基本命令
+
+```bash
+# 列出所有可用工具
+tools-alias-cli list
+
+# 显示特定工具的帮助信息
+tools-alias-cli help show-home
+
+# 显示所有工具的帮助信息
+tools-alias-cli help
+
+# 使用 run 命令执行工具
+tools-alias-cli run show-home
+
+# 直接作为子命令执行工具
+tools-alias-cli show-home
+```
+
+### 示例
+
+#### 示例 1：列出所有工具
+
+```bash
+$ tools-alias-cli list
+工具别名列表:
+  show-home -> echo C:\Users\user/my-tools ( 显示用户主目录 )
+  list-files -> ls -la ( 列出当前目录文件 )
+  grep-pattern -> grep $args *.py ( 在 Python 文件中搜索模式 )
+```
+
+#### 示例 2：显示所有工具的帮助信息
+
+```bash
+$ tools-alias-cli help
+所有工具别名:
+  show-home - 显示用户主目录
+  list-files - 列出当前目录文件
+  grep-pattern - 在 Python 文件中搜索模式
+```
+
+#### 示例 3：执行工具
+
+```bash
+$ tools-alias-cli show-home
+执行命令: echo C:\Users\user/my-tools 
+C:\Users\user/my-tools
+```
+
+#### 示例 4：带参数执行工具
+
+```bash
+$ tools-alias-cli grep-pattern "import"
+执行命令: grep import *.py 
+__init__.py:import argparse
+__init__.py:import os
+__init__.py:import sys
+__init__.py:from string import Template
+__init__.py:from typing import Dict, List, Optional
+# 处理 Python 3.10 兼容性
+__init__.py:if sys.version_info >= (3, 11):
+__init__.py:    import tomllib
+__init__.py:else:
+__init__.py:    import tomli as tomllib
+```
+
+## 环境变量展开
+
+工具支持两种类型的环境变量处理：
+
+1. **用户路径展开**：环境变量中的 `~` 会被替换为用户的主目录
+2. **字符串模板**：命令中的 `${VARIABLE}` 会被替换为对应的环境变量值
+
+## 开发
+
+### 要求
+
+- Python 3.10+
+- uv（用于开发）
+
+### 设置开发环境
+
+```bash
+# 安装依赖
+uv install
+
+# 以开发模式安装
+uv install -e .
+
+# 运行测试
+uv run python -m pytest
+
+# 运行类型检查
+uv run mypy src/
+
+# 构建包
+uv build
+```
+
+## 许可证
+
+Apache License 2.0

tools_alias_cli-0.1.0/README.md

@@ -0,0 +1,197 @@
+# Tools Alias CLI
+
+一个用于管理和运行自定义工具别名的命令行工具，支持环境变量配置。
+
+## 特性
+
+- 📋 **工具管理**：定义自定义工具，包含名称、命令和帮助信息
+- 🌍 **环境变量**：从配置文件加载环境变量，并支持用户路径展开
+- 📝 **字符串模板**：在工具命令中使用 `${VARIABLE}` 语法引用环境变量
+- 🎯 **动态子命令**：工具可作为直接子命令使用
+- 📖 **帮助系统**：内置 help 命令，支持工具特定的帮助信息
+- 📦 **易于安装**：通过 pip 或 uv 安装
+- 📂 **配置目录定制**：通过 TOOLS_ALIAS_DIR 环境变量自定义配置目录位置
+
+## 安装
+
+### 使用 uv
+
+```bash
+uv pip install tools-alias-cli
+```
+
+### 使用 pip
+
+```bash
+pip install tools-alias-cli
+```
+
+## 配置
+
+### 配置文件
+
+默认情况下，工具会在 `~/.tools-alias/config.toml` 查找配置文件。
+
+### 配置目录定制
+
+你可以通过环境变量 `TOOLS_ALIAS_DIR` 来指定配置文件所在的目录：
+
+```bash
+# Linux/Mac
+TOOLS_ALIAS_DIR="~/my-tools-alias" tools-alias-cli list
+
+# Windows
+set TOOLS_ALIAS_DIR="C:\\my-tools-alias" && tools-alias-cli list
+```
+
+如果未设置该环境变量，工具会自动将 `TOOLS_ALIAS_DIR` 设置为默认目录 `~/.tools-alias` 的绝对路径。
+
+### 配置格式
+
+配置文件使用 TOML 格式，结构如下：
+
+```toml
+# 环境变量（可选）
+[ENV]
+HOME_PATH = "~/my-tools"
+CONFIG_PATH = "~/.config/tools-alias"
+USER = "myuser"
+
+# 工具定义（必填）
+[[tool]]
+name = "show-home"
+command = "echo ${HOME_PATH}"
+short_help = "显示用户主目录"
+help = "显示展开后的主目录路径"
+
+[[tool]]
+name = "list-files"
+command = "ls -la"
+short_help = "列出当前目录文件"
+
+[[tool]]
+name = "grep-pattern"
+command = "grep $args *.py"
+short_help = "在 Python 文件中搜索模式"
+```
+
+### 配置选项
+
+#### 环境变量 (`[ENV]`)
+
+- 定义可用于所有工具命令的环境变量
+- 值可以包含用户路径展开（`~` 会被替换为用户主目录）
+- 配置文件中的环境变量会覆盖系统环境变量
+
+#### 工具定义 (`[[tool]]`)
+
+- **name**：工具的唯一标识符（必填）
+- **command**：要执行的命令（必填）
+- **short_help**：帮助输出中显示的简短描述（可选）
+- **help**：详细帮助文本（可选）
+- **help_command**：使用 `help` 命令时执行的帮助命令（可选）
+
+## 使用方法
+
+### 基本命令
+
+```bash
+# 列出所有可用工具
+tools-alias-cli list
+
+# 显示特定工具的帮助信息
+tools-alias-cli help show-home
+
+# 显示所有工具的帮助信息
+tools-alias-cli help
+
+# 使用 run 命令执行工具
+tools-alias-cli run show-home
+
+# 直接作为子命令执行工具
+tools-alias-cli show-home
+```
+
+### 示例
+
+#### 示例 1：列出所有工具
+
+```bash
+$ tools-alias-cli list
+工具别名列表:
+  show-home -> echo C:\Users\user/my-tools ( 显示用户主目录 )
+  list-files -> ls -la ( 列出当前目录文件 )
+  grep-pattern -> grep $args *.py ( 在 Python 文件中搜索模式 )
+```
+
+#### 示例 2：显示所有工具的帮助信息
+
+```bash
+$ tools-alias-cli help
+所有工具别名:
+  show-home - 显示用户主目录
+  list-files - 列出当前目录文件
+  grep-pattern - 在 Python 文件中搜索模式
+```
+
+#### 示例 3：执行工具
+
+```bash
+$ tools-alias-cli show-home
+执行命令: echo C:\Users\user/my-tools 
+C:\Users\user/my-tools
+```
+
+#### 示例 4：带参数执行工具
+
+```bash
+$ tools-alias-cli grep-pattern "import"
+执行命令: grep import *.py 
+__init__.py:import argparse
+__init__.py:import os
+__init__.py:import sys
+__init__.py:from string import Template
+__init__.py:from typing import Dict, List, Optional
+# 处理 Python 3.10 兼容性
+__init__.py:if sys.version_info >= (3, 11):
+__init__.py:    import tomllib
+__init__.py:else:
+__init__.py:    import tomli as tomllib
+```
+
+## 环境变量展开
+
+工具支持两种类型的环境变量处理：
+
+1. **用户路径展开**：环境变量中的 `~` 会被替换为用户的主目录
+2. **字符串模板**：命令中的 `${VARIABLE}` 会被替换为对应的环境变量值
+
+## 开发
+
+### 要求
+
+- Python 3.10+
+- uv（用于开发）
+
+### 设置开发环境
+
+```bash
+# 安装依赖
+uv install
+
+# 以开发模式安装
+uv install -e .
+
+# 运行测试
+uv run python -m pytest
+
+# 运行类型检查
+uv run mypy src/
+
+# 构建包
+uv build
+```
+
+## 许可证
+
+Apache License 2.0

tools_alias_cli-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "tools-alias-cli"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "riag", email = "riag@163.com" }
+]
+requires-python = ">=3.10"
+license = { text = "Apache License 2.0" }
+dependencies = [
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.10.0",
+]
+
+[project.scripts]
+tools-alias-cli = "tools_alias_cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"

tools_alias_cli-0.1.0/src/tools_alias_cli/__init__.py

@@ -0,0 +1,197 @@
+import argparse
+import os
+import subprocess
+import sys
+from string import Template
+from typing import Dict, List, Optional
+
+# 处理 Python 3.10 兼容性
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+ALIAS_DIR = os.path.expanduser(os.environ.get("TOOLS_ALIAS_DIR", "~/.tools-alias"))
+# 如果环境变量 TOOLS_ALIAS_DIR 不存在，就使用 ALIAS_DIR 的值设置它
+if "TOOLS_ALIAS_DIR" not in os.environ:
+    os.environ["TOOLS_ALIAS_DIR"] = ALIAS_DIR
+# 使用默认配置文件路径
+CONFIG_FILE = os.path.join(ALIAS_DIR, "config.toml")
+
+
+class Tool(object):
+    def __init__(
+        self,
+        name: str,
+        command: str,
+        short_help: str = "",
+        help: str = "",
+        help_command: str = "",
+    ):
+        self.name = name
+        self.command = command
+        self.short_help = short_help
+        self.help = help
+        self.help_command = help_command
+
+
+# 全局环境变量存储
+global_env_vars: Dict[str, str] = {}
+
+
+def load_config() -> Dict[str, Tool]:
+    # 确保配置目录存在
+    if not os.path.exists(ALIAS_DIR):
+        os.makedirs(ALIAS_DIR, exist_ok=True)
+
+    tools: Dict[str, Tool] = {}
+
+    if os.path.exists(CONFIG_FILE):
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+
+        # 加载环境变量
+        env_vars = config.get("ENV", {})
+        if isinstance(env_vars, dict):
+            # 展开环境变量值中的用户路径
+            expanded_env_vars = {
+                key: os.path.expanduser(value) for key, value in env_vars.items()
+            }
+            # 首先将配置文件中的环境变量加载到全局环境变量存储
+            global_env_vars.update(expanded_env_vars)
+            # 然后使用配置文件中的环境变量更新系统环境变量，覆盖已存在的系统环境变量
+            os.environ.update(expanded_env_vars)
+
+        # 加载工具别名
+        tool_configs = config.get("tool", [])
+
+        # 处理工具配置
+        if isinstance(tool_configs, list):
+            for tool_data in tool_configs:
+                if isinstance(tool_data, dict):
+                    # 列表格式: [[tool]]
+                    name = tool_data.get("name", "")
+                    if not name:
+                        continue  # 跳过没有名称的工具
+
+                    command = tool_data.get("command", "")
+                    short_help = tool_data.get("short_help", "")
+                    help_text = tool_data.get("help", "")
+                    help_command = tool_data.get("help_command", "")
+                    tool = Tool(
+                        name=name,
+                        command=command,
+                        short_help=short_help,
+                        help=help_text,
+                        help_command=help_command,
+                    )
+                    tools[name] = tool
+
+    return tools
+
+
+def list_aliases(tools: Dict[str, Tool]) -> None:
+    """列出所有工具别名"""
+    if tools:
+        print("工具别名列表:")
+        for name, tool in tools.items():
+            if tool.short_help:
+                print(f"  {name} -> {tool.command} ( {tool.short_help} )")
+            else:
+                print(f"  {name} -> {tool.command}")
+    else:
+        print("没有定义任何工具别名")
+
+
+def run_alias(tools: Dict[str, Tool], name: str, args: List[str]) -> None:
+    """执行工具别名"""
+    if name in tools:
+        tool = tools[name]
+        # 使用 Template 来处理环境变量替换
+        m = {}
+        m.update(os.environ)
+        m["args"] = " ".join(args)
+        m["args_list"] = args
+        command_template = Template(tool.command)
+        full_command = command_template.substitute(m)
+        print(f"执行命令: {full_command}")
+        subprocess.run(full_command, shell=True, env=os.environ)
+    else:
+        print(f"别名 {name} 不存在")
+
+
+def show_help(tools: Dict[str, Tool], name: Optional[str] = None) -> None:
+    """显示工具别名的帮助信息"""
+    if name is None:
+        # 输出所有工具的帮助信息（只显示name和short_help）
+        if tools:
+            print("所有工具别名:")
+            for tool_name, tool in tools.items():
+                if tool.short_help:
+                    print(f"  {tool_name} - {tool.short_help}")
+                else:
+                    print(f"  {tool_name}")
+        else:
+            print("没有定义任何工具别名")
+    elif name in tools:
+        # 输出指定工具的帮助信息
+        tool = tools[name]
+        print(f"{name}")
+        print(f"{tool.command}")
+
+        if tool.help_command:
+            # 使用 Template 来处理 help_command 环境变量替换
+            help_command_template = Template(tool.help_command)
+            processed_help_command = help_command_template.substitute(os.environ)
+
+            # 生成具体的可执行命令
+            full_command = f"{processed_help_command}"
+            print(f"执行帮助命令: {full_command}")
+            subprocess.run(full_command, shell=True, env=os.environ)
+        elif tool.help:
+            # 如果没有help_command但有help字段，显示帮助信息
+            print(f"详细帮助: {tool.help}")
+    else:
+        print(f"别名 {name} 不存在")
+
+
+def main() -> None:
+    """工具别名管理命令行工具"""
+    # 加载配置
+    tools = load_config()
+
+    parser = argparse.ArgumentParser(description="工具别名管理命令行工具")
+    subparsers = parser.add_subparsers(dest="command", help="可用命令")
+
+    # 列出所有别名命令
+    list_parser = subparsers.add_parser("list", help="列出所有工具别名")
+
+    # 显示别名帮助命令
+    help_parser = subparsers.add_parser("help", help="显示工具别名的帮助信息")
+    help_parser.add_argument(
+        "name", nargs="?", default=None, help="别名名称（可选，不提供则显示所有工具）"
+    )
+
+    # 为每个工具配置动态创建子命令
+    for tool_name, tool in tools.items():
+        tool_parser = subparsers.add_parser(
+            tool_name, help=tool.short_help or f"执行工具 {tool_name}"
+        )
+
+    args, unkown_args = parser.parse_known_args()
+
+    if args.command == "list":
+        list_aliases(tools)
+    elif args.command == "run":
+        run_alias(tools, args.name, unkown_args)
+    elif args.command == "help":
+        show_help(tools, args.name)
+    elif args.command in tools:
+        # 直接执行工具命令
+        run_alias(tools, args.command, unkown_args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

tools_alias_cli-0.1.0/src/tools_alias_cli/test_config.toml

@@ -0,0 +1,3 @@
+[tool]
+ls = "dir"
+git = "git"