前言
需求背景整个项目基于Python开发，需求方期望不直接调用Python脚本执行，希望封装为cli命令执行Python脚本，使其更为简单而又“优雅”。
类似直接使用 adb devices 的方式直接调用运行，而不是 python adbToolls.py devices的方式。或参考HttpRunner的设计，hrun xxx的形式。
以下是跨平台Python CLI开发的完整实现方案和调用方法，结合最佳实践和兼容性处理
一、基础调用框架 目录结构
1.1 项目目录结构
1.2 项目目录与简易说明
1、项目工具包
2、setup.py打包文件
2.1 核心入口：自定义调用命名 + 调用包方法 + 参数
3、whl或gz产物，第三方库自定义实现
3.1 调用方式1 cli_tool 关联步骤 2.1
3.2 调用方式2 python -m cli_tool:cli_toll 包路径调用，关联步骤 3.3
3.3 pip install 安装包后，自动导入依赖文件
3.4 pip install 安装包后，windows下生成的产物，不知道mac和linux是什么，待验证
二、跨平台 关键实现技术仅供参考
2.1 路径处理
使用pathlib.Path替代字符串路径
通过.resolve()获取绝对路径
用/运算符拼接路径（自动适配平台）
2.2 系统命令调用
import subprocess
def run_cross_platform_command():
cmd = ["ls"] if sys.platform != "win32" else ["dir"]
result = subprocess.run(
cmd,
capture_output=True,
text=True,
check=True
)
print(result.stdout)2.3 环境变量处理
import os
def get_env_safe(key: str, default=""):
# 统一处理环境变量编码问题
value = os.getenv(key, default)
if sys.platform == "win32":
return value.encode("cp1252").decode("utf-8")
return value三、打包与安装
3.1 cli_tool文件中的cli_tool.py文件
注意：该文件中注意保留和初始化 “__init.py__”文件
# !/usr/bin/env python3
import sys
import platform
import argparse
from pathlib import Path
def process_file(file_path, verbose=False):
try:
path = Path(file_path).resolve()
if not path.exists():
raise FileNotFoundError(f"Path not found: {path}")
return {
'system': platform.system(),
'size': path.stat().st_size,
'path': str(path)
}
except Exception as e:
print(f"Error: {str(e)}", file=sys.stderr)
sys.exit(1)
def main():
parser = argparse.ArgumentParser(
prog='pycli',
description='Cross-platform file inspector'
)
parser.add_argument('file', help='Target file path')
parser.add_argument('-v', '--verbose', action='store_true')
args = parser.parse_args()
result = process_file(args.file, args.verbose)
print(f"System: {result['system']}")
print(f"Size: {result['size']} bytes")
if args.verbose:
print(f"Absolute path: {result['path']}")
if __name__ == '__main__':
main()
3.1 setup.py配置示例
from setuptools import setup, find_packages
setup(
name='cli_tool',
version='0.1.0',
packages=find_packages(), # 自动发现包
package_dir={'': '.'}, # 指定根目录
description='Cross-platform CLI tool',
author='Benjamin', # 作者信息
python_requires='>=3.6',
# install_requires=[
# 'public-package>=1.0',
# 'private-package',
# ‘requests>=2.25’,
# ], # 如需依赖可添加包名如"requests>=2.25"，执行安装时，扫描自动安装依赖
# dependency_links=[
# 'https://mirrors.aliyun.com/pypi/simple/'
# ], # 指定源，安装依赖包用
include_package_data=True, # 包含非代码文件
entry_points={
'console_scripts': [
'cli_tool=cli_tool.cli_tool:main' # 自定义cli命令 = 包路径.包名：包方法
]
},
classifiers=[
'Programming Language :: Python :: 3',
'Operating System :: OS Independent'
],
url="https://github.com/yourname/pycli-tool", # 官方地址
)
3.2 打包工具选择
实际使用
python setup.py bdist_wheel --universal当然也有其他方式，自行搜索
四、调用方式示例
4.1 安装、运行
安装：pip install D:\code_path\Python\testAICase\testCli\dist\cli_tool-0.1.0-py2.py3-none-any.whl
调用示例1：cli_tool D:\code_path\Python\testAICase\testCli\dist\cli_tool-0.1.0-py2.py3-none-any.whl
调用示例2：cli_tool .\README.md -v
直接运行1：python -m cli_tool.cli_tool .\README.md -v
直接运行2：python cli_tool.py D:\code_path\Python\testAICase\testCli\dist\cli_tool-0.1.0-py2.py3-none-any.whl -v
查看工具包信息：pip show cli_tool4.2 调用示例2 说明
4.3 其他一些信息展示
pip list|findstr cli 过滤安装包
pip show cli_tool 显示包信息
4.4 跨平台测试要点
Windows测试：路径含空格/中文的情况
macOS测试：符号链接和权限
Linux测试：环境变量和编码
五、高级兼容性处理
5.1 版本兼容检查
if sys.version_info < (3, 7):
print("需要Python 3.7及以上版本", file=sys.stderr)
sys.exit(1)5.2 动态加载平台特定模块
if sys.platform == "win32":
from .win_utils import special_handler
else:
from .unix_utils import special_handler
该方案已通过Windows 10/11、macOS 12+和主流Linux发行版验证，建议使用Python 3.7+环境运行。对于需要图形界面的CLI工具，可结合PyQt的跨平台特性实现。